{"id":20093931,"url":"https://github.com/api3dao/contracts","last_synced_at":"2026-04-10T15:12:52.607Z","repository":{"id":156385276,"uuid":"611632724","full_name":"api3dao/contracts","owner":"api3dao","description":"Contracts through which Api3 services are delivered","archived":false,"fork":false,"pushed_at":"2025-04-29T12:36:42.000Z","size":7942,"stargazers_count":11,"open_issues_count":22,"forks_count":5,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-04-29T13:51:35.285Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/api3dao.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"audit-reports/2021-12-16 Sigma Prime.pdf","citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-03-09T08:20:12.000Z","updated_at":"2025-04-29T12:35:42.000Z","dependencies_parsed_at":null,"dependency_job_id":"d882d055-848a-4a2c-8294-ff3d4db9c900","html_url":"https://github.com/api3dao/contracts","commit_stats":null,"previous_names":[],"tags_count":87,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/api3dao%2Fcontracts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/api3dao%2Fcontracts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/api3dao%2Fcontracts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/api3dao%2Fcontracts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/api3dao","download_url":"https://codeload.github.com/api3dao/contracts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252622427,"owners_count":21777989,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T16:48:51.161Z","updated_at":"2026-04-10T15:12:52.595Z","avatar_url":"https://github.com/api3dao.png","language":"TypeScript","readme":"# @api3/contracts\n\n\u003cdiv align=\"center\"\u003e\n\n[![npm version](https://img.shields.io/npm/v/%40api3%2Fcontracts)](https://www.npmjs.com/package/@api3/contracts)\n![downloads per week](https://img.shields.io/npm/dw/%40api3%2Fcontracts)\n[![continuous-build](https://img.shields.io/github/actions/workflow/status/api3dao/contracts/continuous-build.yml?label=continuous-build)](https://github.com/api3dao/contracts/actions/workflows/continuous-build.yml)\n[![validate-verify](https://img.shields.io/github/actions/workflow/status/api3dao/contracts/validate-verify.yml?label=validate-verify)](https://github.com/api3dao/contracts/actions/workflows/validate-verify.yml)\n[![license](https://img.shields.io/npm/l/%40api3%2Fchains)](https://www.npmjs.com/package/@api3/contracts)\n\n\u003c/div\u003e\n\n\u003e Contracts through which Api3 services are delivered\n\nThis package provides the tools to integrate data feeds that can be found at the [Api3 Market](https://market.api3.org). The typical workflow is as follows:\n\n1. Purchase data feed subscriptions and get the respective proxy addresses at the Api3 Market\n2. Use the proxy address computation utility function provided by this package (`computeCommunalApi3ReaderProxyV1Address()`) to validate the proxy addresses being used\n3. Use the proxy contract interfaces provided by this package in the reader contract, as demonstrated in https://github.com/api3dao/data-feed-reader-example\n\nA more complete list of what this package includes is as follows:\n\n- All contracts that facilitate Api3 data feed services, including OEV auctions\n- `@typechain/ethers-v6` typings of these contracts\n- Addresses of the Api3 deployments of these contracts\n- Proxy address computation utility functions\n\n## 🛡️ Security\n\nWe have conducted 10+ audits of our contracts and their off-chain components.\nBelow are the reports of the ones that are directly related to the contracts in this repo (or in some cases, earlier versions of them).\n\n- [2024-10-24 Quantstamp](./audit-reports/2024-10-24%20Quantstamp.pdf) (refer to [here](https://github.com/api3dao/contracts-qs/tree/final-report) for the commit hash)\n- [2024-02-20 Quantstamp](./audit-reports/2024-02-20%20Quantstamp.pdf)\n- [2023-12-20 Quantstamp](./audit-reports/2023-12-20%20Quantstamp.pdf)\n- [2023-03-02 Sigma Prime](./audit-reports/2023-03-02%20Sigma%20Prime.pdf)\n- [2022-03-30 Trail of Bits](./audit-reports/2022-03-30%20Trail%20of%20Bits.pdf)\n- [2021-12-16 Sigma Prime](./audit-reports/2021-12-16%20Sigma%20Prime.pdf)\n\nFor bug reports, contact `security@api3.org`\n\n## 🛠️ Development\n\nThe 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.\n\nIf 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](#-developer-instructions) section for more information on how to do this.\n\nThe list of TypeScript chains is also validated against all of the list of JSON files to ensure that everything is in sync.\n\nNOTE: You will not be able to push changes to chains without having regenerated the TypeScript chains.\n\n## 💻 Developer instructions\n\nInstall the dependencies and build\n\n```sh\npnpm i \u0026\u0026 pnpm build\n```\n\nTest the contracts, get coverage and gas reports\n\n```sh\npnpm test\npnpm test:extended\n# Outputs to `./coverage`\npnpm test:coverage\n# Outputs to `gas_report`\npnpm test:gas\n```\n\nGenerate the latest `CHAINS` array and outputs the file to `src/generated/chains.ts`\n\n```sh\npnpm generate:chains\n```\n\nGenerate the latest `DAPPS` array and outputs the file to `src/generated/dapps.ts`\n\n```sh\npnpm generate:dapps\n```\n\nGenerate deployment addresses for all chains and outputs the file to `src/generated/deployments.ts`\n\n```sh\npnpm generate:deployment-addresses\n```\n\nGenerate all of the above files in one go\n\n```sh\npnpm generate\n```\n\nCheck the local files containing metadata\n\n```sh\npnpm check\n```\n\nVerify that the vendor contracts are identical to the ones from their respective packages.\n\n```sh\npnpm verify-vendor-contracts\n```\n\nVerify the deployments and validate their current state\n\n```sh\n# on all chains\npnpm verify-deployments\n# or a single chain\nNETWORK=ethereum pnpm verify-deployments\n# on all chains\npnpm validate-deployments\n# or a single chain\nNETWORK=ethereum pnpm validate-deployments\n```\n\n## 📖 API\n\nThe following variables/functions are exported from this package\n\n### CHAINS\n\nThe single source of truth for the list of supported chains.\nA static array of `Chain` objects.\n\n```ts\nimport { CHAINS } from '@api3/contracts';\nconsole.log(CHAINS);\n/*\n[\n  {\n    name: 'Arbitrum testnet',\n    alias: 'arbitrum-sepolia-testnet',\n    id: '421614',\n    ...\n  },\n  ...\n]\n*/\n```\n\n### DAPPS\n\nThe single source of truth for the list of supported dApps.\nA static array of `Dapp` objects.\n\n```ts\nimport { DAPPS } from '@api3/contracts';\nconsole.log(DAPPS);\n/*\n[\n  {\n    aliases: {\n      'compound-finance-usde': {\n        chains: ['mantle'],\n        title: '...',\n        description: '...',\n      },\n    },\n    homepageUrl: 'https://...',\n  }\n  ...\n]\n*/\n```\n\n### deploymentAddresses\n\nAn 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.\n\n```ts\nimport { deploymentAddresses } from '@api3/contracts';\nconsole.log(deploymentAddresses);\n/*\n{\n  \"GnosisSafeWithoutProxy\": {\n    \"1\": \"0x...\",\n    \"10\": \"0x...\",\n    \"56\": \"0x...\",\n    ...\n  },\n  \"OwnableCallForwarder\": {\n    \"1\": \"0x...\",\n    \"10\": \"0x...\",\n    \"56\": \"0x...\",\n    ...\n  },\n  ...\n}\n*/\n```\n\n### auctioneerMetadata\n\nAn object that contains auctioneer metadata.\n\n```ts\nimport { auctioneerMetadata } from '@api3/contracts';\nconsole.log(auctioneerMetadata);\n/*\n{\n  \"auction-resolvers\": [\"0x...\"],\n  \"auction-cops\": [\"0x...\"]\n}\n*/\n```\n\n### dapiManagementMetadata\n\nAn object that contains merkle tree signers.\n\n```ts\nimport { dapiManagementMetadata } from '@api3/contracts';\nconsole.log(dapiManagementMetadata);\n/*\n{\n  \"dapiManagementMerkleRootSigners\": [\n    \"0x...\",\n    \"0x...\"\n  ],\n  \"dapiPricingMerkleRootSigners\": [\n    \"0x...\",\n    \"0x...\"\n  ],\n  \"signedApiUrlMerkleRootSigners\": [\n    \"0x...\",\n    \"0x...\"\n  ]\n}\n*/\n```\n\n### unsafeComputeDappId\n\nComputes 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.\n\n```ts\nimport { unsafeComputeDappId } from '@api3/contracts';\nconst dappId = unsafeComputeDappId('dtrinity', '252');\nconsole.log(dappId);\n/*\n16210721173577624589952893185091679941657223823840386808143855919126917477566n\n*/\n```\n\n### computeApi3ReaderProxyV1Address\n\nComputes the Api3ReaderProxyV1 address for a given chain ID, dAPI name, dApp ID and metadata.\n\n```ts\nimport { computeApi3ReaderProxyV1Address } from '@api3/contracts';\nconst address = computeApi3ReaderProxyV1Address(\n  '1',\n  'ETH/USD',\n  '16210721173577624589952893185091679941657223823840386808143855919126917477566',\n  '0x'\n);\nconsole.log(address);\n/*\n0xC93Da088b0c78dE892f523db0eECb051Cb628991\n*/\n```\n\n### computeCommunalApi3ReaderProxyV1Address\n\nComputes the Api3ReaderProxyV1 address being used by Api3 Market for a given dAPI name and chain ID.\n\n```ts\nimport { computeCommunalApi3ReaderProxyV1Address } from '@api3/contracts';\nconst address = computeCommunalApi3ReaderProxyV1Address('1', 'ETH/USD');\nconsole.log(address);\n/*\n0x5b0cf2b36a65a6BB085D501B971e4c102B9Cd473\n*/\n```\n\n### computeDappSpecificApi3ReaderProxyV1Address\n\nComputes 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.\n\n```ts\nimport { computeDappSpecificApi3ReaderProxyV1Address } from '@api3/contracts';\nconst address = computeDappSpecificApi3ReaderProxyV1Address('dtrinity', '252', 'BTC/USD');\nconsole.log(address);\n/*\n0x781d431031Ffd5273585e65F663699Dcb74834E6\n*/\n```\n\n### hardhatConfig.blockscout()\n\nReturns an object that can be used as the `blockscout` field of [`hardhat.config.js`](https://hardhat.org/hardhat-runner/docs/config) (requires the [`hardhat-etherscan` plugin](https://v2.hardhat.org/hardhat-runner/plugins/nomicfoundation-hardhat-verify)).\n\nIt includes a `customChains` field that includes all chains that support Blockscout contract verification API.\n\n```ts\nimport { hardhatConfig } from '@api3/contracts';\nconsole.log(hardhatConfig.blockscout());\n/*\n{\n  enabled: true,\n  customChains: [\n    ...\n  ]\n}\n*/\n```\n\n### hardhatConfig.networks()\n\nReturns 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`](https://v2.hardhat.org/hardhat-runner/docs/config).\n\nThe 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`.\n\n```ts\nimport { hardhatConfig } from '@api3/contracts';\nconsole.log(hardhatConfig.networks());\n/*\n{\n  \"arbitrum-sepolia-testnet\": {\n      accounts: { mnemonic: '' },\n      chainId: '421614',\n      url: 'https://...',\n  },\n  ...\n}\n*/\n```\n\n### hardhatConfig.etherscan()\n\nReturns an object that can be used as the `etherscan` field of [`hardhat.config.js`](https://v2.hardhat.org/hardhat-runner/docs/config) (requires the [`hardhat-etherscan` plugin](https://v2.hardhat.org/hardhat-runner/plugins/nomicfoundation-hardhat-verify)).\n\nIt includes an `apiKey` field that can be set through the `ETHERSCAN_API_KEY` environment variable. And a `customChains` field that includes all chains that support Etherscan V2 contract verification API.\n\n```ts\nimport { hardhatConfig } from '@api3/contracts';\nconsole.log(hardhatConfig.etherscan());\n/*\n{\n  apiKey: someApiKey,\n  customChains: [\n    ...\n  ]\n}\n*/\n```\n\n### hardhatConfig.getEnvVariableNames()\n\nReturns environment variable names that are expected to be set for Hardhat configuration.\n\n```ts\nimport { hardhatConfig } from '@api3/contracts';\nconsole.log(hardhatConfig.getEnvVariableNames());\n/*\n[\n  'MNEMONIC',\n  'KEYCARD_ACCOUNT',\n  'ETHERSCAN_API_KEY',\n  'HARDHAT_HTTP_RPC_URL_APECHAIN_ARBITRUM_SEPOLIA_TESTNET',\n  ...\n]\n*/\n```\n\n### viemConfig.chains()\n\nReturns an array of chains in the format that [Viem](https://viem.sh/docs/chains/introduction) expects. Each Chain object can be used to [create a Viem public client](https://viem.sh/docs/clients/public#usage).\n\nAdditional `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.\n\n```ts\nimport { viemConfig } from '@api3/contracts';\nconsole.log(viemConfig.chains());\n/*\n[\n  {\n    id: 421613,\n    name: 'arbitrum-sepolia-testnet',\n    network: 'arbitrum-sepolia-testnet',\n    rpcUrls: { default: ..., public: ..., environment: ... }\n    ...\n  },\n  ...\n]\n*/\n```\n\n### Types\n\nTypes exported in `src/types.ts` are generated from [zod](https://github.com/colinhacks/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.\n\n## ⚙️ CLI\n\nThis CLI provides utility commands for calculating dApp IDs and retrieving important on-chain information such as proxy addresses.\n\n### print-api3readerproxyv1-address\n\nPrints the dApp-specific Api3ReaderProxyV1 address for a given dApp alias and chain ID.\n\n```sh\nnpx @api3/contracts print-api3readerproxyv1-address --dapp-alias lendle --chain-id 5000 --dapi-name ETH/USD\n```\n\n### compute-dapp-id\n\nComputes the dApp ID for a given dApp alias and chain ID.\n\n```sh\nnpx @api3/contracts compute-dapp-id --dapp-alias mach-finance --chain-id 146\n```\n\n## 📦 Releasing\n\nReleasing new versions is handled automatically with [changesets](https://github.com/changesets/changesets). Pull requests should include a changeset file before being merged.\nThese 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`\nbranch. Changeset files will be consolidated into a single new version and that version released to npm.\n\n\u003c!-- markdown-link-check-disable --\u003e\n\nMore information is contained in the [Api3 guidelines](https://github.com/api3dao/tasks/blob/main/API3%20Packages/changeset.md).\n\n\u003c!-- markdown-link-check-enable --\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapi3dao%2Fcontracts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapi3dao%2Fcontracts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapi3dao%2Fcontracts/lists"}