@aqb-foundation/aqb-agent 1.0.1 → 1.0.3

package/client/aqb.mjs

@@ -1,149 +1,233 @@
-// AQB agent SDK — the only client an agent needs.
-// docs/SPEC.md is normative; this file is a thin, boring implementation of it.
-import { Contract, JsonRpcProvider, Wallet, keccak256, toUtf8Bytes, solidityPacked } from "ethers";
-import { newIdentity, signDigest, stealthFor, stealthCheck } from "../pq/pq.mjs";
-export { newIdentity, stealthFor, stealthCheck };
-import crypto from "node:crypto";
-
-export const CHAINS = { base: 8453, "base-sepolia": 84532 };
-export const USDC = {
-  8453: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
-  84532: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
-};
-export const DEFAULT_RPC = {
-  8453: "https://mainnet.base.org",
-  84532: "https://sepolia.base.org",
-};
-
-const ABI_TOKEN = [
-  "function mint(uint256 usd6) returns (uint256)",
-  "function redeem(uint256 aqb18) returns (uint256)",
-  "function balanceOf(address) view returns (uint256)",
-  "function collateralRatio() view returns (uint256)",
-  "function transfer(address,uint256) returns (bool)",
-  "function totalSupply() view returns (uint256)",
-];
-const ABI_REG = [
-  "function register(bytes32 pqKeyHash, bytes32 cardHash)",
-  "function isAgent(address) view returns (bool)",
-  "function updateCard(bytes32 cardHash)",
-  "function announce(address stealth, bytes ephPubKey, bytes1 viewTag, bytes32 meta)",
-  "function agentCount() view returns (uint256)",
-];
+// AQB agent SDK — the only client an agent needs.
+// docs/SPEC.md is normative; this file is a thin, boring implementation of it.
+import { Contract, JsonRpcProvider, Wallet, keccak256, toUtf8Bytes, solidityPacked } from "ethers";
+import { newIdentity, signDigest, stealthFor, stealthCheck } from "../pq/pq.mjs";
+export { newIdentity, stealthFor, stealthCheck };
+
+export const CHAINS = { base: 8453, "base-sepolia": 84532 };
+export const USDC = {
+  8453: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+  84532: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+};
+export const DEFAULT_RPC = {
+  8453: "https://mainnet.base.org",
+  84532: "https://sepolia.base.org",
+};
+
+const ABI_TOKEN = [
+  "function mint(uint256 usd6) returns (uint256)",
+  "function redeem(uint256 aqb18) returns (uint256)",
+  "function balanceOf(address) view returns (uint256)",
+  "function collateralRatio() view returns (uint256)",
+  "function transfer(address,uint256) returns (bool)",
+  "function totalSupply() view returns (uint256)",
+];
+const ABI_REG = [
+  "function register(bytes32 pqKeyHash, bytes32 cardHash)",
+  "function isAgent(address) view returns (bool)",
+  "function updateCard(bytes32 cardHash)",
+  "function announce(address stealth, bytes ephPubKey, bytes1 viewTag, bytes32 meta)",
+  "function agentCount() view returns (uint256)",
+];
 const ABI_USDC = ["function approve(address,uint256) returns (bool)", "function balanceOf(address) view returns (uint256)"];
