{"id":13746566,"url":"https://github.com/circlefin/stablecoin-evm","last_synced_at":"2025-04-13T18:34:23.632Z","repository":{"id":37861138,"uuid":"120320310","full_name":"circlefin/stablecoin-evm","owner":"circlefin","description":"Source repository for smart contracts used by Circle's stablecoins on EVM-compatible blockchains","archived":false,"fork":false,"pushed_at":"2025-03-11T18:56:02.000Z","size":2813,"stargazers_count":591,"open_issues_count":74,"forks_count":406,"subscribers_count":35,"default_branch":"master","last_synced_at":"2025-04-06T15:08:10.362Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/circlefin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-02-05T15:05:54.000Z","updated_at":"2025-04-04T03:22:36.000Z","dependencies_parsed_at":"2023-11-09T14:47:13.079Z","dependency_job_id":"5bc6ceaf-0839-4864-938b-5ccac228c154","html_url":"https://github.com/circlefin/stablecoin-evm","commit_stats":null,"previous_names":["circlefin/stablecoin-evm","centrehq/centre-tokens"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circlefin%2Fstablecoin-evm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circlefin%2Fstablecoin-evm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circlefin%2Fstablecoin-evm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circlefin%2Fstablecoin-evm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/circlefin","download_url":"https://codeload.github.com/circlefin/stablecoin-evm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248761026,"owners_count":21157476,"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-08-03T06:00:55.616Z","updated_at":"2025-04-13T18:34:23.609Z","avatar_url":"https://github.com/circlefin.png","language":"JavaScript","funding_links":[],"categories":["TypeScript","Stablecoins"],"sub_categories":[],"readme":"\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- omit in toc --\u003e\n# Circle's Stablecoin Smart Contracts on EVM-compatible blockchains\n\u003c!-- prettier-ignore-end --\u003e\n\nThis repository contains the smart contracts used by\n[Circle's](https://www.circle.com/) stablecoins on EVM-compatible blockchains.\nAll contracts are written in [Solidity](https://soliditylang.org/) and managed\nby the [Hardhat](https://hardhat.org/) framework.\n\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- omit in toc --\u003e\n## Table of contents\n\u003c!-- prettier-ignore-end --\u003e\n\n- [Setup](#setup)\n  - [Development Environment](#development-environment)\n  - [IDE](#ide)\n- [Development](#development)\n  - [TypeScript type definition files for the contracts](#typescript-type-definition-files-for-the-contracts)\n  - [Linting and Formatting](#linting-and-formatting)\n  - [Testing](#testing)\n- [Deployment](#deployment)\n- [Contracts](#contracts)\n- [FiatToken features](#fiattoken-features)\n  - [ERC20 compatible](#erc20-compatible)\n  - [Pausable](#pausable)\n  - [Upgradable](#upgradable)\n  - [Blacklist](#blacklist)\n  - [Minting/Burning](#mintingburning)\n  - [Ownable](#ownable)\n- [Additional Documentations](#additional-documentations)\n\n## Setup\n\n### Development Environment\n\nRequirements:\n\n- Node 20.9.0\n- Yarn 1.22.19\n- [Foundry@f625d0f](https://github.com/foundry-rs/foundry/releases/tag/nightly-f625d0fa7c51e65b4bf1e8f7931cd1c6e2e285e9)\n\n```sh\n$ nvm use\n$ npm i -g yarn@1.22.19 # Install yarn if you don't already have it\n$ yarn install          # Install npm packages and other dependencies listed in setup.sh\n```\n\n### IDE\n\nWe recommend using VSCode for the project here with these\n[extensions](./.vscode/extensions.json) installed.\n\n## Development\n\n### TypeScript type definition files for the contracts\n\nTypes are automatically generated as a part of contract compilation:\n\n```sh\n$ yarn compile\n```\n\nTo generate typing without re-compiling, run\n\n```sh\n$ yarn hardhat typechain\n```\n\n### Linting and Formatting\n\nTo check code for problems:\n\n```sh\n$ yarn static-check   # Runs a static check on the repo.\n```\n\nor run the checks individually:\n\n```sh\n$ yarn typecheck      # Type-check TypeScript code\n$ yarn lint           # Check JavaScript and TypeScript code\n$ yarn lint --fix     # Fix problems where possible\n$ yarn solhint        # Check Solidity code\n```\n\nTo auto-format code:\n\n```sh\n$ yarn fmt\n```\n\n### Testing\n\nRun all tests:\n\n```sh\n$ yarn test\n```\n\nTo run tests in a specific file, run:\n\n```sh\n$ yarn test [path/to/file]\n```\n\nTo run tests and generate test coverage, run:\n\n```sh\n$ yarn coverage\n```\n\nTo check the size of contracts in the repo, run the following command.\n\n```sh\n$ yarn contract-size # Ignores tests\n```\n\n## Deployment\n\n1. Create a copy of the file `.env.example`, and name it `.env`. Fill in\n   appropriate values in the `.env` file. This file must not be checked into the\n   repository.\n\n```sh\ncp .env.example .env\n```\n\n2. Create a `blacklist.remote.json` file and populate it with a list of\n   addresses to be blacklisted. This file must not be checked into the\n   repository.\n\n```sh\necho \"[]\" \u003e blacklist.remote.json\n```\n\n3. Simulate a deployment by running the following command\n\n```sh\nyarn forge:simulate scripts/deploy/deploy-fiat-token.s.sol --rpc-url \u003ctestnet OR mainnet\u003e\n```\n\n4. Validate that all transactions to be broadcasted are filled in with the\n   correct values\n5. Deploy the contracts by running the following command\n\n```sh\nyarn forge:broadcast scripts/deploy/deploy-fiat-token.s.sol --rpc-url \u003ctestnet OR mainnet\u003e\n```\n\n6. Verify the contracts on an Etherscan flavored block explorer by running the\n   following command. Ensure that `ETHERSCAN_KEY` is set in the `.env` file.\n\n```sh\nyarn forge:verify scripts/deploy/deploy-fiat-token.s.sol --rpc-url \u003ctestnet OR mainnet\u003e\n```\n\n## Contracts\n\nThe FiatToken contracts adheres to OpenZeppelin's\n[Proxy Upgrade Pattern](https://docs.openzeppelin.com/upgrades-plugins/1.x/proxies)\n([permalink](https://github.com/OpenZeppelin/openzeppelin-upgrades/blob/65cf285bd36af24570186ca6409341540c67238a/docs/modules/ROOT/pages/proxies.adoc#L1)).\nThere are 2 main contracts - an implementation contract\n([`FiatTokenV2_2.sol`](./contracts/v2/FiatTokenV2_2.sol)) that contains the main\nlogic for FiatToken's functionalities, and a proxy contract\n([`FiatTokenProxy.sol`](./contracts/v1/FiatTokenProxy.sol)) that redirects\nfunction calls to the implementation contract. This allows upgrading FiatToken's\nfunctionalities, as a new implementation contact can be deployed and the Proxy\ncan be updated to point to it.\n\n## FiatToken features\n\nThe FiatToken offers a number of capabilities, which briefly are described\nbelow. There are more [detailed design docs](./doc/tokendesign.md) in the `doc`\ndirectory.\n\n### ERC20 compatible\n\nThe FiatToken implements the ERC20 interface.\n\n### Pausable\n\nThe entire contract can be frozen, in case a serious bug is found or there is a\nserious key compromise. No transfers can take place while the contract is\npaused. Access to the pause functionality is controlled by the `pauser` address.\n\n### Upgradable\n\nA new implementation contract can be deployed, and the proxy contract will\nforward calls to the new contract. Access to the upgrade functionality is\nguarded by a `proxyOwner` address. Only the `proxyOwner` address can change the\n`proxyOwner` address.\n\n### Blacklist\n\nThe contract can blacklist certain addresses which will prevent those addresses\nfrom transferring or receiving tokens. Access to the blacklist functionality is\ncontrolled by the `blacklister` address.\n\n### Minting/Burning\n\nTokens can be minted or burned on demand. The contract supports having multiple\nminters simultaneously. There is a `masterMinter` address which controls the\nlist of minters and how much each is allowed to mint. The mint allowance is\nsimilar to the ERC20 allowance - as each minter mints new tokens their allowance\ndecreases. When it gets too low they will need the allowance increased again by\nthe `masterMinter`.\n\n### Ownable\n\nThe contract has an Owner, who can change the `owner`, `pauser`, `blacklister`,\nor `masterMinter` addresses. The `owner` can not change the `proxyOwner`\naddress.\n\n## Additional Documentations\n\n- [FiatToken design](./doc/tokendesign.md)\n- [MasterMinter design](./doc/masterminter.md)\n- [Bridged USDC Standard](./doc/bridged_USDC_standard.md)\n- [Deployment process](./doc/deployment.md)\n- [Preparing an upgrade](./doc/upgrade.md)\n- [Upgrading from v2.1 to v2.2](./doc/v2.2_upgrade.md)\n- [Celo FiatToken extension](./doc/celo.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirclefin%2Fstablecoin-evm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcirclefin%2Fstablecoin-evm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirclefin%2Fstablecoin-evm/lists"}