How circlefin/stablecoin-evm works
This repository supplies Circle stablecoin contracts for EVM chains. The main user workflow is a token call routed through an upgradeable proxy to FiatToken implementation logic, where ERC20 operations and administrative controls are applied. Separate branches cover mint authorization, signed gas-abstraction transfers, native/Celo variants, and preparing upgrades. Operational tooling supports deployment, blacklist maintenance, contract reads, and deployed-bytecode verification. Contract internals and deployment scripts were not sampled; those capabilities and relationships are shown only where the README or indexed references support them.
Main entry points: FiatTokenProxy.sol FiatToken proxy · validateAccountsToBlacklist.ts Validate blacklist · downloadBlacklistedAccounts.ts Download blacklist · verifyOnChainBytecode.ts Bytecode verifier
Components 23
Token contracts
- FiatToken proxy
contracts/v1/FiatTokenProxy.sol - FiatToken V2.2
contracts/v2/FiatTokenV2_2.sol - Token controls
contracts/v2/AbstractFiatTokenV2.sol - Minter management
contracts/minting/MasterMinter.sol - Mint controller
contracts/minting/MintController.sol
Token extensions
- Signed transfers
contracts/v2/EIP3009.sol - Permit
contracts/v2/EIP2612.sol - Native token
contracts/v2/NativeFiatTokenV2_2.sol - Celo token
contracts/v2/celo/FiatTokenCeloV2_2.sol - Celo fee adapter
contracts/v2/celo/FiatTokenFeeAdapterV1.sol
Operations tooling
- Download blacklist
scripts/hardhat/downloadBlacklistedAccounts.ts - Validate blacklist
scripts/hardhat/validateAccountsToBlacklist.ts - Blacklist input
utils.js - Read contract values
scripts/hardhat/readValuesFromContract.ts - Find creation block
scripts/hardhat/getContractCreationBlock.ts - Bytecode verifier
scripts/hardhat/verifyOnChainBytecode.ts - Mainnet verification
scripts/verifyMainnetTokenBytecode.ts - Alternate artifacts
scripts/hardhat/alternativeArtifacts.ts
Deployment and upgrades
- Contract deployment
scripts/deploy/deploy-fiat-token.s.sol - V2 upgrader
contracts/v2/upgrader/V2_2Upgrader.sol - Upgrade helpers
contracts/v2/upgrader/helpers/V2_2UpgraderHelper.sol
Other components
- Token caller
- Operations engineer
Connections 20
- Token caller → FiatToken proxy: calls
README.md - FiatToken proxy → FiatToken V2.2: forwards calls
README.md - Minter management → Mint controller: manages minters
- Operations engineer → Download blacklist: runs task
scripts/hardhat/downloadBlacklistedAccounts.ts - Download blacklist → FiatToken proxy: queries events
scripts/hardhat/downloadBlacklistedAccounts.ts - Download blacklist → Blacklist input: writes addresses
scripts/hardhat/downloadBlacklistedAccounts.ts - Operations engineer → Validate blacklist: runs task
scripts/hardhat/validateAccountsToBlacklist.ts - Validate blacklist → Blacklist input: reads addresses
scripts/hardhat/validateAccountsToBlacklist.ts - Validate blacklist → FiatToken proxy: checks blacklist
scripts/hardhat/validateAccountsToBlacklist.ts - Validate blacklist → V2 upgrader: reads blacklist list
scripts/hardhat/validateAccountsToBlacklist.ts - Operations engineer → Read contract values: runs task
scripts/hardhat/readValuesFromContract.ts - Operations engineer → Find creation block: runs task
scripts/hardhat/getContractCreationBlock.ts - Operations engineer → Bytecode verifier: runs task
- Bytecode verifier → Alternate artifacts: loads artifacts
scripts/hardhat/verifyOnChainBytecode.ts - Operations engineer → Mainnet verification: runs verifier
scripts/verifyMainnetTokenBytecode.ts - Mainnet verification → Bytecode verifier: calls verifier
scripts/verifyMainnetTokenBytecode.ts - Operations engineer → Contract deployment: runs deployment
README.md - Contract deployment → FiatToken proxy: deploys token proxy
- V2 upgrader → Upgrade helpers: uses helpers
- FiatToken proxy → V2 upgrader: accepts implementation upgrade