Feat/profile

[OthmanImam]

Closes #58

---

🌐 Robust Multi-Network Configuration System for Soroban

Overview

Implements a production-grade, strongly-typed multi-network configuration system for deploying SkillSync contracts to Stellar's Soroban. Supports testnet, mainnet, and local sandbox with environment-driven configuration, comprehensive validation, and zero-compromise error handling.

What's Included

Configuration Files

✅ soroban.toml - Network profiles with descriptions

• [profile.testnet] - Stellar Testnet configuration
• [profile.mainnet] - Stellar Mainnet configuration
• [profile.sandbox] - Local Soroban Sandbox configuration

✅ .env.example - Safe template for environment variables

• Network selection
• RPC endpoint overrides
• Contract and account IDs
• Debugging options
• Fully documented with no secrets

Rust Implementation

✅ crates/tools/src/config.rs (450+ lines)

• Strongly-typed Network enum (Testnet, Mainnet, Sandbox)
• Config struct with all required fields
• Custom ConfigError type (no panics)
• Configuration resolution with 3 fallback levels
• Comprehensive validation
• Unit tests with 100% passing rate

✅ crates/tools/src/lib.rs

• Public API exports for use in other crates

✅ Updated crates/tools/src/main.rs

• New network show command - display active configuration
• New network list command - list available networks
• Enhanced config --json command - JSON output
• Enhanced deploy --network - runtime network override

Documentation

✅ SOROBAN.md (500+ lines)

• User-friendly guide for all deployment scenarios
• Step-by-step network switching
• Testnet, mainnet, and sandbox setup
• Configuration validation procedures
• Troubleshooting guide
• GitHub Actions and Makefile integration examples

✅ SOROBAN_CONFIG_TECHNICAL.md (600+ lines)

• Architecture overview with diagrams
• Design principles (typing, errors, resolution)
• Complete API reference
• Resolution algorithm walkthrough
• Security considerations
• Performance characteristics
• Extension guidelines

✅ SOROBAN_CONFIG_SUMMARY.md

• Quick reference and implementation checklist
• Code statistics and quality metrics

Key Features

✅ Strongly Typed

pub enum Network {
    Testnet,
    Mainnet,
    Sandbox,
}

Benefits:

• Compile-time guarantee of valid networks
• No runtime string-based network names
• IDE autocompletion

✅ Environment-Driven Configuration

Priority order:

1. Environment variables (highest)
2. soroban.toml profile values
3. Network defaults (lowest)

Environment variables:

• SOROBAN_NETWORK - select network
• SOROBAN_RPC_URL - override RPC endpoint
• SOROBAN_NETWORK_PASSPHRASE - override passphrase
• SOROBAN_CONTRACT_ID - contract address
• SOROBAN_ACCOUNT - signer account
• SOROBAN_RPC_TIMEOUT_MS - request timeout
• SOROBAN_DEBUG - enable debug logging

✅ Production-Safe Error Handling

No unwrap() or expect():

• Every error is typed via thiserror
• Clear error messages for debugging
• Validation catches invalid configurations
• Fails fast with explicit errors

Error types:

pub enum ConfigError {
    MissingField(String),
    InvalidNetwork(String),
    ValidationError(String),
    // ... all variants documented
}

✅ Comprehensive Validation

• RPC URL format (http/https required)
• Network passphrase presence
• Required field detection
• Invalid network name rejection

✅ CLI Integration

# Show active network configuration
cargo run -p skillsync-tools -- network show

# List available networks
cargo run -p skillsync-tools -- network list

# Show configuration as JSON
cargo run -p skillsync-tools -- config --json

# Validate configuration
cargo run -p skillsync-tools -- config --validate

# Deploy with network override
cargo run -p skillsync-tools -- deploy \
  --network mainnet \
  --wasm path/to/contract.wasm

✅ Testable

9 unit tests (all passing):

• Network enum parsing
• Network defaults
• Configuration validation
• Missing field detection
• Invalid URL detection

---

Implementation Quality

Build Status

• ✅ Compiles successfully with all dependencies
• ✅ All 9 unit tests pass
• ✅ Zero compiler errors
• ✅ Only 1 benign warning (unused test helper)

Code Quality

• ✅ No panics in config loading
• ✅ All errors are typed
• ✅ Full documentation on all public APIs
• ✅ Follows Rust 2021 best practices
• ✅ Suitable for production use

