Skip to content

README.md

Latest commit

 

History

History
72 lines (57 loc) · 3.14 KB

README.md

File metadata and controls

72 lines (57 loc) · 3.14 KB
Raw

Stablecoin -- EVM

Solidity implementation of the Stablecoin system using a beacon proxy pattern with OpenZeppelin contracts.

Features

  • Beacon Proxy Upgradeability -- All stablecoin proxies share a single Stablecoin implementation via a TwoStepUpgradeableBeacon; upgrades apply atomically across every deployed instance
  • ERC-7201 Namespaced Storage -- Collision-resistant storage layout across all mixin contracts
  • Mint Rate Limiting -- Each minter has an independent capacity that replenishes over a configurable rolling interval
  • Blocklist -- Addresses can be blocked from sending, receiving, or approving token transfers
  • Role-Based Access Control -- Granular roles with separated concerns:
    • DEFAULT_ADMIN_ROLE -- Role and upgrade management (single holder, two-step transfer with configurable delay)
    • MINT_ROLE -- Mint tokens up to the configured rate limit
    • MINT_RATE_LIMIT_ROLE -- Update rate-limit configurations for existing minters
    • BURN_ROLE -- Burn the caller's own tokens
    • BLOCKLIST_ROLE / UNBLOCKLIST_ROLE -- Add or remove addresses from the blocklist
    • PAUSE_ROLE / UNPAUSE_ROLE -- Pause and unpause all token transfers
    • METADATA_ROLE -- Update the contract-level metadata URI (ERC-7572)

Prerequisites

Build

forge build

Test

forge test -vvv

Format

forge fmt --check

Project Structure

evm/
├── src/
│   ├── Stablecoin.sol                  # ERC-20 stablecoin implementation
│   ├── StablecoinFactory.sol           # UUPS-upgradeable factory (CREATE2 deploys)
│   ├── TwoStepUpgradeableBeacon.sol    # Beacon with two-step ownership transfer
│   ├── MutableBeaconProxy.sol          # Proxy that can swap its beacon
│   ├── interfaces/                     # Solidity interfaces
│   └── lib/
│       ├── Blocklist.sol               # Blocklist mixin
│       ├── RateLimit.sol               # Rolling rate-limit mixin
│       ├── TokenMetadata.sol           # Custom decimals + ERC-7572 contractURI mixin
│       └── ERC3009Upgradeable.sol      # ERC-3009 transfer-with-authorization mixin
├── test/
│   ├── unit/                           # Per-function unit tests
│   ├── integration/                    # End-to-end workflow tests
│   ├── attack/                         # Adversarial scenario tests
│   ├── benchmark/                      # Gas benchmark tests
│   └── lib/                            # Test base contracts and mocks
└── foundry.toml                        # Foundry configuration

Dependencies

Dependency Purpose
OpenZeppelin Contracts Upgradeable Access control, ERC-20 extensions, proxy utilities
OpenZeppelin Contracts ERC-1967 utils, CREATE2, UUPS
forge-std Foundry testing and scripting standard library