Usdc Integration

// 1 USDC = 1_000_000 (1e6)
uint256 constant USDC_UNIT = 1e6;

// $100 USDC
uint256 amount = 100 * 1e6; // 100_000_000

// $0.01 USDC (one cent)
uint256 oneCent = 1e4; // 10_000

// WRONG — this is 1 trillion USDC ($1,000,000,000,000)
uint256 catastrophic = 1e18;

uint256 constant SCALE_FACTOR = 1e12; // 18 - 6 = 12

// Scale 6 → 18 (lossless)
uint256 wad = usdcAmount * SCALE_FACTOR;

// Scale 18 → 6 (LOSES up to 1e12 - 1 wei of precision)
uint256 usdc = wadAmount / SCALE_FACTOR;

// BAD — precision loss compounds
uint256 result = (usdcAmount * price) / 1e18;

// BETTER — scale USDC to 18 decimals first, then divide
uint256 result = (usdcAmount * SCALE_FACTOR * price) / 1e18;

// BEST — use a helper that makes intent explicit
uint256 result = _toWad(usdcAmount) * price / 1e18;

# Confirm USDC contract exists and is a proxy
cast code 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --rpc-url mainnet | head -c 40

# Check decimals
cast call 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 "decimals()(uint8)" --rpc-url mainnet
# → 6

# Check symbol
cast call 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 "symbol()(string)" --rpc-url mainnet
# → "USDC"

/// @notice Validates that a USDC address is the native Circle-issued token
/// @dev Checks for EIP-2612 permit support as a heuristic — bridged variants lack it
function _validateNativeUSDC(address token) internal view {
    // Native USDC supports EIP-2612 permit via DOMAIN_SEPARATOR
    (bool success,) = token.staticcall(abi.encodeWithSignature("DOMAIN_SEPARATOR()"));
    if (!success) revert NotNativeUSDC(token);
}

FiatTokenProxy (storage + delegatecall)
  └── FiatTokenV2_2 (implementation logic)
        ├── ERC-20 (transfer, approve, transferFrom, balanceOf, allowance)
        ├── EIP-2612 (permit — gasless approvals via signature)
        ├── EIP-3009 (transferWithAuthorization, receiveWithAuthorization)
        ├── Blocklist (Circle can block specific addresses)
        ├── Pause (Circle can halt all transfers globally)
        └── Upgrade (Circle can swap the implementation)

// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";

/// @title USDCVault
/// @notice Minimal vault demonstrating safe USDC integration
contract USDCVault is ReentrancyGuard {
    using SafeERC20 for IERC20;

    IERC20 public immutable USDC;

    mapping(address user => uint256 balance) public balances;

    error ZeroAmount();
    error InsufficientBalance(uint256 available, uint256 requested);

    event Deposited(address indexed user, uint256 amount);
    event Withdrawn(address indexed user, address indexed recipient, uint256 amount);

    constructor(address usdc_) {
        USDC = IERC20(usdc_);
    }

    /// @notice Deposit USDC into the vault
    /// @param amount Amount of USDC in 6-decimal units
    function deposit(uint256 amount) external nonReentrant {
        if (amount == 0) revert ZeroAmount();

        balances[msg.sender] += amount;
        emit Deposited(msg.sender, amount);

        USDC.safeTransferFrom(msg.sender, address(this), amount);
    }

    /// @notice Withdraw USDC to a specified recipient
    /// @dev Allows withdrawal to a different address in case msg.sender is blocklisted
    /// @param recipient Address to receive USDC
    /// @param amount Amount of USDC in 6-decimal units
    function withdraw(address recipient, uint256 amount) external nonReentrant {
        if (amount == 0) revert ZeroAmount();
        uint256 bal = balances[msg.sender];
        if (bal < amount) revert InsufficientBalance(bal, amount);

        balances[msg.sender] = bal - amount;
        emit Withdrawn(msg.sender, recipient, amount);

        USDC.safeTransfer(recipient, amount);
    }
}

import {IERC20Permit} from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Permit.sol";

/// @notice Deposit with a signed permit, enabling single-tx approve + deposit
/// @param amount USDC amount (6 decimals)
/// @param deadline Timestamp after which the permit signature expires
/// @param v Recovery byte of the permit signature
/// @param r First 32 bytes of the permit signature
/// @param s Second 32 bytes of the permit signature
function depositWithPermit(
    uint256 amount,
    uint256 deadline,
    uint8 v,
    bytes32 r,
    bytes32 s
) external nonReentrant {
    if (amount == 0) revert ZeroAmount();

    // permit may revert if signature is invalid or already used
    try IERC20Permit(address(USDC)).permit(
        msg.sender, address(this), amount, deadline, v, r, s
    ) {} catch {
        // Permit may fail if:
        // 1. Approval already exists (front-run or user pre-approved)
        // 2. Signature was already used
        // Proceed with transferFrom — it will fail if allowance is insufficient
    }

    balances[msg.sender] += amount;
    emit Deposited(msg.sender, amount);

    USDC.safeTransferFrom(msg.sender, address(this), amount);
}

