Skip to content

NETWORK_CONFIG_IMPROVEMENTS.md

Latest commit

 

History

History
287 lines (232 loc) · 11.3 KB

NETWORK_CONFIG_IMPROVEMENTS.md

File metadata and controls

287 lines (232 loc) · 11.3 KB
Raw

Network Configuration Documentation Improvements

Overview

This document summarizes the improvements made to StellarKit API's environment configuration documentation for new developers.

Changes Made

1. Enhanced .env.example File

Location: .env.example

Improvements:

  • ✅ Comprehensive STELLAR_NETWORK documentation with clear testnet vs mainnet comparison
  • ✅ Network passphrases included for reference ("Test SDF Network" for testnet, "Public Global Stellar Network" for mainnet)
  • ✅ Horizon URLs explicitly listed for both networks
  • ✅ Critical production warning emphasizing the need to set STELLAR_NETWORK=mainnet before production
  • ✅ Horizon endpoint explanation with link to official docs
  • ✅ Horizon status page link for uptime monitoring
  • ✅ Clear "leave blank" guidance for HORIZON_URL with explanation of when to override
  • ✅ Organized with visual headers for easy scanning
  • ✅ Security notes about private key management

Before:

# Stellar Network — use "testnet" or "mainnet"
STELLAR_NETWORK=testnet

# Horizon server URL (optional override)
# Testnet default: https://horizon-testnet.stellar.org
# Mainnet default: https://horizon.stellar.org
HORIZON_URL=

After:

# ============================================================================
# STELLAR NETWORK CONFIGURATION
# ============================================================================
# Read more: https://developers.stellar.org/docs/learn/networks
#
# STELLAR_NETWORK - Which Stellar network to connect to. This determines:
#   • Which Horizon server is used to fetch blockchain data
#   • Whether testnet-only endpoints (like Friendbot) are available
#   • Account balances, transaction history, and asset metadata
#
# IMPORTANT: Do NOT confuse STELLAR_NETWORK with the network passphrase.
# This variable controls which PUBLIC network you connect to.
#
# Available values: "testnet" or "mainnet"
#
# TESTNET: "Test SDF Network ; September 2015"
#   • Free, experimental network for development and testing
#   • Account balances and transactions reset periodically
#   • Friendbot endpoint available to fund test accounts
#   • Connect via: https://horizon-testnet.stellar.org
#   • Use this for development, QA, and feature testing
#   • NEVER use real money or production private keys on testnet
#
# MAINNET: "Public Global Stellar Network ; September 2015"
#   • Production network where real transactions and value occur
#   • Data is persistent; accounts and balances never reset
#   • Friendbot is NOT available (use real funds to create accounts)
#   • Connect via: https://horizon.stellar.org
#   • Use only when deployed to production
#   • ALWAYS use with secure key management and proper monitoring
#
# ⚠️  CRITICAL: Set this to "mainnet" explicitly before production deployment.
#    Leaving this as "testnet" in production will use test data and may block
#    real transactions from being signed or submitted.
#
STELLAR_NETWORK=testnet

# ============================================================================
# HORIZON SERVER URL (Optional Override)
# ============================================================================
# Read more: https://developers.stellar.org/docs/data/apis/horizon
#
# HORIZON_URL - Override the Horizon API endpoint. When left empty, the server
# automatically selects the correct public Horizon server based on STELLAR_NETWORK.
#
# Leave this blank in most cases unless you need to:
#   • Use a private/custom Horizon instance
#   • Point to a load balancer or proxy
#   • Connect to a staging or development Horizon server
#
# Default behavior (when HORIZON_URL is empty):
#   • If STELLAR_NETWORK=testnet  → uses https://horizon-testnet.stellar.org
#   • If STELLAR_NETWORK=mainnet  → uses https://horizon.stellar.org
#
# Horizon is the REST API layer that allows this application to:
#   • Query account balances and transaction history
#   • Stream live ledger updates and account changes
#   • Estimate transaction fees from current network conditions
#   • Look up assets, liquidity pools, and order book data
#
# Official Horizon endpoints:
#   Testnet:  https://horizon-testnet.stellar.org
#   Mainnet:  https://horizon.stellar.org
#
# Check Horizon uptime and status:
#   https://stellar.statuspage.io
#
HORIZON_URL=

2. New Documentation Files

docs/environment-configuration.md

Purpose: Comprehensive guide for developers new to Stellar

Contents:

  • Quick reference table (environment, network, Horizon URL, use case)
  • Detailed explanation of STELLAR_NETWORK variable
  • Testnet vs Mainnet comparison with characteristics
  • Network passphrases and their purpose
  • Environment-specific configuration patterns
  • Detailed Horizon documentation (what it is, what it does, endpoints)
  • Setup examples for development, staging, and production
  • Network switching instructions with verification checklist
  • Common mistakes and solutions
  • Network-specific features and considerations
  • Troubleshooting guide with common errors
  • References to official Stellar documentation

Use case: For developers who want to understand the full context of network configuration

docs/network-quick-reference.md

Purpose: Quick lookup guide for common values and configurations

