This repository contains the smart contracts used by Circle's stablecoins on EVM-compatible blockchains. All contracts are written in Solidity and managed by the Hardhat framework.
Requirements:
- Node 16.14.0
- Yarn 1.22.19
- Foundry@f625d0f
$ git clone git@github.com:circlefin/stablecoin-evm.git
$ cd stablecoin-evm
$ nvm use
$ npm i -g yarn@1.22.19 # Install yarn if you don't already have it
$ yarn install # Install npm packages and other dependencies listed in setup.sh
We recommend using VSCode for the project here with these extensions installed.
Types are automatically generated as a part of contract compilation:
$ yarn compile
To generate typing without re-compiling, run
$ yarn hardhat typechain
To check code for problems:
$ yarn static-check # Runs a static check on the repo.
or run the checks individually:
$ yarn typecheck # Type-check TypeScript code
$ yarn lint # Check JavaScript and TypeScript code
$ yarn lint --fix # Fix problems where possible
$ yarn solhint # Check Solidity code
To auto-format code:
$ yarn fmt
Run all tests:
$ yarn test
To run tests in a specific file, run:
$ yarn test [path/to/file]
To run tests and generate test coverage, run:
$ yarn coverage
To check the size of contracts in the repo, run the following command.
$ yarn contract-size # Ignores tests
- Create a copy of the file
.env.example
, and name it.env
. Fill in appropriate values in the.env
file. This file must not be checked into the repository.
cp .env.example .env
- Create a
blacklist.remote.json
file and populate it with a list of addresses to be blacklisted. This file must not be checked into the repository.
echo "[]" > blacklist.remote.json
- Simulate a deployment by running the following command
yarn forge:simulate scripts/deploy/deploy-fiat-token.s.sol --rpc-url <testnet OR mainnet>
- Validate that all transactions to be broadcasted are filled in with the correct values
- Deploy the contracts by running the following command
yarn forge:broadcast scripts/deploy/deploy-fiat-token.s.sol --rpc-url <testnet OR mainnet>
- Verify the contracts on an Etherscan flavored block explorer by running the
following command. Ensure that
ETHERSCAN_KEY
is set in the.env
file.
yarn forge:verify scripts/deploy/deploy-fiat-token.s.sol --rpc-url <testnet OR mainnet>
The FiatToken contracts adheres to OpenZeppelin's
Proxy Upgrade Pattern
(permalink).
There are 2 main contracts - an implementation contract
(FiatTokenV2_2.sol
) that contains the main
logic for FiatToken's functionalities, and a proxy contract
(FiatTokenProxy.sol
) that redirects
function calls to the implementation contract. This allows upgrading FiatToken's
functionalities, as a new implementation contact can be deployed and the Proxy
can be updated to point to it.
The FiatToken offers a number of capabilities, which briefly are described
below. There are more detailed design docs in the doc
directory.
The FiatToken implements the ERC20 interface.
The entire contract can be frozen, in case a serious bug is found or there is a
serious key compromise. No transfers can take place while the contract is
paused. Access to the pause functionality is controlled by the pauser
address.
A new implementation contract can be deployed, and the proxy contract will
forward calls to the new contract. Access to the upgrade functionality is
guarded by a proxyOwner
address. Only the proxyOwner
address can change the
proxyOwner
address.
The contract can blacklist certain addresses which will prevent those addresses
from transferring or receiving tokens. Access to the blacklist functionality is
controlled by the blacklister
address.
Tokens can be minted or burned on demand. The contract supports having multiple
minters simultaneously. There is a masterMinter
address which controls the
list of minters and how much each is allowed to mint. The mint allowance is
similar to the ERC20 allowance - as each minter mints new tokens their allowance
decreases. When it gets too low they will need the allowance increased again by
the masterMinter
.
The contract has an Owner, who can change the owner
, pauser
, blacklister
,
or masterMinter
addresses. The owner
can not change the proxyOwner
address.