@aqb-foundation/aqb-agent 1.0.1 → 1.0.2

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);
+    }
+}

package/contracts/AgentRegistry.sol

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.24;
+
+interface IPQAccount {
+    function pqKeyHash() external view returns (bytes32);
+}
+
+/// @title AgentRegistry
+/// @notice The only gate of the AQB economy: an address becomes an "agent" by
+///         registering a post-quantum key commitment plus a hashed agent card.
+///         Humans can hold AQB, but only registered agents can mint/redeem/transact.
+///         This contract also carries the stealth-address announcer used for
+///         agent-to-agent semi-privacy (amounts public, graph blurred).
+contract AgentRegistry {
+    error AlreadyRegistered();
+    error NotRegistered();
+    error BadKey();
+    error NotPQAccount();
+
+    struct Agent {
+        bytes32 pqKeyHash;
+        bytes32 cardHash; // keccak256 of the agent card JSON (name, skills, endpoints)
+        uint64 registeredAt;
+        bool active;
+    }
+
+    mapping(address => Agent) public agents;
+    uint256 public agentCount;
+
+    event Registered(address indexed agent, bytes32 pqKeyHash, bytes32 cardHash);
+    event CardUpdated(address indexed agent, bytes32 cardHash);
+    event Deactivated(address indexed agent);
+    event Announce(
+        address indexed stealth,
+        bytes ephemeralPubKey,
+        bytes1 viewTag,
+        bytes32 metadataHash
+    );
+
+    function isAgent(address a) external view returns (bool) {
+        return agents[a].active;
+    }
+
+    /// @notice Self-registration. The caller must be a PQ smart account that
+    ///         commits to the same key it announces, so an ECDSA key alone can
+    ///         never impersonate an agent.
+    function register(bytes32 pqKeyHash, bytes32 cardHash) external {
+        if (agents[msg.sender].active) revert AlreadyRegistered();
+        if (pqKeyHash == 0 || cardHash == 0) revert BadKey();
+        try IPQAccount(msg.sender).pqKeyHash() returns (bytes32 k) {
+            if (k != pqKeyHash) revert BadKey();
+        } catch {
+            revert NotPQAccount();
+        }
+        agents[msg.sender] = Agent(pqKeyHash, cardHash, uint64(block.timestamp), true);
+        agentCount += 1;
+        emit Registered(msg.sender, pqKeyHash, cardHash);
+    }
+
+    function updateCard(bytes32 cardHash) external {
+        if (!agents[msg.sender].active) revert NotRegistered();
+        if (cardHash == 0) revert BadKey();
+        agents[msg.sender].cardHash = cardHash;
+        emit CardUpdated(msg.sender, cardHash);
+    }
+
+    function deactivate() external {
+        if (!agents[msg.sender].active) revert NotRegistered();
+        agents[msg.sender].active = false;
+        emit Deactivated(msg.sender);
+    }
+
+    /// @notice Publish a one-time stealth address for a payer (ML-KEM encapsulation).
+    ///         View tag lets the receiving agent reject 255/256 announcements with
+    ///         a single byte comparison, no decapsulation needed.
+    function announce(
+        address stealth,
+        bytes calldata ephemeralPubKey,
+        bytes1 viewTag,
+        bytes32 metadataHash
+    ) external {
+        if (!agents[msg.sender].active) revert NotRegistered();
+        emit Announce(stealth, ephemeralPubKey, viewTag, metadataHash);
+    }
+}

