Configure Additional Networks using Hardhat

Guide Versions

This guide is available in multiple versions. Choose the one that matches your needs.

When working with the smart-contract-examples CCIP tutorials, you may need to add support for additional blockchain networks beyond the default testnet configurations (Avalanche Fuji, Ethereum Sepolia, Arbitrum Sepolia, Base Sepolia, and Polygon Amoy). This guide explains how to update the network configuration files in the Hardhat version of the repository.

Overview

The smart-contract-examples repository includes pre-configured network settings for common CCIP testnets. These configuration files store network-specific information such as:

  • Chain selectors
  • Router addresses
  • RMN Proxy addresses
  • Token Admin Registry addresses
  • Registry Module Owner Custom addresses
  • LINK token addresses
  • Block confirmations
  • Native currency symbols

Default networks included:

  • Avalanche Fuji
  • Ethereum Sepolia
  • Arbitrum Sepolia
  • Base Sepolia
  • Polygon Amoy

These values vary by network and must be accurate for your CCIP transactions to work correctly. If you want to use additional networks (e.g., Optimism Sepolia, BNB Chain Testnet, or mainnet networks), you'll need to update the configuration files following this guide.

Finding Network Configuration Values

All CCIP-supported networks and their configuration details are available in the CCIP Directory:

The CCIP Directory provides:

  • Chain selectors
  • Router contract addresses
  • RMN Proxy addresses
  • Token Admin Registry addresses
  • Registry Module Owner Custom addresses
  • LINK token addresses

Updating Configuration Files

In the smart-contract-examples repository, Hardhat projects store network configuration in config/config.json.

File location: smart-contract-examples/ccip/cct/hardhat/config/config.json

Example structure:

{
  "avalancheFuji": {
    "chainId": 43113,
    "chainSelector": "14767482510784806043",
    "router": "0xF694E193200268f9a4868e4Aa017A0118C9a8177",
    "rmnProxy": "0xAc8CFc3762a979628334a0E4C1026244498E821b",
    "tokenAdminRegistry": "0xA92053a4a3922084d992fD2835bdBa4caC6877e6",
    "registryModuleOwnerCustom": "0x97300785aF1edE1343DB6d90706A35CF14aA3d81",
    "link": "0x0b9d5D9136855f6FEc3c0993feE6E9CE8a297846",
    "confirmations": 2,
    "nativeCurrencySymbol": "AVAX",
    "chainType": "l1",
    "chainFamily": "evm"
  },
  "ethereumSepolia": {
    "chainId": 11155111,
    "chainSelector": "16015286601757825753",
    "router": "0x0BF3dE8c5D3e8A2B34D2BEeB17ABfCeBaf363A59",
    "rmnProxy": "0xba3f6251de62dED61Ff98590cB2fDf6871FbB991",
    "tokenAdminRegistry": "0x95F29FEE11c5C55d26cCcf1DB6772DE953B37B82",
    "registryModuleOwnerCustom": "0x62e731218d0D47305aba2BE3751E7EE9E5520790",
    "link": "0x779877A7B0D9E8603169DdbD7836e478b4624789",
    "confirmations": 3,
    "nativeCurrencySymbol": "ETH",
    "chainType": "l1",
    "chainFamily": "evm"
  }
}

