Mainnet & Testnet

HyperDex ships both Stellar networks in a single build. A switcher in the navbar picks one at runtime — no separate deployment, no rebuild.

How the switcher works

Both network configurations — contract addresses, RPC endpoint, Horizon endpoint, backend origin and explorer base — are compiled into the bundle. The one in effect is resolved at module load from localStorage["hyperdex.network"], falling back to the build-time default when a visitor has never chosen.

• →Click the Mainnet / Testnet pill next to Connect Wallet
• →Pick a network — the choice is stored and the page hard-reloads
• →Set your wallet to the matching network, then reconnect

What differs per network

Backend routing

The backend is single-network per instance — it reads one STELLAR_NETWORK from its environment and derives the passphrase from it. Running both networks therefore means running two backend instances.

Because Next.js route handlers execute on the server, they cannot see the visitor's localStorage choice. Every browser call to an internal /api/* route is tagged with a header, and the handler maps it to the matching backend origin:

// browser
fetch('/api/maker-application', {
  headers: networkHeaders({ 'Content-Type': 'application/json' }),
  // -> x-hyperdex-network: testnet
});

// server route handler
const backendUrl = backendUrlFromRequest(req);
// -> NETWORKS['testnet'].backendUrl

Wrong-network detection

After connecting, HyperDex compares the wallet's reported network passphrase with the selected network. On a mismatch a banner names the connected wallet and the network it should be on, and signing is blocked before the wallet is ever opened.

Wallets that do not expose a network (hardware devices, some bridges) return null and are allowed through — the check runs again at signing time. This matters: a signature produced against the wrong passphrase is rejected on-chain as txBadAuth, after the user has already approved it.

Environment variables

Each network has its own prefix. Un-suffixed legacy variables are kept as a fallback for whichever network NEXT_PUBLIC_STELLAR_NETWORK names, so an existing single-network deployment keeps working untouched.

# Network a first-time visitor sees
NEXT_PUBLIC_DEFAULT_NETWORK=mainnet

# Mainnet
NEXT_PUBLIC_MAINNET_STELLAR_RPC_URL=https://mainnet.sorobanrpc.com
NEXT_PUBLIC_MAINNET_HORIZON_URL=https://horizon.stellar.org
NEXT_PUBLIC_MAINNET_BACKEND_URL=https://hyperdex.onrender.com
NEXT_PUBLIC_MAINNET_POOL_REGISTRY_CONTRACT=...
NEXT_PUBLIC_MAINNET_QUOTE_VERIFIER_CONTRACT=...
NEXT_PUBLIC_MAINNET_MAKER_POOL_FACTORY_ADDRESS=...
NEXT_PUBLIC_MAINNET_FEE_DISTRIBUTOR_CONTRACT=...
NEXT_PUBLIC_MAINNET_USDC_CONTRACT=...
NEXT_PUBLIC_MAINNET_EURC_CONTRACT=...
NEXT_PUBLIC_MAINNET_ADMIN_ADDRESS=...

# Testnet — same keys, TESTNET_ prefix
NEXT_PUBLIC_TESTNET_STELLAR_RPC_URL=https://soroban-testnet.stellar.org
NEXT_PUBLIC_TESTNET_HORIZON_URL=https://horizon-testnet.stellar.org
NEXT_PUBLIC_TESTNET_BACKEND_URL=https://hyperdex-testnet.onrender.com
# ...same contract keys with TESTNET_

Getting testnet funds

Fund an account with XLM from Friendbot, then add trustlines and acquire Circle's testnet USDC/EURC. Note the two assets have different testnet issuers — USDC is issued by GBBD47IF… (centre.io) and EURC by GB3Q6QDZ… (circle.com).

# Fund a testnet account
curl "https://friendbot.stellar.org/?addr=<YOUR_G_ADDRESS>"

# Or via the CLI
stellar keys generate my-taker --network testnet --fund

Running the testnet stack locally

# 1. Backend pointed at testnet (backend/.env)
STELLAR_NETWORK=testnet
STELLAR_RPC_URL=https://soroban-testnet.stellar.org
HORIZON_URL=https://horizon-testnet.stellar.org
# ...testnet contract addresses

cd backend && npm run dev      # -> port 4000

# 2. Bootstrap a maker end-to-end (apply, approve, signer key, deploy pool)
bash scripts/bootstrap-testnet-maker.sh
# -> writes maker-sdk/.env with the API key, signer seed and pool address

# 3. Start the maker, then the frontend
cd maker-sdk && npm run dev
cd frontend  && npm run dev    # -> http://localhost:3000