# circlefin/stablecoin-evm architecture

> Architecture diagram of the GitHub repository circlefin/stablecoin-evm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/circlefin/stablecoin-evm
- Repository: https://github.com/circlefin/stablecoin-evm

## Overview

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: [`contracts/v1/FiatTokenProxy.sol`](https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v1/FiatTokenProxy.sol) (FiatToken proxy), [`scripts/hardhat/validateAccountsToBlacklist.ts`](https://github.com/circlefin/stablecoin-evm/blob/master/scripts/hardhat/validateAccountsToBlacklist.ts) (Validate blacklist), [`scripts/hardhat/downloadBlacklistedAccounts.ts`](https://github.com/circlefin/stablecoin-evm/blob/master/scripts/hardhat/downloadBlacklistedAccounts.ts) (Download blacklist), [`scripts/hardhat/verifyOnChainBytecode.ts`](https://github.com/circlefin/stablecoin-evm/blob/master/scripts/hardhat/verifyOnChainBytecode.ts) (Bytecode verifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_token["Token contracts"]
  node_proxy["FiatToken proxy<br/>[FiatTokenProxy.sol]"]
  node_implementation["FiatToken V2.2<br/>[FiatTokenV2_2.sol]"]
  node_controls["Token controls"]
  node_minting["Minter management<br/>[MasterMinter.sol]"]
  node_mintcontroller["Mint controller<br/>[MintController.sol]"]
end

subgraph group_extensions["Token extensions"]
  node_signatures["Signed transfers<br/>[EIP3009.sol]"]
  node_permit["Permit<br/>[EIP2612.sol]"]
  node_native["Native token"]
  node_celo["Celo token"]
  node_feeadapter["Celo fee adapter"]
end

subgraph group_operations["Operations tooling"]
  node_blacklistdownload["Download blacklist"]
  node_blacklistvalidate["Validate blacklist"]
  node_blacklistfile["Blacklist input<br/>[utils.js]"]
  node_contractreads["Read contract values"]
  node_creationblock["Find creation block"]
  node_verification["Bytecode verifier"]
  node_mainnetverify["Mainnet verification"]
  node_artifacts["Alternate artifacts"]
end

subgraph group_upgrades["Deployment and upgrades"]
  node_deploy["Contract deployment"]
  node_upgrader["V2 upgrader<br/>[V2_2Upgrader.sol]"]
  node_upgradehelpers["Upgrade helpers"]
end

node_operator(("Token caller"))
node_user(("Operations engineer"))

node_operator -->|"calls"| node_proxy
node_proxy -->|"forwards calls"| node_implementation
node_minting -.->|"manages minters"| node_mintcontroller
node_user -->|"runs task"| node_blacklistdownload
node_blacklistdownload -->|"queries events"| node_proxy
node_blacklistdownload -->|"writes addresses"| node_blacklistfile
node_user -->|"runs task"| node_blacklistvalidate
node_blacklistvalidate -->|"reads addresses"| node_blacklistfile
node_blacklistvalidate -->|"checks blacklist"| node_proxy
node_blacklistvalidate -->|"reads blacklist list"| node_upgrader
node_user -->|"runs task"| node_contractreads
node_user -->|"runs task"| node_creationblock
node_user -->|"runs task"| node_verification
node_verification -->|"loads artifacts"| node_artifacts
node_user -->|"runs verifier"| node_mainnetverify
node_mainnetverify -->|"calls verifier"| node_verification
node_user -->|"runs deployment"| node_deploy
node_deploy -.->|"deploys token proxy"| node_proxy
node_upgrader -.->|"uses helpers"| node_upgradehelpers
node_proxy -.->|"accepts implementation upgrade"| node_upgrader

click node_proxy "https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v1/FiatTokenProxy.sol"
click node_implementation "https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v2/FiatTokenV2_2.sol"
click node_controls "https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v2/AbstractFiatTokenV2.sol"
click node_minting "https://github.com/circlefin/stablecoin-evm/blob/master/contracts/minting/MasterMinter.sol"
click node_mintcontroller "https://github.com/circlefin/stablecoin-evm/blob/master/contracts/minting/MintController.sol"
click node_signatures "https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v2/EIP3009.sol"
click node_permit "https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v2/EIP2612.sol"
click node_native "https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v2/NativeFiatTokenV2_2.sol"
click node_celo "https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v2/celo/FiatTokenCeloV2_2.sol"
click node_feeadapter "https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v2/celo/FiatTokenFeeAdapterV1.sol"
click node_blacklistdownload "https://github.com/circlefin/stablecoin-evm/blob/master/scripts/hardhat/downloadBlacklistedAccounts.ts"
click node_blacklistvalidate "https://github.com/circlefin/stablecoin-evm/blob/master/scripts/hardhat/validateAccountsToBlacklist.ts"
click node_blacklistfile "https://github.com/circlefin/stablecoin-evm/blob/master/utils.js"
click node_contractreads "https://github.com/circlefin/stablecoin-evm/blob/master/scripts/hardhat/readValuesFromContract.ts"
click node_creationblock "https://github.com/circlefin/stablecoin-evm/blob/master/scripts/hardhat/getContractCreationBlock.ts"
click node_verification "https://github.com/circlefin/stablecoin-evm/blob/master/scripts/hardhat/verifyOnChainBytecode.ts"
click node_mainnetverify "https://github.com/circlefin/stablecoin-evm/blob/master/scripts/verifyMainnetTokenBytecode.ts"
click node_artifacts "https://github.com/circlefin/stablecoin-evm/blob/master/scripts/hardhat/alternativeArtifacts.ts"
click node_deploy "https://github.com/circlefin/stablecoin-evm/blob/master/scripts/deploy/deploy-fiat-token.s.sol"
click node_upgrader "https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v2/upgrader/V2_2Upgrader.sol"
click node_upgradehelpers "https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v2/upgrader/helpers/V2_2UpgraderHelper.sol"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_proxy,node_implementation,node_controls,node_minting,node_mintcontroller toneBlue
class node_signatures,node_permit,node_native,node_celo,node_feeadapter toneAmber
class node_blacklistdownload,node_blacklistvalidate,node_blacklistfile,node_contractreads,node_creationblock,node_verification,node_mainnetverify,node_artifacts toneMint
class node_deploy,node_upgrader,node_upgradehelpers toneRose
class node_operator,node_user toneIndigo
```

## Components

### Token contracts

- [FiatToken proxy](https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v1/FiatTokenProxy.sol): `contracts/v1/FiatTokenProxy.sol`
- [FiatToken V2.2](https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v2/FiatTokenV2_2.sol): `contracts/v2/FiatTokenV2_2.sol`
- [Token controls](https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v2/AbstractFiatTokenV2.sol): `contracts/v2/AbstractFiatTokenV2.sol`
- [Minter management](https://github.com/circlefin/stablecoin-evm/blob/master/contracts/minting/MasterMinter.sol): `contracts/minting/MasterMinter.sol`
- [Mint controller](https://github.com/circlefin/stablecoin-evm/blob/master/contracts/minting/MintController.sol): `contracts/minting/MintController.sol`

### Token extensions

- [Signed transfers](https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v2/EIP3009.sol): `contracts/v2/EIP3009.sol`
- [Permit](https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v2/EIP2612.sol): `contracts/v2/EIP2612.sol`
- [Native token](https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v2/NativeFiatTokenV2_2.sol): `contracts/v2/NativeFiatTokenV2_2.sol`
- [Celo token](https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v2/celo/FiatTokenCeloV2_2.sol): `contracts/v2/celo/FiatTokenCeloV2_2.sol`
- [Celo fee adapter](https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v2/celo/FiatTokenFeeAdapterV1.sol): `contracts/v2/celo/FiatTokenFeeAdapterV1.sol`

### Operations tooling

- [Download blacklist](https://github.com/circlefin/stablecoin-evm/blob/master/scripts/hardhat/downloadBlacklistedAccounts.ts): `scripts/hardhat/downloadBlacklistedAccounts.ts`
- [Validate blacklist](https://github.com/circlefin/stablecoin-evm/blob/master/scripts/hardhat/validateAccountsToBlacklist.ts): `scripts/hardhat/validateAccountsToBlacklist.ts`
- [Blacklist input](https://github.com/circlefin/stablecoin-evm/blob/master/utils.js): `utils.js`
- [Read contract values](https://github.com/circlefin/stablecoin-evm/blob/master/scripts/hardhat/readValuesFromContract.ts): `scripts/hardhat/readValuesFromContract.ts`
- [Find creation block](https://github.com/circlefin/stablecoin-evm/blob/master/scripts/hardhat/getContractCreationBlock.ts): `scripts/hardhat/getContractCreationBlock.ts`
- [Bytecode verifier](https://github.com/circlefin/stablecoin-evm/blob/master/scripts/hardhat/verifyOnChainBytecode.ts): `scripts/hardhat/verifyOnChainBytecode.ts`
- [Mainnet verification](https://github.com/circlefin/stablecoin-evm/blob/master/scripts/verifyMainnetTokenBytecode.ts): `scripts/verifyMainnetTokenBytecode.ts`
- [Alternate artifacts](https://github.com/circlefin/stablecoin-evm/blob/master/scripts/hardhat/alternativeArtifacts.ts): `scripts/hardhat/alternativeArtifacts.ts`

### Deployment and upgrades

- [Contract deployment](https://github.com/circlefin/stablecoin-evm/blob/master/scripts/deploy/deploy-fiat-token.s.sol): `scripts/deploy/deploy-fiat-token.s.sol`
- [V2 upgrader](https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v2/upgrader/V2_2Upgrader.sol): `contracts/v2/upgrader/V2_2Upgrader.sol`
- [Upgrade helpers](https://github.com/circlefin/stablecoin-evm/blob/master/contracts/v2/upgrader/helpers/V2_2UpgraderHelper.sol): `contracts/v2/upgrader/helpers/V2_2UpgraderHelper.sol`

### Other components

- **Token caller**
- **Operations engineer**

## Connections

- Token caller → FiatToken proxy: calls (evidence: `README.md`)
- FiatToken proxy → FiatToken V2.2: forwards calls (evidence: `README.md`)
- Minter management → Mint controller: manages minters
- Operations engineer → Download blacklist: runs task (evidence: `scripts/hardhat/downloadBlacklistedAccounts.ts`)
- Download blacklist → FiatToken proxy: queries events (evidence: `scripts/hardhat/downloadBlacklistedAccounts.ts`)
- Download blacklist → Blacklist input: writes addresses (evidence: `scripts/hardhat/downloadBlacklistedAccounts.ts`)
- Operations engineer → Validate blacklist: runs task (evidence: `scripts/hardhat/validateAccountsToBlacklist.ts`)
- Validate blacklist → Blacklist input: reads addresses (evidence: `scripts/hardhat/validateAccountsToBlacklist.ts`)
- Validate blacklist → FiatToken proxy: checks blacklist (evidence: `scripts/hardhat/validateAccountsToBlacklist.ts`)
- Validate blacklist → V2 upgrader: reads blacklist list (evidence: `scripts/hardhat/validateAccountsToBlacklist.ts`)
- Operations engineer → Read contract values: runs task (evidence: `scripts/hardhat/readValuesFromContract.ts`)
- Operations engineer → Find creation block: runs task (evidence: `scripts/hardhat/getContractCreationBlock.ts`)
- Operations engineer → Bytecode verifier: runs task
- Bytecode verifier → Alternate artifacts: loads artifacts (evidence: `scripts/hardhat/verifyOnChainBytecode.ts`)
- Operations engineer → Mainnet verification: runs verifier (evidence: `scripts/verifyMainnetTokenBytecode.ts`)
- Mainnet verification → Bytecode verifier: calls verifier (evidence: `scripts/verifyMainnetTokenBytecode.ts`)
- Operations engineer → Contract deployment: runs deployment (evidence: `README.md`)
- Contract deployment → FiatToken proxy: deploys token proxy
- V2 upgrader → Upgrade helpers: uses helpers
- FiatToken proxy → V2 upgrader: accepts implementation upgrade