[Clinton6801]

Closes #152
Closes #153
Closes #154
Closes #158

feat: establish shared network layer with typed environment configuration

Overview

This PR consolidates four key feature branches into a unified architecture that establishes the foundation for the Stellar Streams protocol. It introduces a centralized, type-safe configuration system, extends the core network layer, and adds practical examples for developers.

What's Included

1. Core Network Layer (feat/core-network-layer)

• Introduces @stellar-starter-kit/core package as a shared network configuration hub
• Pre-configured network registry for local, testnet, and mainnet with RPC URLs, Horizon endpoints, and passphrases
• Implements resolveConfig() function for environment-driven configuration
• Centralized error handling with ConfigResolutionError
• Comprehensive unit tests (48 tests) covering all resolution and validation scenarios
• Full TypeScript support with exported types

Files Added:

• packages/core/ (new package)
• packages/core/src/config.ts - Configuration resolution logic
• packages/core/src/networks.ts - Network registry definitions
• packages/core/src/config.test.ts - Comprehensive test suite
• packages/core/README.md - Complete API documentation

2. Typed Environment Configuration (feat/config-typed-environment-parsing)

• Introduces @stellar-starter-kit/config package for structured environment variable parsing
• Type-safe validation of environment configuration at runtime
• Clear error reporting with field-level validation feedback
• Updates dashboard pages (escrow, streams) to use typed config
• Eliminates hardcoded configuration values and environment variable inconsistencies

Files Updated:

• apps/web/src/app/escrow/page.tsx - Migrated to parseEnvironment()
• apps/web/src/app/streams/page.tsx - Migrated to parseEnvironment()

Merge Conflicts Resolved:

• Chose typed parseEnvironment() approach as the canonical configuration pattern
• Both pages now use structured config validation

3. Basic Payment Example (feat/basic-payment-example)

• Adds a runnable example demonstrating payment flows using Stellar
• Located in examples/basic-payment/
• Includes TypeScript source with detailed comments
• Complete environment configuration template
• Ready-to-use for developers learning the SDK

Files Added:

• examples/basic-payment/src/index.ts - Example implementation
• examples/basic-payment/.env.example - Configuration template
• examples/basic-payment/README.md - Usage guide

4. Release and Changeset Workflow (docs/release-and-changeset-workflow)

• Comprehensive release process documentation
• Changesets workflow guide with practical examples
• Automated release pipeline explanation
• Troubleshooting guide for common issues
• CHANGELOG management best practices

Files Added:

• docs/releasing.md - Complete release documentation
• CONTRIBUTING.md - Updated with release guidelines

Key Benefits

✅ Centralized Configuration - Single source of truth for network settings
✅ Type Safety - Full TypeScript support with validation at runtime
✅ Developer Experience - Clear error messages and comprehensive documentation
✅ Reduced Duplication - Eliminates hardcoded URLs and passphrases across packages
✅ Release Automation - Standardized release process with changesets
✅ Learning Resources - Runnable examples for developers

Testing & Validation

• ✅ All 48 unit tests in @stellar-starter-kit/core pass
• ✅ Configuration validation tests cover:
  • Default network selection
  • Environment variable overrides
  • Passphrase validation and mismatch detection
  • Error handling and messaging
  • Complex override scenarios
• ✅ Dashboard pages tested with new configuration system
• ✅ Build completes successfully across all packages

Integration Notes

For Dashboard Developers

The escrow and streams pages now use:

const envResult = parseEnvironment();
if (!envResult.success) {
  throw new Error('Environment configuration invalid');
}
const { config } = envResult;
const rpcUrl = config.sorobanRpcUrl;
const passphrase = config.networkPassphrase;
For Package Authors
Use the core package for configuration:

typescript

import { resolveConfig } from '@stellar-starter-kit/core';
const config = resolveConfig();
Environment Variables
Supported environment variables (all optional):

NEXT_PUBLIC_STELLAR_NETWORK - Network selection (local|testnet|mainnet, default: testnet)
NEXT_PUBLIC_SOROBAN_RPC_URL - Override RPC endpoint
NEXT_PUBLIC_HORIZON_URL - Override Horizon endpoint
NEXT_PUBLIC_STELLAR_NETWORK_PASSPHRASE - Override passphrase (validated for consistency)
Breaking Changes
None - this is a pure feature addition. Existing code continues to work, but migration to the new configuration system is recommended.

Next Steps
Review the merged changes and configuration system
Update remaining packages to use the new configuration pattern
Consider publishing @stellar-starter-kit/core and @stellar-starter-kit/config to npm
Use the changeset workflow for future releases
Related Documentation
Core Package README
Release Workflow Guide
Contributing Guide

[vercel]

@Clinton6801 is attempting to deploy a commit to the techalhaji's projects Team on Vercel.

A member of the Team first needs to authorize it.

[techAlhaji]

fix the failing ci and review your pr description please.

[Clinton6801]

@techAlhaji , kindly review

[Clinton6801]

@techAlhaji , kindly review

[techAlhaji]

ci still failing