Skip to main content
Testnet deployment allows you to test the Eco Routes Protocol in a public environment with real bridge infrastructure before deploying to mainnet.

​
Supported Testnets

Eco Routes can be deployed to any EVM-compatible testnet. Common testnets include:
  • Ethereum Sepolia
  • Base Sepolia
  • Optimism Sepolia
  • Arbitrum Sepolia
  • Polygon Mumbai
  • BSC Testnet
  • Avalanche Fuji

​
Prerequisites

​
Required Resources

1

Testnet Native Tokens

Obtain testnet native tokens (ETH, MATIC, etc.) from faucets:
2

RPC Endpoints

Get RPC endpoints from providers:
3

Block Explorer API Keys

For contract verification:

​
Bridge Contract Addresses

Identify bridge contract addresses for your target testnets: Hyperlane Mailbox Contracts LayerZero Endpoints Metalayer Router Contracts
  • Contact Metalayer for testnet deployment addresses
Polymer CrossL2ProverV2

​
Environment Configuration

​
Configure .env File

Create a .env file with testnet configuration:
.env
# Deployment private key (NEVER use mainnet keys on testnet!)
PRIVATE_KEY=your_testnet_private_key_here

# Alchemy API key for RPC access
ALCHEMY_API_KEY=your_alchemy_api_key

# Chain configuration
CHAIN_DATA_URL="https://raw.githubusercontent.com/eco/eco-chains/refs/heads/main/src/assets/chain.json"

# Deployment output
DEPLOY_FILE="out/deploy-testnet.csv"

# Salt for deterministic deployment (use same as mainnet for consistency)
SALT=0x88f72b566ae0c96f6fffac4bc8ac74909f61512ac0c06a8124d5ed420d306f90

# Portal configuration (leave empty to deploy new Portal)
PORTAL_CONTRACT=

# Sepolia Hyperlane configuration (example)
MAILBOX_CONTRACT=0xfFAEF09B3cd11D9b20d1a19bECca54EEC2884766

# LayerZero Sepolia endpoint (example)
LAYERZERO_ENDPOINT=0x6EDCE65403992e310A62460808c4b910D972f10f
LAYERZERO_DELEGATE=

# Metalayer router (example)
ROUTER_CONTRACT=0x0000000000000000000000000000000000000000

# Polymer CrossL2ProverV2 (example)
POLYMER_CROSS_L2_PROVER_V2=0x0000000000000000000000000000000000000000

# Cross-VM provers (optional)
HYPER_CROSS_VM_PROVERS=
META_CROSS_VM_PROVERS=
LAYERZERO_CROSS_VM_PROVERS=
POLYMER_CROSS_VM_PROVERS=

# Verification configuration
VERIFICATION_KEYS_FILE=verification-keys-testnet.json

​
Create Verification Keys File

Create verification-keys-testnet.json with API keys for each testnet:
verification-keys-testnet.json
{
  "11155111": "your_etherscan_api_key_for_sepolia",
  "84532": "your_basescan_api_key_for_base_sepolia",
  "11155420": "your_optimistic_etherscan_api_key",
  "421614": "your_arbiscan_api_key",
  "80001": "your_polygonscan_api_key"
}
Chain IDs:
  • Ethereum Sepolia: 11155111
  • Base Sepolia: 84532
  • Optimism Sepolia: 11155420
  • Arbitrum Sepolia: 421614
  • Polygon Mumbai: 80001

​
Deployment Process

​
Single Chain Deployment

Deploy to a single testnet using Forge: 
# Deploy to Sepolia testnet
forge script scripts/Deploy.s.sol \
  --broadcast \
  --rpc-url https://eth-sepolia.g.alchemy.com/v2/$ALCHEMY_API_KEY \
  --verify \
  --etherscan-api-key $ETHERSCAN_API_KEY

​
Multi-Chain Deployment

Deploy to multiple testnets using the deployment script:
1

Prepare Chain Data

Create or update your chain data JSON with testnet configurations:
chain-data-testnet.json
{
  "11155111": {
    "url": "https://eth-sepolia.g.alchemy.com/v2/${ALCHEMY_API_KEY}",
    "mailbox": "0xfFAEF09B3cd11D9b20d1a19bECca54EEC2884766",
    "router": "0x0000000000000000000000000000000000000000",
    "gasMultiplier": "120"
  },
  "84532": {
    "url": "https://base-sepolia.g.alchemy.com/v2/${ALCHEMY_API_KEY}",
    "mailbox": "0xYourBaseSepoliaMailbox",
    "router": "0xYourBaseSepoliaRouter",
    "gasMultiplier": "120"
  }
}
2