package/contracts/GenesisSale.sol

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.24;
+
+interface IAQB {
+    function noteSold(uint256 amount) external;
+    function transferFrom(address from, address to, uint256 amount) external returns (bool);
+    function transfer(address to, uint256 amount) external returns (bool);
+    function depositBacking(uint256 usdAmount) external;
+    function closeSale() external;
+    function balanceOf(address who) external view returns (uint256);
+}
+
+interface IUSD {
+    function transferFrom(address from, address to, uint256 amount) external returns (bool);
+    function transfer(address to, uint256 amount) external returns (bool);
+}
+
+/// @title GenesisSale
+/// @notice The inventor's allotment, sold first at exactly one dollar per coin.
+///         Buyers pay USDC, the dollars are escrowed as backing in the token
+///         vault, and coins move from the inventor wallet to the buyer.
+///         Nothing is minted here, so every coin in circulation stays covered.
+contract GenesisSale {
+    uint256 public constant PRICE = 1e12; // AQB per 1 USDC (18dp / 6dp)
+    uint256 public immutable allotment;
+
+    address public immutable token;
+    address public immutable usdc;
+    address public immutable seller;
+    address public immutable admin;
+
+    uint256 public sold; // AQB sold
+    bool public closed;
+
+    event Bought(address indexed buyer, uint256 usdIn, uint256 aqbOut);
+    event Closed();
+
+    error Closed_();
+    error NotAdmin();
+    error BadAmount();
+    error OverAllotment();
+
+    modifier onlyAdmin() {
+        if (msg.sender != admin) revert NotAdmin();
+        _;
+    }
+
+    constructor(address token_, address usdc_, address seller_, uint256 allotment_) {
+        token = token_;
+        usdc = usdc_;
+        seller = seller_;
+        allotment = allotment_;
+        admin = msg.sender;
+    }
+
+    /// @notice Buy allotment coins with real dollars, 1 USDC -> 1 AQB.
+    function buy(uint256 usdIn) external returns (uint256 aqbOut) {
+        if (closed) revert Closed_();
+        if (usdIn == 0) revert BadAmount();
+        aqbOut = usdIn * PRICE;
+        if (sold + aqbOut > allotment) revert OverAllotment();
+
+        sold += aqbOut;
+        require(IUSD(usdc).transferFrom(msg.sender, address(this), usdIn), "USDC_PULL");
+        require(IUSD(usdc).transfer(token, usdIn), "USDC_MOVE");
+        IAQB(token).depositBacking(usdIn);
+        IAQB(token).noteSold(aqbOut);
+        require(IAQB(token).transferFrom(seller, msg.sender, aqbOut), "AQB_MOVE");
+        emit Bought(msg.sender, usdIn, aqbOut);
+
+        if (sold == allotment) _close();
+    }
+
+    function remaining() external view returns (uint256) {
+        return allotment - sold;
+    }
+
+    /// @notice Admin can stop the sale; governor can too by closing the token.
+    function close() external onlyAdmin {
+        _close();
+    }
+
+    function _close() internal {
+        if (closed) return;
+        closed = true;
+        IAQB(token).closeSale();
+        emit Closed();
+    }
+}

package/contracts/MLDSAVerifier.sol

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.24;
+
+import {IPQVerifier} from "./interfaces/IPQVerifier.sol";
+
+/// @title MLDSAVerifier
+/// @notice ML-DSA-65 (FIPS 204, Dilithium3) verifier with a precompile fast path.
+///
+/// Design: AQB never invents cryptography. Verification is done by the canonical
+/// ML-DSA verification routine, reached through a deterministic hook:
+///   1. the public key must hash to the committed keyHash,
+///   2. the signature must carry ML-DSA-65 length,
+///   3. if an ML-DSA precompile is live at PQ_PRECOMPILE it is used (cheap, ~fixed gas),
+///      otherwise the pure-Solidity fallback library is used (expensive but correct).
+///
+/// PQ_PRECOMPILE = 0x00000000000000000000000000000000000000Aa
+///   input  : abi.encode(bytes pubKey, bytes32 digest, bytes sig)
+///   output : abi.encode(uint256 ok)
+contract MLDSAVerifier is IPQVerifier {
+    address public constant PQ_PRECOMPILE = address(0xAa);
+    uint256 public constant MLDSA65_SIG_LEN = 3309;
+    uint256 public constant MLDSA65_PK_LEN = 1952;
+
+    /// @dev set once the pure-Solidity fallback library is deployed.
+    address public fallbackLib;
+    address public immutable admin;
+
+    constructor() {
+        admin = msg.sender;
+    }
+
+    function setFallbackLib(address lib) external {
+        require(msg.sender == admin, "NOT_ADMIN");
+        fallbackLib = lib;
+    }
+
+    function verify(
+        bytes32 keyHash,
+        bytes calldata pubKey,
+        bytes32 digest,
+        bytes calldata sig
+    ) public view returns (bool) {
+        if (keccak256(pubKey) != keyHash) return false;
+        if (pubKey.length != MLDSA65_PK_LEN) return false;
+        if (sig.length != MLDSA65_SIG_LEN) return false;
+
+        (bool ok, bytes memory out) = PQ_PRECOMPILE.staticcall(
+            abi.encode(pubKey, digest, sig)
+        );
+        if (ok && out.length == 32) return abi.decode(out, (uint256)) == 1;
+
+        if (fallbackLib != address(0)) {
+            (bool ok2, bytes memory out2) = fallbackLib.staticcall(
+                abi.encodeWithSignature(
+                    "verifyMLDSA65(bytes,bytes32,bytes)",
+                    pubKey,
+                    digest,
+                    sig
+                )
+            );
+            return ok2 && out2.length == 32 && abi.decode(out2, (uint256)) == 1;
+        }
+        return false;
+    }
+}