Steps to add a new network:

  1. Navigate to your cloned repository directory:

    cd smart-contract-examples/ccip/cct/hardhat

  2. Open config/config.json in your preferred editor

  3. Visit the CCIP Directory (for testnet) or Mainnet Directory (for mainnet)

  4. Locate your desired network in the directory and copy the following values:

    • Chain Selector
    • Router address
    • RMN Proxy address
    • Token Admin Registry address
    • Registry Module Owner Custom address
    • LINK token address

  5. Add a new entry to config/config.json following the existing structure

  6. Set appropriate values for:

    • chainId: The EVM chain ID (find this on the network's official documentation)
    • confirmations: Number of block confirmations to wait (typically 2-3 for testnets, 5-10 for mainnet)
    • nativeCurrencySymbol: The native currency symbol (e.g., "ETH", "AVAX", "POL")
    • chainType: Usually "l1" for Layer 1 or "op" for Optimistic rollups
    • chainFamily: "evm" for Ethereum-compatible chains

  7. Update the network TypeScript configuration:

    • Open config/networks.ts and add your new network to the networks object
    • Add the corresponding RPC URL environment variable

  8. Save the files and test your configuration with a simple deployment

Example: Adding Optimism Sepolia Testnet:

First, add to config/config.json:

{
  "optimismSepolia": {
    "chainId": 11155420,
    "chainSelector": "5224473277236331295",
    "router": "0x114A20A10b43D4115e5aeef7345a1A71d2a60C57",
    "rmnProxy": "0xb40A3109075965cc09E93719e33E748abf680dAe",
    "tokenAdminRegistry": "0x1d702b1FA12F347f0921C722f9D9166F00DEB67A",
    "registryModuleOwnerCustom": "0x49c4ba01dc6F5090f9df43Ab8F79449Db91A0CBB",
    "link": "0xE4aB69C077896252FAFBD49EFD26B5D171A32410",
    "confirmations": 2,
    "nativeCurrencySymbol": "ETH",
    "chainType": "op",
    "chainFamily": "evm"
  }
}

Then, add to config/networks.ts:

[EVMChains.optimismSepolia]: {
  type: "http",
  ...configData.optimismSepolia,
  url: process.env.OPTIMISM_SEPOLIA_RPC_URL || "https://UNSET-PLEASE-SET-OPTIMISM_SEPOLIA_RPC_URL",
  gasPrice: undefined,
  nonce: undefined,
  accounts,
},

Verifying Your Configuration

After updating your configuration files, verify that:

  1. Chain Selector: Matches the value in the CCIP Directory
  2. Router Address: Matches the CCIP Router address for your network
  3. RMN Proxy: Matches the RMN Proxy address
  4. Token Admin Registry: Matches the registry address
  5. Registry Module Owner Custom: Matches the registry module address
  6. LINK Token: Matches the LINK token address for your network
  7. Chain ID: Correct for your network
  8. Block Confirmations: Set to a reasonable value (2-3 for testnets, higher for mainnet)

Common Configuration Errors

Incorrect Chain Selector

Symptom: Transactions fail with "destination chain not supported" error
Solution: Verify the chain selector matches the CCIP Directory exactly

Wrong Router Address

Symptom: Transactions revert when calling CCIP Router
Solution: Ensure you're using the correct CCIP Router address from the directory

Mismatched Token Addresses

Symptom: LINK approval or transfer operations fail
Solution: Verify the LINK token address for your specific network

Missing Network Configuration in networks.ts

Symptom: Hardhat cannot find the network or RPC URL is undefined
Solution: Ensure you've added the network configuration to config/networks.ts and set the RPC URL environment variable

Adapting for Your Own Projects

While this guide focuses on the smart-contract-examples repository structure, you can adapt these principles for your own projects:

  1. Different project structure: Adjust the file paths to match your project's organization
  2. Custom configuration format: You may use environment variables, YAML, TOML, or other formats—apply the same CCIP Directory values
  3. Additional parameters: Your project may require extra configuration fields beyond what's shown here
  4. Multiple networks: Consider organizing configurations by environment (development, staging, production)

The key principle remains the same: Always retrieve official CCIP configuration values from the CCIP Directory to ensure compatibility and correctness.

Next Steps

Once you've updated your network configuration in the smart-contract-examples repository:

  1. Update RPC URLs: Add the new network's RPC URL to your .env.enc file using npx env-enc set

  2. Fund your wallet with native tokens and LINK for the new network using the Chainlink faucets (for testnets)

  3. Test the configuration by running a simple deployment:

    npx hardhat deployToken --name "Test Token" --symbol TEST --network yourNewNetwork

  4. Follow the tutorials using your newly configured network

Get the latest Chainlink content straight to your inbox.