Dependencies Added

toml = "0.8"          # TOML parsing
dotenvy = "0.15"      # Load .env automatically  
thiserror = "1.0"     # Typed error handling

All battle-tested, widely-used crates.

---

Usage Examples

For Users: Switch Networks

# Switch to testnet
export SOROBAN_NETWORK=testnet
cargo run -p skillsync-tools -- network show

# Switch to mainnet (be careful!)
export SOROBAN_NETWORK=mainnet
cargo run -p skillsync-tools -- network show

# Switch to local sandbox
export SOROBAN_NETWORK=sandbox
cargo run -p skillsync-tools -- network show

For Developers: Use as Library

use skillsync_tools::Config;

#[tokio::main]
async fn main() -> Result<()> {
    let config = Config::load()?;
    println!("Using network: {}", config.network);
    println!("RPC URL: {}", config.rpc_url);
    
    if config.network == Network::Mainnet {
        eprintln!("⚠️  WARNING: Operating on MAINNET");
    }
    
    deploy_contract(&config).await?;
    Ok(())
}

For CI/CD: GitHub Actions

env:
  SOROBAN_NETWORK: testnet
  SOROBAN_ACCOUNT: ${{ secrets.TESTNET_ACCOUNT }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cargo run -p skillsync-tools -- config --validate
      - run: cargo build -p skillsync-core --target wasm32-unknown-unknown --release
      - run: cargo run -p skillsync-tools -- deploy --wasm target/...

---

File Structure

Root directory:
  soroban.toml                           # Network profiles
  .env.example                           # Environment template
  SOROBAN.md                            # User guide
  SOROBAN_CONFIG_TECHNICAL.md           # Technical reference
  SOROBAN_CONFIG_SUMMARY.md             # Implementation summary

crates/tools/:
  Cargo.toml                            # Added dependencies
  src/
    lib.rs                              # New: public API
    config.rs                           # New: configuration module
    main.rs                             # Updated: CLI commands

---

Testing

CLI Commands Tested:

• ✅ cargo run -p skillsync-tools -- network (default to show)
• ✅ cargo run -p skillsync-tools -- network show
• ✅ cargo run -p skillsync-tools -- network list
• ✅ cargo run -p skillsync-tools -- config --json
• ✅ Environment variable override (SOROBAN_NETWORK=mainnet)

All tests pass with correct output:

• Network selection works
• Configuration resolution respects priority order
• JSON serialization is correct
• Environment variables override TOML values

---

Benefits

• 🔐 Security: Type system prevents network misselection
• 📦 Automation: One command triggers full configuration
• ✅ Validation: Catches configuration errors before deployment
• 📚 Documentation: Complete guides for all scenarios
• 🎯 Smart Contract Optimized: Supports deployment across all networks
• ♻️ Maintainable: Clean code architecture, easy to extend
• 🚀 Production-Ready: No compromises on error handling

---

Next Steps

1. Review soroban.toml for your network endpoints
2. Copy .env.example to .env and configure locally
3. Test with cargo run -p skillsync-tools -- network show
4. Deploy to testnet first: export SOROBAN_NETWORK=testnet
5. Reference SOROBAN.md for detailed procedures

---

Documentation

• Quick start: SOROBAN.md § "How to Use the Configuration System"
• Network setup: SOROBAN.md § "Network-Specific Setup"
• Troubleshooting: SOROBAN.md § "Troubleshooting"
• Technical details: SOROBAN_CONFIG_TECHNICAL.md
• Implementation status: SOROBAN_CONFIG_SUMMARY.md

---

Compatibility

• ✅ Works with official soroban CLI patterns
• ✅ Compatible with GitHub Actions
• ✅ Works with Makefiles
• ✅ Docker container friendly
• ✅ CI/CD pipeline ready

---

Related Issues

• Addresses multi-network support requirements
• Enables safe mainnet deployment
• Provides developer ergonomics for network switching
• Creates production-ready configuration foundation

Checklist

• Workflow is production-ready
• All documentation complete with exact commands
• Configuration system tested (9 unit tests pass)
• CLI integration verified
• Permissions properly scoped
• Uses only stable, reliable dependencies
• Zero panics in critical paths
• Error handling is comprehensive

---

Category: Infrastructure / DevOps
Type: Feature
Breaking Changes: None
Verified: ✅ Builds, tests, and runs