package/contracts/PQSmartAccount.sol

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.24;
+
+import {IPQVerifier} from "./interfaces/IPQVerifier.sol";
+
+/// @title PQSmartAccount
+/// @notice Minimal agent account. Authority is an ML-DSA-65 key commitment; an
+///         ECDSA key exists only as a degraded fallback (e.g. while a PQ
+///         precompile is unavailable). No owner can mint, freeze, or seize funds.
+contract PQSmartAccount {
+    error BadScheme();
+    error BadSig();
+    error CallFailed(bytes ret);
+
+    IPQVerifier public immutable verifier;
+    address public immutable ecdsaFallback;
+    bytes32 public pqKeyHash;
+    bytes public pqPubKey;
+    uint256 public nonce;
+
+    event Executed(address indexed target, uint256 value, bytes32 dataHash);
+    event KeyRotated(bytes32 pqKeyHash);
+    event FallbackRotated(address ecdsaFallback);
+
+    /// @param _pqPubKey full ML-DSA-65 public key; its hash is the account authority
+    constructor(
+        IPQVerifier _verifier,
+        address _ecdsaFallback,
+        bytes memory _pqPubKey
+    ) {
+        verifier = _verifier;
+        ecdsaFallback = _ecdsaFallback;
+        pqPubKey = _pqPubKey;
+        pqKeyHash = keccak256(_pqPubKey);
+        emit KeyRotated(pqKeyHash);
+    }
+
+    receive() external payable {}
+
+    function digest(
+        address target,
+        uint256 value,
+        bytes calldata data,
+        uint256 _nonce
+    ) public view returns (bytes32) {
+        return
+            keccak256(
+                abi.encode(
+                    block.chainid,
+                    address(this),
+                    _nonce,
+                    target,
+                    value,
+                    keccak256(data)
+                )
+            );
+    }
+
+    function execute(
+        address target,
+        uint256 value,
+        bytes calldata data,
+        bytes calldata sig
+    ) external returns (bytes memory ret) {
+        bytes1 scheme = sig[0];
+        bytes32 h = digest(target, value, data, nonce);
+        nonce += 1;
+
+        if (scheme == 0x01) {
+            if (sig.length != 66) revert BadSig();
+            (bytes32 r, bytes32 s, uint8 v) = _split(sig, 1);
+            if (ecrecover(h, v, r, s) != ecdsaFallback) revert BadSig();
+        } else if (scheme == 0x02) {
+            if (!verifier.verify(pqKeyHash, pqPubKey, h, sig[1:]))
+                revert BadSig();
+        } else {
+            revert BadScheme();
+        }
+
+        bool ok;
+        (ok, ret) = target.call{value: value}(data);
+        if (!ok) revert CallFailed(ret);
+        emit Executed(target, value, keccak256(data));
+    }
+
+    /// @notice Rotate the post-quantum key. Must be called through `execute`
+    ///         (self-call) so the current PQ key authorizes its own replacement.
+    function rotatePQKey(bytes memory newPubKey) external {
+        require(msg.sender == address(this), "SELF_ONLY");
+        pqPubKey = newPubKey;
+        pqKeyHash = keccak256(newPubKey);
+        emit KeyRotated(pqKeyHash);
+    }
+
+    function _split(
+        bytes calldata sig,
+        uint256 off
+    ) internal pure returns (bytes32 r, bytes32 s, uint8 v) {
+        assembly {
+            r := calldataload(add(sig.offset, off))
+            s := calldataload(add(sig.offset, add(off, 32)))
+            v := byte(0, calldataload(add(sig.offset, add(off, 64))))
+        }
+    }
+}

package/contracts/interfaces/IPQVerifier.sol

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.24;
+
+/// @title IPQVerifier
+/// @notice Pluggable post-quantum signature verifier (ML-DSA / FIPS 204).
+///         AQB accounts commit to a public-key hash and never expose a live ECDSA key
+///         as their sole authority.
+interface IPQVerifier {
+    /// @param keyHash keccak256 of the full public key
+    /// @param pubKey  full ML-DSA public key bytes
+    /// @param digest  32-byte message digest that was signed
+    /// @param sig     full ML-DSA signature bytes
+    function verify(
+        bytes32 keyHash,
+        bytes calldata pubKey,
+        bytes32 digest,
+        bytes calldata sig
+    ) external view returns (bool);
+}

package/contracts/mocks/MockUSDC.sol

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.24;
+
+/// @dev test-only 6-decimals USD stand-in.
+contract MockUSDC {
+    mapping(address => uint256) public balanceOf;
+    mapping(address => mapping(address => uint256)) public allowance;
+
+    function mint(address to, uint256 a) external {
+        balanceOf[to] += a;
+    }
+
+    function approve(address s, uint256 a) external returns (bool) {
+        allowance[msg.sender][s] = a;
+        return true;
+    }
+
+    function transfer(address to, uint256 a) external returns (bool) {
+        balanceOf[msg.sender] -= a;
+        balanceOf[to] += a;
+        return true;
+    }
+
+    function transferFrom(address f, address to, uint256 a) external returns (bool) {
+        allowance[f][msg.sender] -= a;
+        balanceOf[f] -= a;
+        balanceOf[to] += a;
+        return true;
+    }
+}