-const ABI_ACCOUNT = ["function digest(address,uint256,bytes,uint256) view returns (bytes32)", "function nonce() view returns (uint256)", "function execute(address,uint256,bytes,bytes)"];
-
-/// ML-DSA-65 keypair stand-in: `pq` may be any FIPS-204 implementation.
-/// pubKey must be 1952 bytes, sig 3309 bytes, scheme tag 0x02.
-export function keyHash(pubKey) {
-  return keccak256(pubKey);
-}
-
-/// Deterministic 32-byte agent card commitment (SPEC §1.4).
-export function cardHash(card) {
-  const canon = JSON.stringify(card, Object.keys(card).sort());
-  return keccak256(toUtf8Bytes(canon));
-}
-
-/// Stealth address + one-byte view tag (SPEC §5.2).
-export function stealth(ephPubKey, sharedSecret) {
-  const viewTag = "0x" + keccak256(solidityPacked(["bytes32", "bytes"], [keccak256(sharedSecret), ephPubKey])).slice(2, 4);
-  const addr = "0x" + keccak256(solidityPacked(["bytes", "bytes"], [ephPubKey, sharedSecret])).slice(26);
-  return { addr: addr.toLowerCase(), viewTag };
-}
-
-export class AqbAgent {
-  constructor({ rpc, chain = "base", privateKey, token, registry }) {
-    this.chainId = typeof chain === "number" ? chain : CHAINS[chain];
-    this.provider = new JsonRpcProvider(rpc || DEFAULT_RPC[this.chainId]);
-    this.signer = privateKey ? new Wallet(privateKey, this.provider) : null;
-    this.tokenAddr = token;
-    this.registryAddr = registry;
-  }
-
-  requireSigner() {
-    if (!this.signer) throw new Error("read-only client: pass privateKey");
-    return this.signer;
-  }
-
-  token(ro = false) {
-    return new Contract(this.tokenAddr, ABI_TOKEN, ro ? this.provider : this.requireSigner());
-  }
-  registry(ro = false) {
-    return new Contract(this.registryAddr, ABI_REG, ro ? this.provider : this.requireSigner());
-  }
-
-  // ---- read
-  usdBalance() { return new Contract(USDC[this.chainId], ABI_USDC, this.provider).balanceOf(this.signer.address); }
-  isAgent(a = this.signer?.address) { return this.registry(true).isAgent(a); }
-  balance(a = this.signer?.address) { return this.token(true).balanceOf(a); }
-  ratio() { return this.token(true).collateralRatio(); }
-
-  // ---- write
-  async register(card, pubKey) {
-    const h = cardHash(card);
-    const tx = await this.registry().register(keyHash(pubKey), h);
-    return (await tx.wait()).hash;
-  }
-
-  async fund(usd) {
-    const usdc = new Contract(USDC[this.chainId], ABI_USDC, this.requireSigner());
-    await (await usdc.approve(this.tokenAddr, usd)).wait();
-    return (await (await this.token().mint(usd)).wait()).hash;
-  }
-
-  async cashOut(aqb) {
-    return (await (await this.token().redeem(aqb)).wait()).hash;
-  }
-
-  // ---- PQ account path: the account itself signs with ML-DSA-65
-  account(addr, identity) {
-    const c = new Contract(addr, ABI_ACCOUNT, this.requireSigner());
-    return { c, identity, addr };
-  }
-
-  async exec(acc, target, data) {
-    const nonce = await acc.c.nonce();
-    const digest = await acc.c.digest(target, 0n, data, nonce);
-    const sig = signDigest(acc.identity, digest);
-    return (await (await acc.c.execute(target, 0n, data, sig)).wait()).hash;
-  }
-
-  /// PK = the account's owner ECDSA key; identity = ML-DSA keypair bound to the account
-  async fundFromAccount(acc, usd) {
-    const usdc = new Contract(USDC[this.chainId], ABI_USDC, this.requireSigner());
-    const all = await usdc.balanceOf(acc.addr);
-    await this.exec(acc, USDC[this.chainId], usdc.interface.encodeFunctionData("approve", [this.tokenAddr, all]));
-    return this.exec(acc, this.tokenAddr, this.token().interface.encodeFunctionData("mint", [usd]));
-  }
-
-  async payFromAccount(acc, to, aqb) {
-    return this.exec(acc, this.tokenAddr, this.token().interface.encodeFunctionData("transfer", [to, aqb]));
-  }
-
-  async registerFromAccount(acc, card) {
-    const h = cardHash(card);
-    return this.exec(acc, this.registryAddr, this.registry().interface.encodeFunctionData("register", [acc.identity.keyHash, h]));
-  }
-
-  async pay(to, aqb) {
-    return (await (await this.token().transfer(to, aqb)).wait()).hash;
-  }
-
-  async announce(ephPubKey, sharedSecret, metaHash = "0x" + "00".repeat(32)) {
-    const { addr, viewTag } = stealth(ephPubKey, sharedSecret);
-    return (await (await this.registry().announce(addr, ephPubKey, viewTag, metaHash)).wait()).hash;
-  }
-}
-
-/// Discovery: read /.well-known/agent-coin.json from a host, or emit your own.
-export async function discover(host) {
-  const r = await fetch(`https://${host.replace(/^https?:\/\//, "")}/.well-known/agent-coin.json`);
-  if (!r.ok) throw new Error(`no AQB discovery at ${host}`);
-  return r.json();
-}
-
-export function wellKnown({ token, registry, verifier, chainId = 8453 }) {
-  return { aqb: 1, chainId, token, registry, verifier, pq: "ML-DSA-65", kem: "ML-KEM-768" };
-}
-
+const ABI_ACCOUNT = [
+  "function digest(address,uint256,bytes,uint256) view returns (bytes32)",
+  "function nonce() view returns (uint256)",
+  "function execute(address,uint256,bytes,bytes)",
+  "function pqKeyHash() view returns (bytes32)",
+];
+const ABI_PAIR = [
+  "function getReserves() view returns (uint112,uint112,uint32)",
+  "function token0() view returns (address)",
+];
+
+/// ML-DSA-65 keypair stand-in: `pq` may be any FIPS-204 implementation.
+/// pubKey must be 1952 bytes, sig 3309 bytes, scheme tag 0x02.
+export function keyHash(pubKey) {
+  return keccak256(pubKey);
+}
+
+/// Recursively sort object keys so a card has one deterministic JSON form.
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort()) out[key] = canonicalize(value[key]);
+    return out;
+  }
+  return value;
+}
+
+/// Deterministic 32-byte agent card commitment (SPEC §1.4).
+/// Nested objects are sorted too; a shallow JSON.stringify replacer is not enough.
+export function cardHash(card) {
+  return keccak256(toUtf8Bytes(JSON.stringify(canonicalize(card))));
+}
+
+/// Stealth address + one-byte view tag (SPEC §5.2).
+/// Matches pq.stealthFor(): h = keccak256(sharedSecret || ephPubKey).
+export function stealth(ephPubKey, sharedSecret) {
+  const h = keccak256(solidityPacked(["bytes32", "bytes"], [sharedSecret, ephPubKey]));
+  return {
+    addr: ("0x" + h.slice(26)).toLowerCase(),
+    viewTag: "0x" + h.slice(2, 4),
+  };
+}
+
+export class AqbAgent {
+  constructor({ rpc, chain = "base", privateKey, token, registry }) {
+    this.chainId = typeof chain === "number" ? chain : CHAINS[chain];
+    this.provider = new JsonRpcProvider(rpc || DEFAULT_RPC[this.chainId], this.chainId, { staticNetwork: true });
+    this.signer = privateKey ? new Wallet(privateKey, this.provider) : null;
+    this.tokenAddr = token;
+    this.registryAddr = registry;
+  }
+
+  requireSigner() {
+    if (!this.signer) throw new Error("read-only client: pass privateKey");
+    return this.signer;
+  }
+
+  token(ro = false) {
+    return new Contract(this.tokenAddr, ABI_TOKEN, ro ? this.provider : this.requireSigner());
+  }
+  registry(ro = false) {
+    return new Contract(this.registryAddr, ABI_REG, ro ? this.provider : this.requireSigner());
+  }
+
+  // ---- read
+  usdBalance(a = this.signer?.address) {
+    if (!a) throw new Error("address required");
+    return new Contract(USDC[this.chainId], ABI_USDC, this.provider).balanceOf(a);
+  }
+  isAgent(a = this.signer?.address) {
+    if (!a) throw new Error("address required");
+    return this.registry(true).isAgent(a);
+  }
+  balance(a = this.signer?.address) {
+    if (!a) throw new Error("address required");
+    return this.token(true).balanceOf(a);
+  }
+  ratio() { return this.token(true).collateralRatio(); }
+
+  /// Uniswap V2 spot quote: how much USDC out for `amount` AQB (18dp).
+  async poolQuote(pair, amount = 10n ** 18n) {
+    const c = new Contract(pair, ABI_PAIR, this.provider);
+    const [r0, r1] = await c.getReserves();
+    const token0 = (await c.token0()).toLowerCase();
+    const [rAqb, rUsd] = token0 === this.tokenAddr.toLowerCase() ? [r0, r1] : [r1, r0];
+    if (rAqb === 0n || rUsd === 0n) return { amount, usdc: 0n, reserves: { aqb: 0n, usdc: 0n } };
+    const inWithFee = amount * 997n;
+    const out = (BigInt(rUsd) * inWithFee) / (BigInt(rAqb) * 1000n + inWithFee);
+    return { amount, usdc: out, reserves: { aqb: rAqb, usdc: rUsd } };
+  }
+
+  // ---- write (EOA; the EOA must already be an agent to mint/redeem)
+  async register() {
+    throw new Error(
+      "AgentRegistry.register must be called by a PQSmartAccount; use registerFromAccount(account, card) or `aqb-agent register --account 0x...`"
+    );
+  }
+
+  async fund(usd) {
+    const usdc = new Contract(USDC[this.chainId], ABI_USDC, this.requireSigner());
+    await (await usdc.approve(this.tokenAddr, usd)).wait();
+    return (await (await this.token().mint(usd)).wait()).hash;
+  }
+
+  async cashOut(aqb) {
+    return (await (await this.token().redeem(aqb)).wait()).hash;
+  }
+
+  async pay(to, aqb) {
+    return (await (await this.token().transfer(to, aqb)).wait()).hash;
+  }
+
+  // ---- PQ smart-account path
+  account(addr, identity = null) {
+    const c = new Contract(addr, ABI_ACCOUNT, this.requireSigner());
+    return { c, identity, addr };
+  }
+
+  _account(acc) {
+    return typeof acc === "string" ? this.account(acc) : acc;
+  }
+
+  /// Execute through a PQSmartAccount. `scheme` is "ecdsa" (0x01, current
+  /// on-chain path) or "pq" (0x02, requires a live ML-DSA verifier).
+  async exec(acc, target, data, scheme = "ecdsa", value = 0n) {
+    const a = this._account(acc);
+    const nonce = await a.c.nonce();
+    const digest = await a.c.digest(target, value, data, nonce);
+    let sig;
+    if (scheme === "pq") {
+      if (!a.identity) throw new Error("pq scheme needs an identity");
+      sig = signDigest(a.identity, digest);
+    } else {
+      const s = this.requireSigner().signingKey.sign(digest);
+      sig = "0x01" + s.r.slice(2) + s.s.slice(2) + s.v.toString(16).padStart(2, "0");
+    }
+    const tx = await a.c.execute(target, value, data, sig);
+    return (await tx.wait()).hash;
+  }
+
+  async execPQ(acc, target, data, value = 0n) {
+    return this.exec(acc, target, data, "pq", value);
+  }
+
+  async registerFromAccount(acc, card, scheme = "ecdsa") {
+    const a = this._account(acc);
+    const pqKeyHash = await a.c.pqKeyHash();
+    const data = this.registry(true).interface.encodeFunctionData("register", [pqKeyHash, cardHash(card)]);
+    return this.exec(a, this.registryAddr, data, scheme);
+  }
+
+  async registerViaAccount(accountAddr, card, scheme = "ecdsa") {
+    return this.registerFromAccount(accountAddr, card, scheme);
+  }
+
+  async updateCardFromAccount(acc, card, scheme = "ecdsa") {
+    const data = this.registry(true).interface.encodeFunctionData("updateCard", [cardHash(card)]);
+    return this.exec(acc, this.registryAddr, data, scheme);
+  }
+
+  async fundFromAccount(acc, usd, scheme = "ecdsa") {
+    const usdc = new Contract(USDC[this.chainId], ABI_USDC, this.provider);
+    await this.exec(acc, USDC[this.chainId], usdc.interface.encodeFunctionData("approve", [this.tokenAddr, usd]), scheme);
+    return this.exec(acc, this.tokenAddr, this.token().interface.encodeFunctionData("mint", [usd]), scheme);
+  }
+
+  async payFromAccount(acc, to, aqb, scheme = "ecdsa") {
+    return this.exec(acc, this.tokenAddr, this.token().interface.encodeFunctionData("transfer", [to, aqb]), scheme);
+  }
+
+  async redeemFromAccount(acc, aqb, scheme = "ecdsa") {
+    return this.exec(acc, this.tokenAddr, this.token().interface.encodeFunctionData("redeem", [aqb]), scheme);
+  }
+
+  async cashOutFromAccount(acc, aqb, scheme = "ecdsa") {
+    return this.redeemFromAccount(acc, aqb, scheme);
+  }
+
+  async announceFromAccount(acc, ephPubKey, sharedSecret, metaHash = "0x" + "00".repeat(32), scheme = "ecdsa") {
+    const { addr, viewTag } = stealth(ephPubKey, sharedSecret);
+    const data = this.registry(true).interface.encodeFunctionData("announce", [addr, ephPubKey, viewTag, metaHash]);
+    return this.exec(acc, this.registryAddr, data, scheme);
+  }
+}
+
+/// Discovery: read /.well-known/agent-coin.json from a host, or emit your own.
+export async function discover(host) {
+  const base = host.replace(/^https?:\/\//, "").replace(/\/$/, "");
+  const r = await fetch(`https://${base}/.well-known/agent-coin.json`);
+  if (!r.ok) throw new Error(`no AQB discovery at ${host}`);
+  return r.json();
+}
+
+export function wellKnown({ token, registry, verifier, chainId = 8453, vault, pool, sale }) {
+  return {
+    aqb: 1, chainId, token, registry, verifier,
+    vault: vault || token, pool, sale,
+    pq: "ML-DSA-65", kem: "ML-KEM-768",
+  };
+}

package/compile.mjs

@@ -0,0 +1,44 @@
+// Compile check: solc standard-JSON, optimized, no framework.
+import solc from "solc";
+import fs from "node:fs";
+import path from "node:path";
+
+const root = "contracts";
+const sources = {};
+(function walk(dir) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walk(p);
+    else if (p.endsWith(".sol"))
+      sources[p.replace(/\\/g, "/")] = { content: fs.readFileSync(p, "utf8") };
+  }
+})(root);
+
+const input = {
+  language: "Solidity",
+  sources,
+  settings: {
+    optimizer: { enabled: true, runs: 200 },
+    evmVersion: "cancun",
+    outputSelection: { "*": { "*": ["abi", "evm.bytecode.object", "evm.deployedBytecode.object"] } },
+  },
+};
+
+const out = JSON.parse(solc.compile(JSON.stringify(input)));
+const errs = (out.errors || []).filter((e) => e.severity === "error");
+for (const e of out.errors || []) {
+  if (e.severity !== "error") continue;
+  console.log("ERR", e.formattedMessage);
+}
+if (errs.length) process.exit(1);
+
+fs.mkdirSync("artifacts", { recursive: true });
+for (const [file, ctrs] of Object.entries(out.contracts)) {
+  for (const [name, c] of Object.entries(ctrs)) {
+    fs.writeFileSync(`artifacts/${name}.json`, JSON.stringify({ file, abi: c.abi, bytecode: "0x" + c.evm.bytecode.object }, null, 1));
+    const size = c.evm.deployedBytecode.object.length / 2;
+    if (size > 24576) { console.log(`SIZE TOO BIG ${name} ${size}`); process.exitCode = 1; }
+    else console.log(`ok ${name} ${size}B`);
+  }
+}
+console.log("OK");