interface IFiatTokenV2 {
    function transferWithAuthorization(
        address from,
        address to,
        uint256 value,
        uint256 validAfter,
        uint256 validBefore,
        bytes32 nonce,
        uint8 v,
        bytes32 r,
        bytes32 s
    ) external;

    function receiveWithAuthorization(
        address from,
        address to,
        uint256 value,
        uint256 validAfter,
        uint256 validBefore,
        bytes32 nonce,
        uint8 v,
        bytes32 r,
        bytes32 s
    ) external;
}

/// @notice Withdraw to an alternative recipient if the depositor is blocklisted
/// @dev Access-controlled so only the original depositor can redirect
function withdraw(address recipient, uint256 amount) external nonReentrant {
    if (amount == 0) revert ZeroAmount();
    uint256 bal = balances[msg.sender];
    if (bal < amount) revert InsufficientBalance(bal, amount);

    balances[msg.sender] = bal - amount;
    emit Withdrawn(msg.sender, recipient, amount);

    USDC.safeTransfer(recipient, amount);
}

/// @notice Liquidate a position, sending seized USDC to the liquidator
/// @dev If the direct transfer fails (blocklist), escrow the funds
function liquidate(address borrower, uint256 repayAmount) external nonReentrant {
    // ... checks and effects ...

    uint256 seizedCollateral = _calculateSeizedCollateral(repayAmount);
    balances[borrower] -= seizedCollateral;

    // Attempt direct transfer; fall back to escrow on failure
    try IERC20(address(USDC)).transfer(msg.sender, seizedCollateral) {
        emit Liquidated(borrower, msg.sender, seizedCollateral);
    } catch {
        pendingWithdrawals[msg.sender] += seizedCollateral;
        emit LiquidatedToEscrow(borrower, msg.sender, seizedCollateral);
    }
}

/// @notice Claim escrowed funds from a failed liquidation transfer
function claimEscrow(address recipient) external nonReentrant {
    uint256 amount = pendingWithdrawals[msg.sender];
    if (amount == 0) revert NothingToClaim();
    pendingWithdrawals[msg.sender] = 0;
    USDC.safeTransfer(recipient, amount);
}

/// @notice Check if USDC is currently paused
/// @dev Useful for UIs or circuits that need to know transfer availability
function isUSDCPaused() public view returns (bool) {
    (bool success, bytes memory data) = address(USDC).staticcall(
        abi.encodeWithSignature("paused()")
    );
    return success && abi.decode(data, (bool));
}

// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

/// @title USDCLib
/// @notice Helpers for USDC decimal conversions
library USDCLib {
    uint256 internal constant USDC_DECIMALS = 6;
    uint256 internal constant USDC_UNIT = 1e6;
    uint256 internal constant WAD = 1e18;
    uint256 internal constant SCALE_FACTOR = 1e12;

    /// @notice Convert USDC amount (6 decimals) to WAD (18 decimals)
    /// @dev Lossless — always safe
    function toWad(uint256 usdcAmount) internal pure returns (uint256) {
        return usdcAmount * SCALE_FACTOR;
    }

    /// @notice Convert WAD (18 decimals) to USDC amount (6 decimals)
    /// @dev Truncates — loses up to 999_999_999_999 wei (< $0.000001)
    function fromWad(uint256 wadAmount) internal pure returns (uint256) {
        return wadAmount / SCALE_FACTOR;
    }

    /// @notice Convert WAD to USDC, rounding up
    /// @dev Use when the protocol should not lose value (e.g., debt calculations)
    function fromWadRoundUp(uint256 wadAmount) internal pure returns (uint256) {
        return (wadAmount + SCALE_FACTOR - 1) / SCALE_FACTOR;
    }

    /// @notice Construct a USDC amount from whole dollars
    function dollars(uint256 amount) internal pure returns (uint256) {
        return amount * USDC_UNIT;
    }

    /// @notice Construct a USDC amount from dollars and cents
    function dollarsAndCents(uint256 wholeDollars, uint256 cents) internal pure returns (uint256) {
        return wholeDollars * USDC_UNIT + cents * 1e4;
    }
}

// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

import {Test} from "forge-std/Test.sol";
import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";

contract USDCForkTest is Test {
    IERC20 constant USDC = IERC20(0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48);

    address alice = makeAddr("alice");
    address bob = makeAddr("bob");

    function setUp() public {
        vm.createSelectFork("mainnet");

        // deal() works for setting USDC balances on forks
        deal(address(USDC), alice, 1_000_000 * 1e6); // $1M
        deal(address(USDC), bob, 500_000 * 1e6);      // $500K
    }

    function test_usdcDecimals() public view {
        assertEq(USDC.decimals(), 6);
    }

    function test_transfer() public {
        vm.prank(alice);
        USDC.transfer(bob, 100 * 1e6); // $100

        assertEq(USDC.balanceOf(bob), 600_000 * 1e6);
    }
}

