feat(`config`): improve documentation around usage of `--chain` and `--rpc-url`

[mshakeg]

Component

Forge

Describe the feature you would like

Summary

Extend Foundry's chain configuration system to include chain IDs alongside RPC URLs in foundry.toml, enabling the --chain flag to work seamlessly with custom chains and improving integration with StdChains.

Problem Statement

Currently, Foundry's chain configuration has several limitations that create friction in the developer experience:

1. Limited --chain Flag Functionality

The --chain flag only works with pre-defined chains in StdChains (mainnet, polygon, etc.). For custom or newer chains not included in the default set, developers must:

• Use --rpc-url instead of the more intuitive --chain to use the rpc url for a specified chain alias.

2. StdChains Integration Gap

When working with custom chains in Solidity scripts, developers must manually add chain data:

// Current workaround required
setChain("unichain", ChainData("Unichain", 130, ""));
Chain memory chain = getChain("unichain");

This breaks the seamless experience that StdChains provides for default chains.

3. Inconsistent Configuration Experience

Developers configure RPC URLs in foundry.toml:

[rpc_endpoints]
unichain = "${UNICHAIN_MAINNET_RPC_URL}"

But this configuration doesn't enable full chain functionality - it only works for RPC calls, not for script execution or StdChains integration.

Proposed Solution

Enhanced foundry.toml Configuration

Extend the configuration format to include chain IDs alongside RPC URLs:

[rpc_endpoints]
mainnet = { url = "${MAINNET_RPC_URL}", chain_id = 1 }
unichain = { url = "${UNICHAIN_MAINNET_RPC_URL}", chain_id = 130 }
polygon = { url = "${POLYGON_RPC_URL}", chain_id = 137 }
# ...

Backward Compatibility

Maintain full backward compatibility with existing configurations:

[rpc_endpoints]
mainnet = "https://eth.llamarpc.com"  # Still works as before
unichain = { url = "${UNICHAIN_MAINNET_RPC_URL}", chain_id = 1301 }  # New format

Expected Benefits

1. Seamless --chain Flag Usage

# This would work for any configured chain
forge script script/Deploy.s.sol --chain unichain --account deployer --broadcast

2. Automatic StdChains Integration

// Would work automatically without manual setup
Chain memory chain = getChain(1301);  // By chain ID
Chain memory chain = getChain("unichain");  // By alias

3. Built-in Validation

Foundry could perform sanity checks:

• Verify the actual chain ID matches the configured chain ID when connecting
• Warn about mismatches between configured and actual chain IDs
• Provide helpful error messages for chain configuration issues

4. Unified Configuration Experience

One configuration enables:

• Script execution with --chain
• RPC calls with aliases
• StdChains integration
• Verification with proper chain context

Implementation Considerations

1. Chain ID Discovery

For configurations without explicit chain IDs, Foundry could:

• Auto-discover chain ID on first connection
• Cache the result for future use
• Provide warnings about missing chain ID configuration

2. Configuration Validation

• Validate that URLs are reachable and return expected chain IDs
• Provide clear error messages for configuration mismatches
• Support dry-run validation commands

3. Migration Path

• Provide tooling to help migrate existing configurations
• Auto-generate chain ID mappings for common networks
• Clear documentation on migration benefits

Use Cases

1. Multi-Chain Development

# Deploy to multiple chains with consistent commands
forge script script/Deploy.s.sol --chain mainnet --broadcast
forge script script/Deploy.s.sol --chain unichain --broadcast  
forge script script/Deploy.s.sol --chain polygon --broadcast

2. Chain-Aware Scripts

function run() external {
    Chain memory currentChain = getChain(block.chainid);
    console.log("Deploying to:", currentChain.name);
    
    // Chain-specific logic without manual configuration
    if (currentChain.chainId == 1301) {
        // Unichain-specific deployment logic
    }
}

Related Issues

This enhancement would address several common developer pain points:

• Confusion about when to use --chain vs --rpc-url
• Manual StdChains configuration for custom networks
• Inconsistent chain configuration across different Foundry commands

Additional context

No response

[zerosnacks]

Hi @mshakeg

I am not sure if I understand your request fully. I was under the impression that we fetch the chain id from the RPC already. It should not be necessary for the user to define the chain ids manually, we use https://github.com/alloy-rs/chains for this to link a human readable name to the chain id.

I think there is some confusion around getChain which is logic defined in https://github.com/foundry-rs/forge-std/blob/master/src/StdChains.sol and how Foundry uses the --chain parameter in forge script. These two are not connected.

[mshakeg]

Hey @zerosnacks there's 2 asks here:

1. devs should be to be able to specify --chain chain_alias instead of --rpc-url chain_alias as currently required(though this can work too for backwards compatibility)
2. and for StdChains.getChain(chain_alias|chain_id) to return the info configured in the foundry.toml for this possibly non-std (though configured in foundry.toml) chain.

[zerosnacks]

Reading the ticket description I think this will largely be resolved by improved documentation around the use of --chain and --rpc-url in different contexts

[Rimeeeeee]

may i look into this :)

[zerosnacks]

sure! assigned to you @Rimeeeeee

[Rimeeeeee]

@zerosnacks should we consider adding the docs directly to the foundry book or here

[zerosnacks]

I think we could add some additional documentation here: https://book.getfoundry.sh/reference/forge/forge-script / https://github.com/foundry-rs/book/blob/master/src/reference/forge/forge-script.md and https://book.getfoundry.sh/guides/scripting-with-solidity#configuring-foundrytoml

We can also improve the documentation in Foundry itself for the following commands:

It is kind of strange we alias --fork-url / --rpc-url , we can improve the description here.

EVM options:
  -f, --fork-url <URL>
          Fetch state over a remote endpoint instead of starting from an empty state.
          
          If you want to fetch state from a specific block number, see --fork-block-number.
          
          [aliases: --rpc-url]

      --chain <CHAIN>
          The chain name or EIP-155 chain ID
          
          [aliases: --chain-id]

In basically all cases --rpc-url is preferred over manually defining a --chain - this should almost never be necessary.

[onbjerg]

Since this was deemed to be docs, and the docs were added in https://github.com/foundry-rs/book/pull/1522, I'm closing this issue.