@api3/contracts

@api3/contracts

Contracts through which Api3 services are delivered

This package provides the tools to integrate data feeds that can be found at the Api3 Market. The typical workflow is as follows:

• Purchase data feed subscriptions and get the respective proxy addresses at the Api3 Market
• Use the proxy address computation utility function provided by this package (computeCommunalApi3ReaderProxyV1Address()) to validate the proxy addresses being used
• Use the proxy contract interfaces provided by this package in the reader contract, as demonstrated in https://github.com/api3dao/data-feed-reader-example

A more complete list of what this package includes is as follows:

• All contracts that facilitate Api3 data feed services, including OEV auctions
• @typechain/ethers-v6 typings of these contracts
• Addresses of the Api3 deployments of these contracts
• Proxy address computation utility functions

🛡️ Security

We have conducted 10+ audits of our contracts and their off-chain components. Below are the reports of the ones that are directly related to the contracts in this repo (or in some cases, earlier versions of them).

• 2024-10-24 Quantstamp (refer to here for the commit hash)
• 2024-02-20 Quantstamp
• 2023-12-20 Quantstamp
• 2023-03-02 Sigma Prime
• 2022-03-30 Trail of Bits
• 2021-12-16 Sigma Prime

For bug reports, contact [e-mail]

🛠️ 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 data/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. Please check the Developer instructions section for more information on how to do this.

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.

💻 Developer instructions

Install the dependencies and build

pnpm i && pnpm build

Test the contracts, get coverage and gas reports

pnpm test
pnpm test:extended
# Outputs to `./coverage`
pnpm test:coverage
# Outputs to `gas_report`
pnpm test:gas

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

pnpm generate:chains

Generate the latest DAPPS array and outputs the file to src/generated/dapps.ts

pnpm generate:dapps

Generate deployment addresses for all chains and outputs the file to src/generated/deployments.ts

pnpm generate:deployment-addresses

Generate all of the above files in one go

pnpm generate

Check the local files containing metadata

pnpm check

Verify that the vendor contracts are identical to the ones from their respective packages.

pnpm verify-vendor-contracts

Verify the deployments and validate their current state

# on all chains
pnpm verify-deployments
# or a single chain
NETWORK=ethereum pnpm verify-deployments
# on all chains
pnpm validate-deployments
# or a single chain
NETWORK=ethereum pnpm validate-deployments

📖 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/contracts';
console.log(CHAINS);
/*
[
  {
    name: 'Arbitrum testnet',
    alias: 'arbitrum-sepolia-testnet',
    id: '421614',
    ...
  },
  ...
]
*/

DAPPS

The single source of truth for the list of supported dApps. A static array of Dapp objects.

import { DAPPS } from '@api3/contracts';
console.log(DAPPS);
/*
[
  {
    aliases: {
      'compound-finance-usde': {
        chains: ['mantle'],
        title: '...',
        description: '...',
      },
    },
    homepageUrl: 'https://...',
  }
  ...
]
*/

deploymentAddresses

An object that contains the deployment addresses of all contracts on all chains. The keys are contract names and the values are objects where the keys are chain IDs and the values are the contract addresses.

import { deploymentAddresses } from '@api3/contracts';
console.log(deploymentAddresses);
/*
{
  "GnosisSafeWithoutProxy": {
    "1": "0x...",
    "10": "0x...",
    "56": "0x...",
    ...
  },
  "OwnableCallForwarder": {
    "1": "0x...",
    "10": "0x...",
    "56": "0x...",
    ...
  },
  ...
}
*/

auctioneerMetadata

An object that contains auctioneer metadata.

import { auctioneerMetadata } from '@api3/contracts';
console.log(auctioneerMetadata);
/*
{
  "auction-resolvers": ["0x..."],
  "auction-cops": ["0x..."]
}
*/

dapiManagementMetadata

An object that contains merkle tree signers.

import { dapiManagementMetadata } from '@api3/contracts';
console.log(dapiManagementMetadata);
/*
{
  "dapiManagementMerkleRootSigners": [
    "0x...",
    "0x..."
  ],
  "dapiPricingMerkleRootSigners": [
    "0x...",
    "0x..."
  ],
  "signedApiUrlMerkleRootSigners": [
    "0x...",
    "0x..."
  ]
}
*/

unsafeComputeDappId

Computes the dApp ID for a given dApp alias and chain ID. This function is unsafe because it does not validate the inputs, so it should only be used when the inputs are guaranteed to be correct.

import { unsafeComputeDappId } from '@api3/contracts';
const dappId = unsafeComputeDappId('dtrinity', '252');
console.log(dappId);
/*
16210721173577624589952893185091679941657223823840386808143855919126917477566n
*/

computeApi3ReaderProxyV1Address

Computes the Api3ReaderProxyV1 address for a given chain ID, dAPI name, dApp ID and metadata.

import { computeApi3ReaderProxyV1Address } from '@api3/contracts';
const address = computeApi3ReaderProxyV1Address(
  '1',
  'ETH/USD',
  '16210721173577624589952893185091679941657223823840386808143855919126917477566',
  '0x'
);
console.log(address);
/*
0xC93Da088b0c78dE892f523db0eECb051Cb628991
*/

computeCommunalApi3ReaderProxyV1Address

Computes the Api3ReaderProxyV1 address being used by Api3 Market for a given dAPI name and chain ID.

import { computeCommunalApi3ReaderProxyV1Address } from '@api3/contracts';
const address = computeCommunalApi3ReaderProxyV1Address('1', 'ETH/USD');
console.log(address);
/*
0x5b0cf2b36a65a6BB085D501B971e4c102B9Cd473
*/

computeDappSpecificApi3ReaderProxyV1Address

Computes the dApp-specific Api3ReaderProxyV1 address for a given dApp alias, chain ID, and dAPI name. This function is useful for retrieving the proxy address for a specific dApp on a specific chain.

import { computeDappSpecificApi3ReaderProxyV1Address } from '@api3/contracts';
const address = computeDappSpecificApi3ReaderProxyV1Address('dtrinity', '252', 'BTC/USD');
console.log(address);
/*
0x781d431031Ffd5273585e65F663699Dcb74834E6
*/

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/contracts';
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/contracts';
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/contracts';
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/contracts';
console.log(viemConfig.chains());
/*
[
  {
    id: 421613,
    name: 'arbitrum-sepolia-testnet',
    network: 'arbitrum-sepolia-testnet',
    rpcUrls: { default: ..., public: ..., environment: ... }
    ...
  },
  ...
]
*/

Types

Types exported in src/types.ts are generated from zod schemas, which are also used to validate each chain. Contract-related types generated by TypeChain can be found in typechain-types after building the project.

⚙️ CLI

This CLI provides utility commands for calculating dApp IDs and retrieving important on-chain information such as proxy addresses.

print-api3readerproxyv1-address

Prints the dApp-specific Api3ReaderProxyV1 address for a given dApp alias and chain ID.

npx @api3/contracts print-api3readerproxyv1-address --dapp-alias lendle --chain-id 5000 --dapi-name ETH/USD

compute-dapp-id

Computes the dApp ID for a given dApp alias and chain ID.

npx @api3/contracts compute-dapp-id --dapp-alias mach-finance --chain-id 146

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