stablecoin-toolkit

Open-source stablecoin infrastructure — issuance, reserve management, compliance, multi-geography support.

Quick Start

git clone https://github.com/kcolbchain/stablecoin-toolkit.git
cd stablecoin-toolkit
npm install

npx hardhat compile
npx hardhat test

# Deploy locally
npx hardhat node &
npx hardhat run scripts/deploy.js --network localhost

Architecture

┌─────────────────────────────────────┐
│           Minting Gateway           │
│   (mint, redeem, fee management)    │
├──────────┬──────────────────────────┤
│Compliance│    Reserve Manager       │
│ Module   │ (multi-asset, proof of   │
│(KYC, geo │  reserves, ratio         │
│ restrict)│  enforcement)            │
├──────────┴──────────────────────────┤
│        Stablecoin (ERC-20)          │
│  (mint/burn, pause, blacklist,      │
│   EIP-2612 permit)                  │
└─────────────────────────────────────┘

Stablecoin.sol

Core ERC-20 stablecoin with 6 decimals (USDC-style). Built on OpenZeppelin v5.

ReserveManager.sol

Multi-asset reserve tracking with on-chain proof of reserves.

• Add multiple reserve assets (bank deposits, government securities, etc.)
• Enforce minimum reserve ratio (e.g. 105% for overcollateralisation)
• On-chain attestation with timestamps
• Automatic total recalculation on updates

ComplianceModule.sol

Per-address compliance enforcement:

• KYC status — None, Pending, Approved, Rejected
• Geography restrictions — per-geography allow/deny with ISO 3166-1 codes
• Transaction limits — max per-tx and daily limits per geography
• Sanctions list — block specific addresses

// Configure India geography
compliance.configureGeography(
    "IN",           // ISO code
    true,           // allowed
    10000000000,    // max tx: 10,000 INDR
    50000000000     // daily limit: 50,000 INDR
);

Minter.sol

Gateway contract that checks compliance + reserve ratio before every mint. Handles redemption queuing and fee management.

Flow: mint() → compliance check → reserve ratio check → mint tokens → record daily spend → collect fees

Adding a New Geography

1. Copy config/geographies/template.json
2. Set ISO code, name, symbol, compliance requirements, limits, and fee structure
3. Deploy contracts with geography-specific parameters
4. Configure compliance module with geography rules

See config/geographies/india.json for the INDR reference implementation.

Deployment

The deploy script (scripts/deploy.js) deploys all 4 contracts and links them:

1. Deploy Stablecoin
2. Deploy ReserveManager (with minimum ratio)
3. Deploy ComplianceModule
4. Deploy Minter (references all three)
5. Grant MINTER_ROLE to Minter contract
6. Transfer ownership of ReserveManager and ComplianceModule to Minter

Fee Configuration

Mint and redeem fees are set in basis points (1 bps = 0.01%). Default: 10 bps (0.1%) each direction. Fees go to a configurable fee collector address.