function test_blocklistedAddressCannotReceive() public {
    address blocklister = 0x5dB0115f3B72d19cEa34dD697cf412Ff86dc7E1b;
    address victim = makeAddr("victim");

    deal(address(USDC), alice, 100 * 1e6);

    // Blocklist the victim address
    vm.prank(blocklister);
    (bool success,) = address(USDC).call(
        abi.encodeWithSignature("blacklist(address)", victim)
    );
    assertTrue(success);

    // Transfer to blocklisted address reverts
    vm.prank(alice);
    vm.expectRevert();
    USDC.transfer(victim, 50 * 1e6);
}

function test_permitAndDeposit() public {
    uint256 alicePk = 0xA11CE;
    address aliceAddr = vm.addr(alicePk);
    deal(address(USDC), aliceAddr, 1000 * 1e6);

    uint256 amount = 500 * 1e6;
    uint256 deadline = block.timestamp + 1 hours;

    // Build permit digest
    bytes32 domainSeparator = IERC20Permit(address(USDC)).DOMAIN_SEPARATOR();
    bytes32 structHash = keccak256(abi.encode(
        keccak256("Permit(address owner,address spender,uint256 value,uint256 nonce,uint256 deadline)"),
        aliceAddr,
        address(vault),
        amount,
        IERC20Permit(address(USDC)).nonces(aliceAddr),
        deadline
    ));
    bytes32 digest = keccak256(abi.encodePacked("\x19\x01", domainSeparator, structHash));

    (uint8 v, bytes32 r, bytes32 s) = vm.sign(alicePk, digest);

    vm.prank(aliceAddr);
    vault.depositWithPermit(amount, deadline, v, r, s);

    assertEq(vault.balances(aliceAddr), amount);
}

function test_usdcOnMultipleChains() public {
    // Ethereum
    uint256 ethFork = vm.createFork("mainnet");
    vm.selectFork(ethFork);
    assertEq(
        IERC20(0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48).decimals(),
        6
    );

    // Base
    uint256 baseFork = vm.createFork("base");
    vm.selectFork(baseFork);
    assertEq(
        IERC20(0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913).decimals(),
        6
    );

    // Arbitrum
    uint256 arbFork = vm.createFork("arbitrum");
    vm.selectFork(arbFork);
    assertEq(
        IERC20(0xaf88d065e77c8cC2239327C5EDb3A432268e5831).decimals(),
        6
    );
}

// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {IERC20Metadata} from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";

/// @title USDCRegistry
/// @notice Deploy-time registry that validates the USDC address for the target chain
contract USDCRegistry {
    error InvalidUSDCDecimals(uint8 actual);
    error InvalidUSDCSymbol(string actual);
    error ChainMismatch(uint256 expected, uint256 actual);

    IERC20 public immutable USDC;
    uint256 public immutable EXPECTED_CHAIN_ID;

    constructor(address usdc_, uint256 expectedChainId_) {
        if (block.chainid != expectedChainId_) {
            revert ChainMismatch(expectedChainId_, block.chainid);
        }

        uint8 decimals = IERC20Metadata(usdc_).decimals();
        if (decimals != 6) revert InvalidUSDCDecimals(decimals);

        string memory symbol = IERC20Metadata(usdc_).symbol();
        if (keccak256(bytes(symbol)) != keccak256("USDC")) {
            revert InvalidUSDCSymbol(symbol);
        }

        USDC = IERC20(usdc_);
        EXPECTED_CHAIN_ID = expectedChainId_;
    }
}

// script/Deploy.s.sol
// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

import {Script} from "forge-std/Script.sol";
import {USDCVault} from "../src/USDCVault.sol";

contract DeployScript is Script {
    function _getUSDCAddress() internal view returns (address) {
        if (block.chainid == 1) return 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48;
        if (block.chainid == 8453) return 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913;
        if (block.chainid == 42161) return 0xaf88d065e77c8cC2239327C5EDb3A432268e5831;
        if (block.chainid == 10) return 0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85;
        if (block.chainid == 137) return 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359;
        if (block.chainid == 43114) return 0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E;
        // Testnets
        if (block.chainid == 11155111) return 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238;
        if (block.chainid == 84532) return 0x036CbD53842c5426634e7929541eC2318f3dCF7e;
        if (block.chainid == 421614) return 0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d;
        revert("Unsupported chain");
    }

    function run() external {
        vm.startBroadcast();
        new USDCVault(_getUSDCAddress());
        vm.stopBroadcast();
    }
}