Requesting Chain Support

The chains supported by Sourcify are configured in the sourcifyeth/sourcify-chains repository. The Sourcify server fetches the generated sourcify-chains-default.json file from this repository at startup.

Most chains are added automatically. A CI job runs twice a day and:

Fetches the chains supported by the RPC providers (QuickNode and dRPC) and the block explorers (Etherscan and Blockscout) Sourcify uses.
Probes the provider RPCs and the public RPCs to check that the chain is alive and which trace methods it supports.
Merges the result with the manually maintained files in the repository.
Writes the merged result to sourcify-chains-default.json.

A chain is auto-included if it is available on QuickNode or dRPC, is listed in Etherscan's chainlist, or has a Blockscout explorer instance hosted by Blockscout itself. If your chain is one of these, you don't need to do anything: it will be picked up with the next generation run. Otherwise, or if your chain needs a custom configuration, please open a pull request with the instructions below for a speedy process.

Adding a chain

Make sure the new chains are listed in chainid.network (github: ethereum-lists/chains). The generator takes the public RPCs of a chain from this list if no other RPCs are configured. If your chains are not included, please first add your chains to the ethereum-lists/chains repository.
Fork the sourcify-chains repository. Branch out from the main branch with name e.g. add-chain-1-11155111 for Ethereum Mainnet (1) and Sepolia (11155111) or add-chain-1 for Ethereum Mainnet only. This branch name format is required for automated testing: the Test New Chain workflow parses the chain ids from the branch name. You can also add more than one chain in one pull request, granted you added tests for each.

Add the chain details in one of the two source files. Do not edit sourcify-chains-default.json, it is auto-generated by the CI pipeline and your changes would be overwritten.

If your chain only needs a name and the public RPCs from chainid.network, add it to additional-chains.json:
```
{
  "12345": { "sourcifyName": "My Chain Mainnet" }
}
```
Only the sourcifyName belongs in this file. The generator adds supported: true and the public RPCs at output time.
If your chain needs custom RPCs or other configuration (e.g. how to find the contract creation transaction), add it to chain-overrides.json instead. An entry in this file alone is sufficient to include the chain. A chain must not appear in both files.

Here's a full example of a chain-overrides.json entry:

{
  // the chain id
  "12345": {
    "sourcifyName": "My Chain Mainnet", // the display name. Overrides the chainid.network name

    // optional
    // Only for Etherscan-compatible explorers that are not in Etherscan's chainlist
    "etherscanApi": {
      "supported": true,
      "url": "https://api.explorer.mychain.io", // the base url of the explorer API
      "apiKeyEnvName": "ETHERSCAN_API_KEY_MYCHAIN" // optional. Omit it if the explorer does not need an api key
    },

    // optional
    "fetchContractCreationTxUsing": {
      // How to find the transaction hash that created the contract
      "etherscanApi": true, // if supported by the explorer configured in etherscanApi
      "blockscoutApi": {
        // blockscout v2 instances have an api endpoint for this
        "url": "https://explorer.mychain.io/"
      },
      "avalancheApi": true // avalanche subnets at glacier-api.avax.network have an api endpoint for this
    },

    // optional
    // RPCs defined here have a higher priority than the provider and the public RPCs.
    // Leave empty to use the provider RPCs or the public RPCs from chainid.network
    "rpc": [
      "https://rpc.mychain.io", // can be a simple url
      {
        "type": "BaseRPC", // a simple url with extra information
        "url": "https://rpc.mychain.io",
        "traceSupport": "trace_transaction" // "trace_transaction" or "debug_traceTransaction" if the RPC supports tracing
      },
      {
        "type": "FetchRequest", // ethers.js FetchRequest for header authenticated RPCs
        "url": "https://rpc.mychain.io",
        "headers": [
          {
            "headerName": "X-API-Key",
            "headerEnvName": "MYCHAIN_API_KEY" // the name of the environment variable holding the api key
          }
        ]
      }
    ]
  }
}

The allowed fields of a chain-overrides.json entry are:

Field	Description
`sourcifyName`	Display name (overrides the chainid.network name)
`etherscanApi`	Opt into Etherscan-compatible explorer support for a chain not in Etherscan's chainlist: `{ "supported": true, "url": "<base-url>", "apiKeyEnvName"?: "<ENV>" }`
`fetchContractCreationTxUsing`	Additional methods to find the contract creation transaction (`blockscoutApi`, `avalancheApi`, etc.). A `blockscoutApi` override needs only the `url`
`rpc`	RPCs with a higher priority than the auto-discovered provider RPCs. Plain RPC URLs must pass a liveness probe. Header-authenticated RPCs are kept as configured

Note that API keys and other secrets are referenced by environment variable name. These variables must be set on the Sourcify servers, so please mention them in the pull request.

Provide test contracts. The tests verify a contract on your chain, so the chain must have a known contract to verify:
1. If your chain has an instance of CreateX (deployments), Multicall3 (deployments) or the Safe v1.4.1 SafeProxyFactory (deployments) at the canonical address, you can skip this step. The tests detect these contracts automatically.
2. If not, deploy a Storage.sol contract:
  1. Using the provided script: You can easily deploy the contract with an account private key using the provided script. The script reads the RPC of the chain from sourcify-chains-default.json, so you need to generate the file for your chain first. In the repository root, run:
    npm install npm run generate -- --only <chainId> npx tsx scripts/deployContracts.ts --chainId=<chainId> --privateKey=<privateKey>
    Run npx tsx scripts/deployContracts.ts --help for more information. Do not commit the generated sourcify-chains-default.json.
  2. If you can't or don't want to paste your private key, deploy this contract in the Thirdweb dashboard through the wallet of your choice.
  3. Add the contract address on your chain to storage-contract-chain-addresses.json.

To test locally, build a chains config for your chain and run the chain test against a Sourcify server in Docker. Note that this requires Node 22+ and docker compose, and that DRPC_API_KEY and QUICKNODE_API_KEY are required because the server does not start without them. If you don't have these keys, you can rely on the test run on your pull request.

npm install
npm run generate -- --only <chainId> # multiple chains: --only 1,11155111

# Fill in the keys in .secrets and load them into your shell
cp .secrets.dev .secrets
set -a; source .secrets; set +a

# Start the Sourcify server
docker compose -f tests/docker-compose.yml up -d postgres
bash tests/migrate.sh
docker compose -f tests/docker-compose.yml up -d sourcify

# Run the test for your chain(s)
NEW_CHAIN_ID=<chainId> npm run test:integration:chain

# Clean up
docker compose -f tests/docker-compose.yml down -v
git checkout sourcify-chains-default.json

If the tests pass, open a pull request targeting the sourcify-chains main branch. The Test New Chain workflow runs the same test in CI for the chain ids in your branch name.

If the tests pass, the chain will be added quickly. After your pull request is merged, the generation workflow runs and opens a pull request that regenerates sourcify-chains-default.json. Once this pull request is merged, the new file is released and the Sourcify servers are restarted, so the chain is available on sourcify.dev right away.

Deprecating a chain

If a chain is not maintained anymore, add its chain id and name to deprecated-chains.json. If the chain is also in additional-chains.json, remove it from there too. Deprecated chains will have supported: false in the output, even if they are still auto-discovered.

If the tests for a chain will fail two weeks in a row, we will assume the chain is not being maintained and remove it from the supported chains list. The tests run twice a day in the Integration tests workflow of the sourcify-chains repository. Chains that are left with no live RPC are deprecated automatically by the generation workflow.

Adding a chain​

Deprecating a chain​

Adding a chain

Deprecating a chain