Skip to main content

Requesting Chain Support

Do you want to verify contracts on an EVM chain (or chains)? Great! We don't want to be the single source of truth and encourage you to run your own Sourcify server instance.

If you still want to request an EVM chain(s) to be supported by Sourcify, please open a pull request with the instructions below for a speedy process:

  1. Make sure the new chains are listed in chains.json but this file should not be edited. It is kept in sync with chainid.network (github: ethereum-lists/chains) periodically. If your chains are not included, please first add your chains to the ethereum-lists/chains repository first.

  2. Fork the repository. Branch out from the staging 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. You can also add more than one chains in one pull request, granted you added tests for each.

  3. Add the chain details in sourcify-chains-default.json similar to other chains with supported: true.

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. Install and build the project with npm install and npx lerna run build.

  2. Provide test contracts:

    1. Deploy test contracts:
      1. Using the provided script: You can easily deploy both contracts with an account private key using the provided script, that can be run with ts-node. Inside services/server, run npx ts-node test/chains/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.
    2. If you are not able to deploy new test contracts above (e.g. because it costs on a mainnet) you can provide existing contracts. Create a folder services/server/test/chains/sources/{chainId} and store the contract source files and metadata of already deployed contracts there.

  3. Add the test for the new chains in services/server/test/chains/chain-tests.spec.ts similar to other chains. If you deployed a test contract as described above, the contract and the metadata are the following:

    • Storage.sol: shared/1_Storage.sol and shared/1_Storage.metadata.json

  4. To test locally run export NEW_CHAIN_ID=1,11155111 && npm run test-local:chains inside services/server. Note that this requires docker-compose.

  5. If the tests pass, open a pull request targeting the Sourcify staging branch.

If the tests pass, the chain will be added quickly. The chain will be added to production (master branch) with the next release, which usually happens in 1-2 weeks.

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 can be seen in CircleCI under "test-chains-regularly" workflow