API3 chains

The single source of truth for chain-related information across API3 projects

📦 Installation

npm install @api3/chains --save
yarn add @api3/chains
pnpm add @api3/chains

📖 API

The following variables/functions are exported from this package

CHAINS

The single source of truth for the list of supported chains. A static array of Chain objects.

import { CHAINS } from '@api3/chains';
console.log(CHAINS);
/*
[
  {
    name: 'Arbitrum Sepolia testnet',
    alias: 'arbitrum-sepolia-testnet',
    id: '421614',
    ...
  },
  ...
]
*/

hardhatConfig.networks()

Returns an object where the key is each chain's alias and the value is an object that can be used as the networks field of hardhat.config.js.

The default url values can be overridden with chain specific environment variables. These environment variables take the form of HARDHAT_HTTP_RPC_URL_${toUpperSnakeCase(chain.alias)}. e.g. HARDHAT_HTTP_RPC_URL_ARBITRUM_SEPOLIA_TESTNET.

import { hardhatConfig } from '@api3/chains';
console.log(hardhatConfig.networks());
/*
{
  "arbitrum-sepolia-testnet": {
      accounts: { mnemonic: '' },
      chainId: '421614',
      url: 'https://...',
  },
  ...
}
*/

hardhatConfig.etherscan()

Returns an object where the key is each chain's alias and the value is an object that can be used as the etherscan field of hardhat.config.js (requires the hardhat-etherscan plugin).

NOTE: hardhat-etherscan requires us to use a dummy API key with Blockscout block explorer APIs. We use "DUMMY_VALUE" but it could have been anything else.

import { hardhatConfig } from '@api3/chains';
console.log(hardhatConfig.etherscan());
/*
{
  apiKey: {
    'arbitrumSepolia': { ... }
  },
  customChains: [
    ...
  ]
}
*/

hardhatConfig.getEnvVariableNames()

Returns an array of expected environment variable names for chains that have an API key required for the explorer. The array also includes a single MNEMONIC variable that can be used to configure all networks.

NOTE: Each ETHERSCAN_API_KEY_ and HARDHAT_HTTP_RPC_URL_ environment variable has the chain alias as a suffix, where the alias has been converted to upper snake case.

import { hardhatConfig } from '@api3/chains';
console.log(hardhatConfig.getEnvVariableNames());
/*
[
  'MNEMONIC',
  'ETHERSCAN_API_KEY_ARBITRUM_SEPOLIA_TESTNET',
  ...
  'HARDHAT_HTTP_RPC_URL_ARBITRUM_SEPOLIA_TESTNET',
  ...
]
*/

viemConfig.chains()

Returns an array of chains in the format that Viem expects. Each Chain object can be used to create a Viem public client.

Additional rpcUrls values can (optionally) be added through the use of environment variables. These environment variables take the form of API3_CHAINS_HTTP_RPC_URL_${toUpperSnakeCase(chain.alias)}. If a matching environment variable is detected for a given chain, then it will be added to the http array of the rpcUrls.environment object. If no matching environment variable is detected, then the http array is left empty.

import { viemConfig } from '@api3/chains';
console.log(viemConfig.chains());
/*
[
  {
    id: 421613,
    name: 'arbitrum-sepolia-testnet',
    network: 'arbitrum-sepolia-testnet',
    rpcUrls: { default: ..., public: ..., environment: ... }
    ...
  },
  ...
]
*/

Types

Types are also exported and can be found in src/types.ts. Types are generated from zod schemas. These schemas are also used to validate each chain.

📄 Scripts

The following utility scripts are available

generate:chains

Generates the latest CHAINS array and outputs the file to src/generated/chains.ts

pnpm generate:chains

providers:ping

Iterates through the list of chains to check that the chain is configured correctly and is responsive.

pnpm providers:ping

🛠️ Development

The most common type of change would be adding or updating a chain. This can be done by creating or editing the relevant JSON file in the chains/ directory.

If any changes are made to chains, you will need to "regenerate" the chains. This will compile all of the JSON files into a single TypeScript file for projects to import. This can be done with the following command

pnpm generate:chains

The list of TypeScript chains is also validated against all of the list of JSON files to ensure that everything is in sync.

NOTE: You will not be able to push changes to chains without having regenerated the TypeScript chains.

Validation

Validations can be run with the following commands.

# Validate each chain JSON file conforms to the zod schemas
pnpm validate:chains

# Run all validations
pnpm validate

🚢 Releasing

Releasing new versions is handled automatically with changesets. Pull requests should include a changeset file before being merged. These can be generated by running pnpm changeset and following the instructions. Once a new version is ready to be released, simply merge main into the production branch. Changeset files will be consolidated into a single new version and that version released to npm.

More information is contained in the API3 guidelines.