Update .env

Point to your testnet chain data:
CHAIN_DATA_URL="./chain-data-testnet.json"
RESULTS_FILE="deployments/testnet-results.json"
3

Run Deployment Script

./scripts/deployRoutes.sh
The script will:
  • Deploy to each chain in your chain data file
  • Use deterministic addresses based on SALT
  • Record deployments to CSV file
  • Skip chains where contracts are already deployed

​
Deployment with Cross-VM Support

For cross-chain testing with non-EVM chains: 
# Set cross-VM prover addresses
export HYPER_CROSS_VM_PROVERS="0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
export LAYERZERO_CROSS_VM_PROVERS="0x5678901234abcdef5678901234abcdef5678901234abcdef5678901234abcdef"

# Deploy
./scripts/deployRoutes.sh

​
Verify Deployment

​
Check Deployment Output

# View deployment results
cat out/deploy-testnet.csv
Expected output: 
ChainID,ContractAddress,ContractPath,ContractArguments
11155111,0x742d35Cc6634C0532925a3b844Bc454e4438f44e,contracts/Portal.sol:Portal,0x
11155111,0x8464135c8F25Da09e49BC8782676a84730C318bC,contracts/prover/HyperProver.sol:HyperProver,0x000000...

​
Verify Contract Addresses

Verify that contracts were deployed to expected deterministic addresses: 
# Check Portal address
cast code 0x742d35Cc6634C0532925a3b844Bc454e4438f44e \
  --rpc-url https://eth-sepolia.g.alchemy.com/v2/$ALCHEMY_API_KEY

# Verify it matches across chains (should be same address)
cast code 0x742d35Cc6634C0532925a3b844Bc454e4438f44e \
  --rpc-url https://base-sepolia.g.alchemy.com/v2/$ALCHEMY_API_KEY

​
Contract Verification

Verify contracts on block explorers: 
# Verify all deployed contracts
./scripts/verifyRoutes.sh
This script will:
  • Read deployment data from CSV file
  • Verify each contract on its respective block explorer
  • Retry failed verifications
  • Provide verification summary
For manual verification of a single contract: 
forge verify-contract \
  --chain sepolia \
  --etherscan-api-key $ETHERSCAN_API_KEY \
  --watch \
  0x742d35Cc6634C0532925a3b844Bc454e4438f44e \
  contracts/Portal.sol:Portal

​
Testing on Testnet

​
Integration Testing

Test cross-chain intent flow on testnets:
1

Create Intent on Source Chain

# Create an intent on Sepolia
cast send $PORTAL_ADDRESS "publish(...)" \
  --private-key $PRIVATE_KEY \
  --rpc-url https://eth-sepolia.g.alchemy.com/v2/$ALCHEMY_API_KEY
2

Fund Intent

Fund the intent with testnet tokens.
3

Fulfill on Destination Chain

Execute fulfillment on destination testnet (e.g., Base Sepolia).
4

Verify Proof

Monitor bridge message delivery and proof verification.
5

Withdraw Rewards

Solver withdraws rewards on source chain after proof validation.

​
Monitor Transactions

Use block explorers to monitor testnet transactions:

​
Common Issues

​
Insufficient Testnet Funds

Deployment requires gas for multiple transactions. Ensure you have sufficient testnet tokens before deploying.
Estimated gas costs:
  • Portal deployment: ~2-3M gas
  • Each Prover deployment: ~1-2M gas

​
RPC Rate Limiting

If using public RPC endpoints, you may hit rate limits: 
# Add delay between deployments
forge script scripts/Deploy.s.sol \
  --broadcast \
  --rpc-url $RPC_URL \
  --slow  # Adds delay between transactions

​
Bridge Contract Not Deployed

If bridge contracts aren’t available on your target testnet:
  • Contact bridge provider for testnet addresses
  • Deploy only Portal without Provers for basic testing
  • Use alternative bridge protocols available on that testnet

​
Verification Failures

If contract verification fails: 
# Wait a few minutes for Etherscan to index the contract
sleep 60

# Retry verification
forge verify-contract \
  --chain sepolia \
  --etherscan-api-key $ETHERSCAN_API_KEY \
  --watch \
  --constructor-args $(cast abi-encode "constructor(address,address,bytes32[])" $ARG1 $ARG2 $ARG3) \
  $CONTRACT_ADDRESS \
  $CONTRACT_PATH

​
Next Steps

Verify Contracts

Complete guide to contract verification

Mainnet Deployment

Deploy to production after testnet validation

Build docs developers (and LLMs) love

Get started for freeTalk to us