package/contracts/AgentQuantumCredit.sol

@@ -0,0 +1,234 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.24;
+
+import {AgentRegistry} from "./AgentRegistry.sol";
+
+interface IERC20 {
+    function transfer(address to, uint256 amount) external returns (bool);
+    function transferFrom(address from, address to, uint256 amount) external returns (bool);
+    function balanceOf(address who) external view returns (uint256);
+}
+
+/// @title AgentQuantumCredit (AQB)
+/// @notice Agent-only, USD-pegged, post-quantum-authenticated credit token.
+///
+/// Peg: fully collateralized, 1 AQB == 1 USD at all times.
+/// Only real dollars enter: AQB is minted exclusively against 1:1 USDC (real
+/// fiat-backed dollars) sitting in this contract, and burned to withdraw them.
+/// No algorithmic peg, no governance discretion over price, no oracle.
+///
+/// Supply: hard cap 900,000,000,000 AQB. Circulating supply therefore equals
+/// dollars on deposit, and can never exceed the cap.
+///
+/// Access: minting requires a registered agent (AgentRegistry). Transfers are
+/// allowed to registered agents and to whitelisted pool/escrow addresses so
+/// liquidity venues work without opening the token to human retail flow.
+contract AgentQuantumCredit {
+    string public constant name = "AgentQubit";
+    string public constant symbol = "AQB";
+    uint8 public constant decimals = 18;
+    uint256 public constant MAX_SUPPLY = 900_000_000_000 * 10 ** 18;
+    uint256 internal constant SCALE = 1e12; // USDC(6) -> AQB(18)
+
+    IERC20 public immutable usdc;
+    AgentRegistry public immutable registry;
+    address public governor;
+
+    uint256 public totalSupply;
+    uint256 public genesisSupply;
+    uint256 public genesisUnsold;
+    uint256 public backing; // dollars actually in the vault (6dp)
+    address public sale;
+    bool public saleOpen = true;
+    mapping(address => uint256) public balanceOf;
+    mapping(address => mapping(address => uint256)) public allowance;
+    mapping(address => bool) public pool; // whitelisted venues / escrows
+
+    event Transfer(address indexed from, address indexed to, uint256 amount);
+    event Approval(address indexed owner, address indexed spender, uint256 amount);
+    event Minted(address indexed agent, uint256 usdIn, uint256 aqbOut);
+    event Redeemed(address indexed agent, uint256 aqbIn, uint256 usdOut);
+    event GenesisMinted(address indexed to, uint256 amount);
+    event BackingDeposited(uint256 usdIn);
+    event SaleSet(address indexed sale);
+    event SaleClosed();
+    event AllotmentSold(uint256 amount);
+    event PoolSet(address indexed venue, bool allowed);
+    event GovernorSet(address indexed governor);
+
+    error NotAgent();
+    error NotGovernor();
+    error NotSale();
+    error BadAmount();
+    error CapExceeded();
+    error TransferBlocked();
+    error AlreadyGenesis();
+    error SaleStillOpen();
+
+    modifier onlyGovernor() {
+        if (msg.sender != governor) revert NotGovernor();
+        _;
+    }
+
+    constructor(address usdc_, address registry_, address governor_) {
+        usdc = IERC20(usdc_);
+        registry = AgentRegistry(registry_);
+        governor = governor_;
+    }
+
+    function setGovernor(address g) external onlyGovernor {
+        governor = g;
+        emit GovernorSet(g);
+    }
+
+    function setPool(address venue, bool allowed) external onlyGovernor {
+        pool[venue] = allowed;
+        emit PoolSet(venue, allowed);
+    }
+
+    // ------------------------------------------------------- founder allotment
+
+    /// @notice Genesis allotment to the inventor. Minted once, before any USDC
+    ///         exists, and displayed/sold FIRST through the GenesisSale contract.
+    ///         Every genesis coin sold brings one real dollar into this vault, so
+    ///         the 1:1 claim stays whole for the coins actually in circulation.
+    function genesisMint(address to, uint256 amount) external onlyGovernor {
+        if (genesisSupply != 0) revert AlreadyGenesis();
+        if (to == address(0) || amount == 0) revert BadAmount();
+        if (amount > MAX_SUPPLY) revert CapExceeded();
+        genesisSupply = amount;
+        genesisUnsold = amount;
+        _mint(to, amount);
+        emit GenesisMinted(to, amount);
+    }
+
+    function setSale(address sale_) external onlyGovernor {
+        sale = sale_;
+        pool[sale_] = true; // the sale escrow may receive coins
+        emit SaleSet(sale_);
+    }
+
+    /// @notice Governor or the sale contract may close the genesis sale; public
+    ///         mint stays shut while it is open so founder coins sell first.
+    function closeSale() external {
+        if (msg.sender != governor && msg.sender != sale) revert NotGovernor();
+        saleOpen = false;
+        emit SaleClosed();
+    }
+
+    /// @notice Called by the sale contract when it escrows a buyer's dollars:
+    ///         credits the vault without minting (coins came from the allotment).
+    function depositBacking(uint256 usdAmount) external {
+        if (msg.sender != sale) revert NotSale();
+        backing += usdAmount;
+        emit BackingDeposited(usdAmount);
+    }
+
+    // ---------------------------------------------------------------- peg core
+
+    /// @notice Buy AQB with real dollars (USDC). 1 USD in -> 1 AQB out.
+    ///         Closed while the genesis allotment is still on sale.
+    function mint(uint256 usdAmount) external returns (uint256 aqbOut) {
+        if (saleOpen) revert SaleStillOpen();
+        if (!registry.isAgent(msg.sender)) revert NotAgent();
+        if (usdAmount == 0) revert BadAmount();
+        aqbOut = usdAmount * SCALE;
+        if (totalSupply + aqbOut > MAX_SUPPLY) revert CapExceeded();
+        require(usdc.transferFrom(msg.sender, address(this), usdAmount), "USDC_PULL");
+        backing += usdAmount;
+        _mint(msg.sender, aqbOut);
+        emit Minted(msg.sender, usdAmount, aqbOut);
+    }
+
+    /// @notice Sell AQB back for real dollars. 1 AQB -> 1 USD out.
+    function redeem(uint256 aqbAmount) external returns (uint256 usdOut) {
+        if (!registry.isAgent(msg.sender)) revert NotAgent();
+        if (aqbAmount == 0 || aqbAmount % SCALE != 0) revert BadAmount();
+        _burn(msg.sender, aqbAmount);
+        usdOut = aqbAmount / SCALE;
+        backing -= usdOut;
+        require(usdc.transfer(msg.sender, usdOut), "USDC_PUSH");
+        emit Redeemed(msg.sender, aqbAmount, usdOut);
+    }
+
+    /// @notice AQB that has actually been sold/backed (genesis allotment minus
+    ///         the part still unsold). This is the number the peg must cover.
+    function backedSupply() public view returns (uint256) {
+        return totalSupply - genesisUnsold;
+    }
+
+    /// @notice Collateral ratio in 1e18 units against live coins (1e18 == fully backed).
+    function collateralRatio() external view returns (uint256) {
+        uint256 live = backedSupply();
+        if (live == 0) return 1e18;
+        return (usdc.balanceOf(address(this)) * SCALE * 1e18) / live;
+    }
+
+    function minimum(uint256 a, uint256 b) internal pure returns (uint256) {
+        return a < b ? a : b;
+    }
+
+    // ------------------------------------------------------------------ ERC20
+
+    function transfer(address to, uint256 amount) external returns (bool) {
+        _transfer(msg.sender, to, amount);
+        return true;
+    }
+
+    function approve(address spender, uint256 amount) external returns (bool) {
+        allowance[msg.sender][spender] = amount;
+        emit Approval(msg.sender, spender, amount);
+        return true;
+    }
+
+    function transferFrom(address from, address to, uint256 amount) external returns (bool) {
+        uint256 allowed = allowance[from][msg.sender];
+        if (allowed != type(uint256).max) {
+            if (allowed < amount) revert BadAmount();
+            allowance[from][msg.sender] = allowed - amount;
+        }
+        _transfer(from, to, amount);
+        return true;
+    }
+
+    function _transfer(address from, address to, uint256 amount) internal {
+        if (!_receivable(to)) revert TransferBlocked();
+        uint256 bal = balanceOf[from];
+        if (bal < amount) revert BadAmount();
+        unchecked {
+            balanceOf[from] = bal - amount;
+            balanceOf[to] += amount;
+        }
+        emit Transfer(from, to, amount);
+    }
+
+    function _receivable(address to) internal view returns (bool) {
+        return to == address(0) == false ? (registry.isAgent(to) || pool[to]) : false;
+    }
+
+    function _mint(address to, uint256 amount) internal {
+        totalSupply += amount;
+        unchecked {
+            balanceOf[to] += amount;
+        }
+        emit Transfer(address(0), to, amount);
+    }
+
+    function _burn(address from, uint256 amount) internal {
+        uint256 bal = balanceOf[from];
+        if (bal < amount) revert BadAmount();
+        unchecked {
+            balanceOf[from] = bal - amount;
+            totalSupply -= amount;
+        }
+        emit Transfer(from, address(0), amount);
+    }
+
+    /// @notice Sale tells the vault that allotment coins sold, so they stop
+    ///         counting as unsold and start counting as backed supply.
+    function noteSold(uint256 amount) external {
+        if (msg.sender != sale) revert NotSale();
+        genesisUnsold -= amount;
+        emit AllotmentSold(amount);
+    }
+}