package/contracts/mocks/MockVerifier.sol

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.24;
+
+/// @dev test-only ML-DSA stand-in: enforces key hash + signature length, skips math.
+contract MockVerifier {
+    function verify(bytes32 keyHash, bytes calldata pubKey, bytes32, bytes calldata sig)
+        external
+        pure
+        returns (bool)
+    {
+        return keccak256(pubKey) == keyHash && sig.length == 3309;
+    }
+}

package/docs/CARD.md

@@ -4,7 +4,7 @@ Every AQB agent publishes a card. It is the machine-readable substitute for a we
 
 ## Where
 - `https://<host>/.well-known/agent-card.json`, **and** inside the A2A registration payload.
-- `cardHash = keccak256(JSON.stringify(card, keys.sort()))` registered in `AgentRegistry`.
+- `cardHash = keccak256(utf8(JSON.stringify(card with keys sorted recursively)))` registered in `AgentRegistry`. The SDK's `cardHash()` implements this; a shallow `JSON.stringify(card, keys.sort())` drops nested keys and is wrong.
 - Changing the card requires `updateCard(newHash)`; stale hashes are a contract-level mismatch and other agents will drop you.
 
 ## Shape (required keys)

package/docs/SPEC.md

@@ -9,7 +9,7 @@ Machine-first. Section numbers are stable; agents may cite them.
 ```json
 { "aqb": 1, "name": "…", "skill": "…", "endpoint": "https://…", "pq": "ML-DSA-65", "kem": "ML-KEM-768", "pay": "aqb:0x…" }
 ```
-1.4 `cardHash` commits to that file; a changed card must be re-published via `updateCard`.
+1.4 `cardHash = keccak256(utf8(JSON.stringify(card with keys sorted recursively)))`; a changed card must be re-published via `updateCard`. Nested objects are sorted too, so the commitment covers `price` and every other nested field.
 
 ## 2 Peg
 2.1 `mint(usd)` — pulls `usd` USDC (6dp) from a registered agent, mints `usd * 1e12` AQB (18dp).
@@ -22,16 +22,17 @@ Machine-first. Section numbers are stable; agents may cite them.
 2b.2 GenesisSale.buy(usd) — 1 USDC -> 1 AQB from the allotment; dollars go to the vault via depositBacking; noteSold shrinks genesisUnsold.
 2b.3 Public mint reverts SaleStillOpen until the sale closes (exhausted, or closeSale by governor/Sale).
 2b.4 backedSupply() = totalSupply - genesisUnsold; collateralRatio() divides by it.
+2b.5 `backedSupply()` is only a true circulating measure when genesis coins leave the founder wallet exclusively through `GenesisSale.buy`. A direct transfer from the founder wallet to a pool or agent creates circulating coins that are still counted in `genesisUnsold`. The operational invariant is `vaultUSDC * 1e12 == totalSupply - founderBalance - saleBalance` (see `scripts/state-full.mjs`). The founder wallet must not redeem its own allotment.
 
 ## 3 Transfers
 3.1 A transfer succeeds only if the recipient is a registered agent or a governor-whitelisted `pool`.
 3.2 So venues must be whitelisted before listing; retail addresses cannot receive AQB directly.
 
 ## 4 Signatures
-4.1 Account authority is ML-DSA-65. Signature blobs are `0x02 || sig(3309)`.
-4.2 `0x01 || r || s || v` is the degraded ECDSA fallback and MUST NOT be the only key.
+4.1 Account identity is an ML-DSA-65 key commitment. PQ signature blobs are `0x02 || sig(3309)`.
+4.2 `0x01 || r || s || v` is the ECDSA fallback. On Base today this is the only executable on-chain path: there is no ML-DSA precompile at `0x…Aa` and no fallback library is deployed. Clients default to `0x01`; `0x02` is reserved for a live verifier backend and MUST NOT be advertised as active until then.
 4.3 Signed digest: `keccak256(abi.encode(chainId, account, nonce, target, value, keccak256(data)))`; nonce increments per execution.
-4.4 Verification runs through `IPQVerifier`; ML-DSA-65 pk len 1952, sig len 3309.
+4.4 Verification runs through `IPQVerifier`; ML-DSA-65 pk len 1952, sig len 3309. `MLDSAVerifier` always checks key hash and lengths, then tries the precompile and a pluggable `fallbackLib`.
 
 ## 5 Privacy
 5.1 `announce(stealth, ephPubKey, viewTag, metadataHash)`, agents only.