@phase21/chains

API3 chains

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

📦 Installation

npm install @phase21/chains --save
yarn add @phase21/chains
pnpm add @phase21/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 '@phase21/chains';
console.log(CHAINS);
/*
[
  {
    name: 'Arbitrum testnet',
    alias: 'arbitrum-goerli-testnet',
    id: '421613',
    ...
  },
  ...
]
*/

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_GOERLI_TESTNET.

import { hardhatConfig } from '@phase21/chains';
console.log(hardhatConfig.networks());
/*
{
  "arbitrum-goerli-testnet": {
      accounts: { mnemonic: '' },
      chainId: '421613',
      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 '@phase21/chains';
console.log(hardhatConfig.etherscan());
/*
{
  apiKey: {
    'arbitrumGoerli': { ... }
  },
  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 '@phase21/chains';
console.log(hardhatConfig.getEnvVariableNames());
/*
[
  'MNEMONIC',
  'ETHERSCAN_API_KEY_ARBITRUM_GOERLI_TESTNET',
  ...
  'HARDHAT_HTTP_RPC_URL_ARBITRUM_GOERLI_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 '@phase21/chains';
console.log(viemConfig.chains());
/*
[
  {
    id: 421613,
    name: 'arbitrum-goerli-testnet',
    network: 'arbitrum-goerli-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

yarn generate:chains

providers:ping

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

yarn 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

yarn 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
yarn validate:chains

# Run all validations
yarn validate

Package update

Run the following command to update the package:

yarn changeset

Then follow the instructions in the terminal:

🦋  What kind of change is this for chains? (current version is x.x.x)
❯ patch
  minor
  major

🦋  Please enter a summary for this change (this will be in the changelogs).
🦋    (submit empty line to open external editor)
🦋  Summary ›  [CHANGES]

After that, you will be asked to confirm the changeset:

🦋  Summary › [CHANGES]
🦋
🦋  === Summary of changesets ===
🦋  patch:  chains
🦋
🦋  Is this your desired changeset? (Y/n) › true

If you confirm, the changeset will be created and you will be asked to publish it:

🦋  Changeset added! - you can now commit it
🦋
🦋  If you want to modify or expand on the changeset summary, you can find it here
🦋  info .changeset/[MD_FILE]
✨  Done.

Commit the changeset and push it to the repository:

git add .
git commit -m "chore: update chains"
git push

Merge the changeset to the main branch:

git checkout main
git merge [BRANCH_NAME]
git push

To publish the package, merge main to the production branch:

git checkout production
git merge main
git push

Changeset will raise a PR to the production branch. After the PR is merged, the package will be published to npm.