Skip to main content

Requesting Chain Support

To request an EVM chain(s) to be supported by Sourcify, please open a pull request in the sourcify-chains repository with the instructions below:

  1. Make sure the new chains are listed in chains.json (github: ethereum-lists/chains). If your chain is not included there, please add it first. It will be picked up automatically in the next sourcify-chains generation run.

  2. Fork the sourcify-chains repository. Branch out from the main branch with a name like add-chain-1-11155111 for Ethereum Mainnet (1) and Sepolia (11155111), or add-chain-1 for a single chain. This branch name format is used to identify new chains in automated testing.

  3. Add the chain details to chain-overrides.json (for chains already present in chainid.network) or additional-chains.json (for chains not yet in chainid.network). Set supported: true and fill in the relevant fields.

Here's a full example of a chain entry:

{
  // the chain id
  "1": {
    "sourcifyName": "Ethereum Mainnet", // required
    "supported": true, // required

    // optional
    "etherscanApi": {
      "apiURL": "https://api.etherscan.io",
      "apiKeyEnvName": "ETHERSCAN_API_KEY" // the name of the environment variable holding the api key
    },

    // optional
    "fetchContractCreationTxUsing": {
      // How to find the transaction hash that created the contract
      "etherscanApi": true, // if supported by the new etherscan api. Need to provide the etherscanApi config
      "blockscoutApi": {
        // blockscout v2 instances have an api endpoint for this
        "url": "https://gnosis.blockscout.com/"
      },
      "blockscoutScrape": {
        // scraping from old (server-side rendered) blockscout ui
        "url": "https://scan.pulsechain.com/"
      },
      "avalancheApi": true // avalanche subnets at glacier-api.avax.network have an api endpoint for this
    },

    // optional
    // Leave empty to use the default rpcs in chains.json i.e. chainid.network/chains.json
    "rpc": [
      "https://rpc.sepolia.io", // can be a simple url
      {
        "type": "FetchRequest", // ethers.js FetchRequest for header authenticated RPCs
        "url": "https://rpc.mainnet.ethpandaops.io",
        "headers": [
          {
            "headerName": "CF-Access-Client-Id",
            "headerEnvName": "CF_ACCESS_CLIENT_ID"
          },
          {
            "headerName": "CF-Access-Client-Secret",
            "headerEnvName": "CF_ACCESS_CLIENT_SECRET"
          }
        ]
      },
      {
        "type": "Alchemy", // Alchemy RPCs
        "url": "https://eth-mainnet.alchemyapi.io/v2/{ALCHEMY_API_KEY}",
        "apiKeyEnvName": "ALCHEMY_API_KEY"
      },
      {
        "type": "Infura", // Infura RPCs
        "url": "https://palm-mainnet.infura.io/v3/{INFURA_API_KEY}",
        "apiKeyEnvName": "INFURA_API_KEY"
      }
    ]
  }
}

  1. Provide test contracts:

    1. If your chain has an instance of CreateX (deployments) or Multicall3 (deployments), you can skip this step.
    2. If not, deploy a Storage.sol contract:
      1. Using the provided script: Deploy the contract with an account private key using the deployContracts.ts script. Inside the sourcify-chains repo, run npx tsx scripts/deployContracts.ts --help for more information.
      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

  2. If the tests pass, open a pull request targeting the sourcify-chains main branch.

If the tests pass, the chain will be added to the Sourcify server configuration quickly. The server picks up the updated chain config from the sourcify-chains repo on each deployment.

If the tests for a chain fail two weeks in a row, we will assume the chain is not being maintained and remove it from the supported chains list. The automated tests run twice daily and can be seen under the integration-tests workflow.