Multiple bugs and documentation inaccuracies make testnet deployment unnecessarily difficult. The official workflow doesn't work as documented.
Environment

Scaffold Stellar CLI: [run stellar scaffold version to get version]
Stellar CLI: [run stellar version to get version]
OS: Linux/Ubuntu
Node.js: [run node --version]

Issues Found

1. Registry System Failures
   Expected: Registry publish/deploy should work per docs
   bashstellar registry publish --wasm contract.wasm --source account --network testnet
   stellar registry deploy --deployed-name my-contract --published-name my-contract
   Actual:

stellar registry publish fails with Error(Contract, #11)
--deployed-name flag doesn't exist (error: "unexpected argument")
Constructor arguments cause XDR processing errors
Registry workflow is unreliable

2. Environment Variable Issues
   Expected: STELLAR_ENV=staging npm run dev should use testnet
   Actual: Still tries to use localhost Docker container even with staging environment
   Missing from docs:

Need STELLAR_SCAFFOLD_ENV=staging (not STELLAR_ENV)
Correct syntax: STELLAR_SCAFFOLD_ENV=staging stellar scaffold watch --build-clients staging

3. Configuration Problems
   Missing from docs:

Must set run-locally = false in development environment
Need to manually add contract IDs to staging.contracts after deployment
Must add client = true to staging contracts, not development
environments.toml structure unclear for testnet

4. Docker Container Conflicts
   Issue: Scaffold tries to start local Docker even when targeting testnet
   Error: "Failed to start docker container" / "Connection reset by peer"
   Working Solution
   Direct deployment works reliably:
   bash# 1. Deploy directly
   stellar contract deploy --wasm contract.wasm --source testnet-dev --network testnet

2. Add contract ID to environments.toml staging section with client = true

3. Generate clients

STELLAR_SCAFFOLD_ENV=staging stellar scaffold watch --build-clients staging
Suggested Fixes

Update registry documentation - either fix registry bugs or document direct deployment as primary method
Fix environment variable handling - STELLAR_ENV should work as documented
Add troubleshooting section for common testnet deployment issues
Include complete environments.toml examples for testnet configuration
Document Docker avoidance - how to disable local container when using testnet

These are the steps I took to get it working

Scaffold Stellar Testnet Deployment Guide

Step 1: Configure Environments

1. Update environments.toml for staging (testnet)

   ### Development environment configuration
   [development.network]
   rpc-url = "http://localhost:8000/rpc"
   network-passphrase = "Standalone Network ; February 2017"
   run-locally = false  # Set to false to avoid Docker issues
   
   [[development.accounts]]
   name = "me"
   default = true
   
   [development.contracts]
   # Leave empty or comment out for testnet deployment
   
   ### Staging environment configuration (TESTNET)
   [staging.network]
   rpc-url = "https://soroban-testnet.stellar.org"
   network-passphrase = "Test SDF Network ; September 2015"
   
   [[staging.accounts]]
   name = "testnet-dev"
   default = true
   
   [staging.contracts]
   # Will be populated after deployment

Step 2: Set Up Testnet Account

1. Generate and fund testnet account

   # Generate new testnet identity
   stellar keys generate testnet-dev --network testnet
   
   # Fund the account using Stellar's friendbot
   stellar keys fund testnet-dev --network testnet

Step 3: Build and Deploy Contract

1. Build the contract

   stellar contract build

2. Deploy to testnet

   # Deploy your new contract
   stellar contract deploy \
     --wasm target/wasm32v1-none/release/my_new_contract.wasm \
     --source testnet-dev \
     --network testnet
   
   # If contract has constructor, add constructor args:
   stellar contract deploy \
     --wasm target/wasm32v1-none/release/my_new_contract.wasm \
     --source testnet-dev \
     --network testnet \
     -- \
     --param1 value1 \
     --param2 value2

3. Save the contract ID (from deploy output)

   Example output: CCJNWS5X3WHQNPXVVMRJV2SHCS43Y744E22V5QNI7K6OFXICKXPRNYYM
   

Step 4: Update Configuration Files

1. Update environments.toml with contract ID

   [staging.contracts]
   my_new_contract = { id = "CCJNWS5X3WHQNPXVVMRJV2SHCS43Y744E22V5QNI7K6OFXICKXPRNYYM", client = true }
   # Add other existing contracts too

2. Update .env file for testnet

   PUBLIC_STELLAR_NETWORK="TESTNET"
   PUBLIC_STELLAR_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
   PUBLIC_STELLAR_RPC_URL="https://soroban-testnet.stellar.org"
   PUBLIC_STELLAR_HORIZON_URL="https://horizon-testnet.stellar.org"
   
   # Add contract IDs
   PUBLIC_MY_NEW_CONTRACT_ID="CCJNWS5X3WHQNPXVVMRJV2SHCS43Y744E22V5QNI7K6OFXICKXPRNYYM"

Step 5: Generate TypeScript Clients

1. Generate clients using Scaffold

   # Set environment and generate clients
   STELLAR_SCAFFOLD_ENV=staging stellar scaffold watch --build-clients staging

   Expected output:

   • ✅ Using network at https://soroban-testnet.stellar.org
   • ✅ Downloading contract spec from your contract ID
   • ✅ Generated TypeScript client
   • ✅ Built NPM package

2. Alternative: Manual client generation

   stellar contract bindings typescript \
     --contract-id CCJNWS5X3WHQNPXVVMRJV2SHCS43Y744E22V5QNI7K6OFXICKXPRNYYM \
     --network testnet \
     --output-dir packages/my_new_contract

Step 6: Start Frontend

1. Install generated packages

   npm run install:contracts

2. Start development server

   # Keep scaffold watch running in one terminal
   STELLAR_SCAFFOLD_ENV=staging stellar scaffold watch --build-clients staging
   
   # In another terminal, start frontend
   npx vite

Step 7: Test Contract

1. Test via CLI

   stellar contract invoke \
     --id CCJNWS5X3WHQNPXVVMRJV2SHCS43Y744E22V5QNI7K6OFXICKXPRNYYM \
     --source testnet-dev \
     --network testnet \
     -- \
     your_function_name \
     --param1 value1

2. Test via frontend

   • Open http://localhost:5173
   • Navigate to Debug page
   • Your contract should appear with testnet ID

Troubleshooting

Scaffold still uses localhost

• Ensure run-locally = false in development.network
• Use STELLAR_SCAFFOLD_ENV=staging environment variable
• Pass staging as argument to watch command

Contract not appearing in frontend

• Check environments.toml has correct contract ID
• Ensure client = true is set in staging.contracts
• Restart scaffold watch process

MissingValue errors

• Contract not deployed or wrong network
• Check .env has correct network settings
• Verify contract ID is correct

Summary Checklist

• Contract added to contracts/ folder
• environments.toml configured for staging
• Testnet account created and funded
• Contract built and deployed to testnet
• Contract ID added to environments.toml
• .env updated for testnet
• TypeScript clients generated
• Frontend started and contracts visible
• Contract functions tested via CLI

Key Environment Variables

# Always use these for testnet development
STELLAR_SCAFFOLD_ENV=staging
PUBLIC_STELLAR_NETWORK="TESTNET"
PUBLIC_STELLAR_RPC_URL="https://soroban-testnet.stellar.org"

Benefits of This Approach

✅ Persistent contracts - Survive restarts and shutdowns
✅ Real network conditions - Test against actual testnet
✅ Shareable - Others can interact with same contracts
✅ No Docker issues - Avoid local container problems
✅ Production-like - Similar to mainnet deployment process