Repository files navigation

npm install @api3/chains --saveyarn add @api3/chainspnpm add @api3/chains

The following variables/functions are exported from this package

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

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

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

The defaulturl values can be overridden with chain specific environment variables. These environment variables take the form ofHARDHAT_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://...',  },  ...}*/

Returns an object where the key is each chain's alias and the value is an object that can be used as theetherscan field ofhardhat.config.js (requires thehardhat-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: [    ...  ]}*/

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

NOTE: EachETHERSCAN_API_KEY_ andHARDHAT_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',  ...]*/

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

AdditionalrpcUrls values can (optionally) be added through the use of environment variables. These environment variables take the form ofAPI3_CHAINS_HTTP_RPC_URL_${toUpperSnakeCase(chain.alias)}. If a matching environment variable is detected for a given chain, then it will be added to thehttp array of therpcUrls.environment object. If no matching environment variable is detected, then thehttp 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 are also exported and can be found insrc/types.ts.Types are generated fromzod schemas.These schemas are also used to validate each chain.

The following utility scripts are available

Generates the latestCHAINS array and outputs the file tosrc/generated/chains.ts

pnpm generate:chains

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

pnpm providers:ping

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 thechains/ 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.

Validations can be run with the following commands.

# Validate each chain JSON file conforms to the zod schemaspnpm validate:chains# Run all validationspnpm validate

Releasing new versions is handled automatically withchangesets. Pull requests should include a changeset file before being merged.These can be generated by runningpnpm changeset and following the instructions. Once a new version is ready to be released, simply mergemain into theproductionbranch. Changeset files will be consolidated into a single new version and that version released to npm.

More information is contained in theAPI3 guidelines.