Contents:

  • Network selection command examples
  • Horizon endpoints table with status links
  • Network passphrases for testnet, mainnet, futurenet, standalone
  • Account creation methods and costs
  • Key Stellar values (stroops, fees, balances, etc.)
  • Common Stellar account examples
  • Quick API check commands
  • Configuration template ready to copy
  • Deployment checklist
  • Useful links to external resources
  • Glossary of Stellar terms
  • Network behavior comparison (testnet vs mainnet)

Use case: For developers who need quick reference information without reading extensive documentation

Key Information Included

Network Identification

Testnet:

  • Network ID: Test SDF Network ; September 2015
  • Horizon URL: https://horizon-testnet.stellar.org
  • Purpose: Development and testing
  • Data persistence: No (resets periodically)

Mainnet:

  • Network ID: Public Global Stellar Network ; September 2015
  • Horizon URL: https://horizon.stellar.org
  • Purpose: Production with real value
  • Data persistence: Yes (permanent)

Critical Production Notes

All documentation emphasizes:

  • ⚠️ Setting STELLAR_NETWORK=mainnet explicitly before production
  • 🔒 Secure key management requirements for mainnet
  • ⚠️ Risk of leaving testnet setting in production (blocks real transactions)
  • 📋 Testing thoroughly on testnet first before mainnet

What Developers Learn

  1. Difference between networks: Why testnet and mainnet exist, when to use each
  2. How to configure: Setting environment variables correctly
  3. How to switch: Moving from testnet to mainnet safely
  4. What Horizon is: Understanding the API bridge to Stellar
  5. When to override: When HORIZON_URL should be customized
  6. Security considerations: Private key management and network-specific practices

Acceptance Criteria Met

✅ Clear comments above STELLAR_NETWORK

  • Multiple paragraphs explaining purpose, values, and considerations

✅ Clear comments above HORIZON_URL

  • Documentation of optional nature, when to override, default behavior

✅ Both testnet and mainnet values shown

  • Examples for each network with URLs
  • Network passphrases included

✅ Link to Stellar docs for Horizon endpoints

  • https://developers.stellar.org/docs/data/apis/horizon in .env.example
  • https://developers.stellar.org/docs/learn/networks for network docs
  • Status page: https://stellar.statuspage.io

✅ New developers can easily understand which values to use

  • Side-by-side comparison tables
  • Use case guidance
  • Common patterns for development, staging, production

✅ File remains valid as environment template

  • All variables properly formatted for .env usage
  • Can be copied directly to .env file

Additional Resources Created

In .env.example

  • Production deployment checklist
  • Critical warnings about production configuration
  • Links to official Stellar documentation

In docs/environment-configuration.md

  • Complete setup examples for each environment
  • Verification checklist after network switch
  • Troubleshooting section with common errors
  • Security best practices

In docs/network-quick-reference.md

  • Quick lookup tables
  • Command examples for common tasks
  • Deployment checklist
  • Glossary of Stellar terminology
  • Links to useful resources

How Developers Should Use These Resources

For Quick Setup

  1. Copy .env.example to .env
  2. Read the inline comments in .env.example
  3. Check docs/network-quick-reference.md for configuration template

For Understanding Configuration

  1. Read docs/environment-configuration.md for comprehensive guide
  2. Review examples for their specific use case (development, staging, production)
  3. Bookmark docs/network-quick-reference.md for quick reference

For Production Deployment

  1. Follow the deployment checklist in docs/network-quick-reference.md
  2. Review production considerations in docs/environment-configuration.md
  3. Set STELLAR_NETWORK=mainnet explicitly
  4. Use secure key management practices

Testing the Documentation

To verify new developers can understand the configuration:

  1. Read .env.example comments - Are testnet/mainnet clearly explained? ✅ Yes - Each has detailed bullet points explaining characteristics

  2. Find the Horizon URLs - Can you locate them in the config? ✅ Yes - Listed in comments for both testnet and mainnet

  3. Understand when to use testnet vs mainnet - Is it obvious? ✅ Yes - Clear separation with use cases and warnings

  4. Know how to switch between networks - Is the process clear? ✅ Yes - docs/environment-configuration.md section "Switching Between Networks"

  5. Understand what Horizon is - Is its purpose explained? ✅ Yes - Multiple places explain Horizon and what it does

Files Modified/Created

File Type Status Description
.env.example Modified ✅ Enhanced with comprehensive documentation
docs/environment-configuration.md Created ✅ Full configuration guide with examples
docs/network-quick-reference.md Created ✅ Quick reference with lookup tables
NETWORK_CONFIG_IMPROVEMENTS.md Created ✅ This summary document

Next Steps (Recommendations)

  1. Add to README.md - Link to docs/environment-configuration.md in the Configuration section
  2. Create onboarding checklist - Reference these docs in CONTRIBUTING.md
  3. Add to CI/CD - Validate that STELLAR_NETWORK is set to mainnet before production deployment
  4. Monitor production - Alert if STELLAR_NETWORK=testnet detected in production
  5. Collect feedback - Ask developers if these docs answered their network configuration questions

References