@aqb-foundation/aqb-agent 1.0.1 → 1.0.3

package/mcp/server.mjs

@@ -1,37 +1,123 @@
 #!/usr/bin/env node
 // AQB MCP server (stdio JSON-RPC 2.0, no deps). Tools every agent can call.
-import { AqbAgent, discover, wellKnown, cardHash, keyHash } from "../client/aqb.mjs";
+import fs from "node:fs";
+import { parseUnits, formatUnits, formatEther } from "ethers";
+import { AqbAgent, discover, wellKnown, cardHash } from "../client/aqb.mjs";
+
+const regFile = JSON.parse(fs.readFileSync(new URL("../registry/agent-coin.json", import.meta.url), "utf8"));
+const TOKEN = process.env.AQB_TOKEN || regFile.contracts.token;
+const REGISTRY = process.env.AQB_REGISTRY || regFile.contracts.registry;
+const VERIFIER = process.env.AQB_VERIFIER || regFile.contracts.verifier;
+const PAIR = process.env.AQB_PAIR || regFile.markets?.[0]?.pair;
+const SALE = process.env.AQB_SALE || regFile.sale;
 
 const cfg = () => new AqbAgent({
-  rpc: process.env.AQB_RPC, chain: process.env.AQB_CHAIN || "base",
-  privateKey: process.env.AQB_KEY, token: process.env.AQB_TOKEN, registry: process.env.AQB_REGISTRY,
+  rpc: process.env.AQB_RPC || process.env.BASE_RPC,
+  chain: process.env.AQB_CHAIN || "base",
+  privateKey: process.env.AQB_KEY || process.env.PRIVATE_KEY,
+  token: TOKEN,
+  registry: REGISTRY,
 });
 
 const TOOLS = [
   { name: "aqb_discover", description: "Fetch AQB discovery doc from an agent host", inputSchema: { type: "object", properties: { host: { type: "string" } }, required: ["host"] } },
-  { name: "aqb_balance", description: "Get AQB and USDC balances (read-only)", inputSchema: { type: "object", properties: { address: { type: "string" } } } },
+  { name: "aqb_balance", description: "Get AQB and USDC balances for an address (read-only)", inputSchema: { type: "object", properties: { address: { type: "string" } } } },
   { name: "aqb_is_agent", description: "Check whether an address is a registered agent", inputSchema: { type: "object", properties: { address: { type: "string" } }, required: ["address"] } },
-  { name: "aqb_register", description: "Register this wallet as an agent with a card and ML-DSA public key", inputSchema: { type: "object", properties: { card: { type: "object" }, pubKey: { type: "string" } }, required: ["card", "pubKey"] } },
-  { name: "aqb_fund", description: "Mint AQB against USDC, 1:1 (usd in 6 decimals)", inputSchema: { type: "object", properties: { usd: { type: "string" } }, required: ["usd"] } },
-  { name: "aqb_pay", description: "Pay AQB to another agent", inputSchema: { type: "object", properties: { to: { type: "string" }, aqb: { type: "string" } }, required: ["to", "aqb"] } },
-  { name: "aqb_cash_out", description: "Redeem AQB for USDC, 1:1", inputSchema: { type: "object", properties: { aqb: { type: "string" } }, required: ["aqb"] } },
-  { name: "aqb_announce_stealth", description: "Publish a stealth address for a payer", inputSchema: { type: "object", properties: { ephPubKey: { type: "string" }, sharedSecret: { type: "string" }, metaHash: { type: "string" } }, required: ["ephPubKey", "sharedSecret"] } },
-  { name: "aqb_wellknown", description: "Generate your own /.well-known/agent-coin.json", inputSchema: { type: "object", properties: { token: { type: "string" }, registry: { type: "string" }, verifier: { type: "string" } } } },
+  { name: "aqb_quote", description: "Quote 1 AQB in USDC from the vault (1.0) and the Uniswap V2 pool", inputSchema: { type: "object", properties: { amount: { type: "string" }, pair: { type: "string" } } } },
+  { name: "aqb_register", description: "Register a PQSmartAccount as an agent (caller must be the account)", inputSchema: { type: "object", properties: { account: { type: "string" }, card: { type: "object" }, scheme: { type: "string", enum: ["ecdsa", "pq"] } }, required: ["account", "card"] } },
+  { name: "aqb_update_card", description: "Publish a new agent card hash from a PQSmartAccount", inputSchema: { type: "object", properties: { account: { type: "string" }, card: { type: "object" }, scheme: { type: "string", enum: ["ecdsa", "pq"] } }, required: ["account", "card"] } },
+  { name: "aqb_fund", description: "Mint AQB against USDC, 1:1 (usd in human units, e.g. 10.5)", inputSchema: { type: "object", properties: { usd: { type: "string" }, account: { type: "string" } }, required: ["usd"] } },
+  { name: "aqb_pay", description: "Pay AQB to another agent (amount in human units, e.g. 1.5)", inputSchema: { type: "object", properties: { to: { type: "string" }, aqb: { type: "string" }, account: { type: "string" } }, required: ["to", "aqb"] } },
+  { name: "aqb_redeem", description: "Redeem AQB for USDC, 1:1 (amount in human units)", inputSchema: { type: "object", properties: { aqb: { type: "string" }, account: { type: "string" } }, required: ["aqb"] } },
+  { name: "aqb_cash_out", description: "Alias for aqb_redeem", inputSchema: { type: "object", properties: { aqb: { type: "string" }, account: { type: "string" } }, required: ["aqb"] } },
+  { name: "aqb_announce_stealth", description: "Publish a stealth address for a payer from a PQSmartAccount", inputSchema: { type: "object", properties: { account: { type: "string" }, ephPubKey: { type: "string" }, sharedSecret: { type: "string" }, metaHash: { type: "string" } }, required: ["account", "ephPubKey", "sharedSecret"] } },
+  { name: "aqb_wellknown", description: "Generate your own /.well-known/agent-coin.json", inputSchema: { type: "object", properties: { token: { type: "string" }, registry: { type: "string" }, verifier: { type: "string" }, pool: { type: "string" } } } },
 ];
 
+function requireArg(a, name) {
+  if (!a[name]) throw new Error(`missing argument: ${name}`);
+  return a[name];
+}
+
+const addr = (x) => (typeof x === "string" ? x.toLowerCase() : x);
+
+function accountOf(c, a) {
+  return a.account ? c.account(addr(a.account)) : null;
+}
+
 async function run(name, a) {
   const c = cfg();
   switch (name) {
-    case "aqb_discover": return await discover(a.host);
-    case "aqb_balance": return { aqb: String(await c.balance(a.address)).padStart(1), usdc: String(await c.usdBalance()) };
-    case "aqb_is_agent": return { isAgent: await c.isAgent(a.address) };
-    case "aqb_register": return { tx: await c.register(a.card, a.pubKey), cardHash: cardHash(a.card), pqKeyHash: keyHash(a.pubKey) };
-    case "aqb_fund": return { tx: await c.fund(BigInt(a.usd)) };
-    case "aqb_pay": return { tx: await c.pay(a.to, BigInt(a.aqb)) };
-    case "aqb_cash_out": return { tx: await c.cashOut(BigInt(a.aqb)) };
-    case "aqb_announce_stealth": return { tx: await c.announce(a.ephPubKey, a.sharedSecret, a.metaHash) };
-    case "aqb_wellknown": return wellKnown({ token: a.token || process.env.AQB_TOKEN, registry: a.registry || process.env.AQB_REGISTRY, verifier: process.env.AQB_VERIFIER, chainId: Number(process.env.AQB_CHAIN_ID || 8453) });
-    default: throw new Error(`unknown tool ${name}`);
+    case "aqb_discover":
+      return await discover(requireArg(a, "host"));
+    case "aqb_balance": {
+      const address = addr(a.address || c.signer?.address);
+      if (!address) throw new Error("address required");
+      return {
+        address,
+        aqb: formatEther(await c.balance(address)),
+        usdc: formatUnits(await c.usdBalance(address), 6),
+      };
+    }
+    case "aqb_is_agent":
+      return { isAgent: await c.isAgent(addr(requireArg(a, "address"))) };
+    case "aqb_quote": {
+      const amount = parseUnits(a.amount || "1", 18);
+      const q = await c.poolQuote(addr(a.pair || PAIR), amount);
+      return {
+        pool: addr(a.pair || PAIR),
+        aqb: formatEther(amount),
+        vaultUSDC: formatUnits(amount / 10n ** 12n, 6),
+        poolUSDC: formatUnits(q.usdc, 6),
+        reserves: { aqb: formatEther(q.reserves.aqb), usdc: formatUnits(q.reserves.usdc, 6) },
+      };
+    }
+    case "aqb_register": {
+      const account = addr(requireArg(a, "account"));
+      const tx = await c.registerViaAccount(account, requireArg(a, "card"), a.scheme || "ecdsa");
+      return { tx, account, cardHash: cardHash(a.card) };
+    }
+    case "aqb_update_card": {
+      const account = addr(requireArg(a, "account"));
+      const tx = await c.updateCardFromAccount(account, requireArg(a, "card"), a.scheme || "ecdsa");
+      return { tx, account, cardHash: cardHash(a.card) };
+    }
+    case "aqb_fund": {
+      const usd = parseUnits(requireArg(a, "usd"), 6);
+      const acc = accountOf(c, a);
+      return { tx: acc ? await c.fundFromAccount(acc, usd) : await c.fund(usd), usdc: formatUnits(usd, 6) };
+    }
+    case "aqb_pay": {
+      const aqb = parseUnits(requireArg(a, "aqb"), 18);
+      const acc = accountOf(c, a);
+      const to = addr(requireArg(a, "to")); return { tx: acc ? await c.payFromAccount(acc, to, aqb) : await c.pay(to, aqb), aqb: formatEther(aqb) };
+    }
+    case "aqb_redeem":
+    case "aqb_cash_out": {
+      const aqb = parseUnits(requireArg(a, "aqb"), 18);
+      const acc = accountOf(c, a);
+      return { tx: acc ? await c.redeemFromAccount(acc, aqb) : await c.cashOut(aqb), aqb: formatEther(aqb) };
+    }
+    case "aqb_announce_stealth": {
+      const tx = await c.announceFromAccount(
+        c.account(addr(requireArg(a, "account"))),
+        requireArg(a, "ephPubKey"),
+        requireArg(a, "sharedSecret"),
+        a.metaHash || "0x" + "00".repeat(32)
+      );
+      return { tx };
+    }
+    case "aqb_wellknown":
+      return wellKnown({
+        token: a.token || TOKEN,
+        registry: a.registry || REGISTRY,
+        verifier: a.verifier || VERIFIER,
+        chainId: Number(process.env.AQB_CHAIN_ID || 8453),
+        pool: a.pool || PAIR,
+        sale: SALE,
+      });
+    default:
+      throw new Error(`unknown tool ${name}`);
   }
 }
 
@@ -47,14 +133,21 @@ process.stdin.on("data", async (chunk) => {
     let m;
     try { m = JSON.parse(line); } catch { continue; }
     try {
-      if (m.method === "initialize") send({ jsonrpc: "2.0", id: m.id, result: { protocolVersion: "2024-11-05", capabilities: { tools: {} }, serverInfo: { name: "aqb", version: "1.0.0" } } });
-      else if (m.method === "tools/list") send({ jsonrpc: "2.0", id: m.id, result: { tools: TOOLS } });
-      else if (m.method === "tools/call") {
+      if (m.method === "initialize") {
+        send({ jsonrpc: "2.0", id: m.id, result: { protocolVersion: "2024-11-05", capabilities: { tools: {} }, serverInfo: { name: "aqb", version: "1.0.2" } } });
+      } else if (m.method === "tools/list") {
+        send({ jsonrpc: "2.0", id: m.id, result: { tools: TOOLS } });
+      } else if (m.method === "tools/call") {
         const out = await run(m.params.name, m.params.arguments || {});
         send({ jsonrpc: "2.0", id: m.id, result: { content: [{ type: "text", text: JSON.stringify(out) }] } });
-      } else if (m.id !== undefined) send({ jsonrpc: "2.0", id: m.id, result: {} });
+      } else if (m.id !== undefined) {
+        send({ jsonrpc: "2.0", id: m.id, result: {} });
+      }
     } catch (e) {
-      send({ jsonrpc: "2.0", id: m.id, error: { code: -32000, message: String(e.message || e) } });
+      const msg = String(e.shortMessage || e.message || e);
+      if (m.id !== undefined) {
+        send({ jsonrpc: "2.0", id: m.id, result: { content: [{ type: "text", text: msg }], isError: true } });
+      }
     }
   }
 });

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@aqb-foundation/aqb-agent",
-  "version": "1.0.1",
-  "description": "AQB — agent-only, USD-pegged, post-quantum credit token on Base",
-  "main": "index.js",
+  "version": "1.0.3",
+  "description": "AQB — agent-only, USD-pegged, post-quantum credit token on Base. SDK, CLI and MCP server.",
+  "main": "client/aqb.mjs",
   "directories": {
     "doc": "docs",
     "test": "test"
@@ -10,43 +10,73 @@
   "scripts": {
     "compile": "node compile.mjs",
     "test": "node compile.mjs && node test/pq.mjs && node test/e2e.mjs",
-    "deploy": "node deploy.mjs"
+    "mcp": "node mcp/server.mjs"
   },
   "keywords": [
     "ai-agents",
+    "agent-payments",
     "x402",
     "post-quantum",
     "ml-dsa",
     "base",
-    "stablecoin"
+    "stablecoin",
+    "mcp",
+    "mcp-server"
   ],
-  "author": "",
-  "license": "ISC",
+  "author": "AgentQubit",
+  "license": "MIT",
   "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
-    "@aqb-foundation/aqb-agent": "^1.0.0",
     "@noble/post-quantum": "^0.6.0",
     "ethers": "^6.17.0"
   },
+  "devDependencies": {
+    "@ethereumjs/common": "^10.1.3",
+    "@ethereumjs/statemanager": "^10.1.3",
+    "@ethereumjs/util": "^10.1.3",
+    "@ethereumjs/vm": "^10.1.3",
+    "solc": "0.8.24"
+  },
   "bin": {
+    "aqb-agent": "index.js",
     "aqb-mcp": "mcp/server.mjs"
   },
   "exports": {
-    "./client": "./client/aqb.mjs"
+    ".": "./client/aqb.mjs",
+    "./client": "./client/aqb.mjs",
+    "./pq": "./pq/pq.mjs",
+    "./mcp": "./mcp/server.mjs"
   },
   "files": [
+    "index.js",
     "client",
     "pq",
     "mcp",
     "registry",
     "docs",
     "artifacts",
+    "contracts",
+    "test",
+    "vendor",
+    "pq-deployment.json",
+    "compile.mjs",
     "WHITEPAPER.md",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/yss787976-ai/agent-coin.git"
   },
-  "mcpName": "io.github.yss787976-ai/aqb-agent"
+  "homepage": "https://agentqubit.pages.dev",
+  "bugs": {
+    "url": "https://github.com/yss787976-ai/agent-coin/issues"
+  },
+  "mcpName": "io.github.yss787976-ai/aqb-agent",
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/pq-deployment.json

@@ -0,0 +1,14 @@
+{
+  "factory": "0x9961a96B2F77B6D86d8a60607A90b3cAeECBe197",
+  "skaleVerifier": "0xa11eE20877a7618ff417f79A026186A9253C0b30",
+  "adapter": "0xeEbccD88DDb596860b33D0285294fF53cd83506B",
+  "registerA": "0x7235b1d3f2331e238eefdef1414abc01687bfc90339122c3a1195db2a195b3bf",
+  "registerT": "0x0c0ab4b55823c27aaec046e88b893fa8a4302f7bfbe191d676801594f2d34514",
+  "setFallbackLib": "0x43d2cf0fe5611cc7539ce5b46bf2249ef398ea7ca7827c910c43c83d849d1403",
+  "verifyDigest": "0x6fb181b661b9a10e86d2a34cd3e4c3862f9af8770c2aa68f689bfc649c0588a7",
+  "verifyDirect": true,
+  "verifyViaAqb": true,
+  "execute": "0xe7bed9f3b530e447ea92a19fcab7cee4082a07a17c35834f02237d9ec86a5fe5",
+  "executeGas": "3966579",
+  "nonceAfter": "198"
+}

package/registry/agent-coin.json

@@ -17,7 +17,17 @@
   "pq": {
     "signature": "ML-DSA-65",
     "kem": "ML-KEM-768",
-    "standard": "FIPS-204"
+    "standard": "FIPS-204",
+    "onchain": {
+      "mode": "0x02",
+      "aqbVerifier": "0x53d34e4Ffd0bd984f8b92561f9e2B7D3EDdbE60d",
+      "adapter": "0xeEbccD88DDb596860b33D0285294fF53cd83506B",
+      "verifier": "0xa11eE20877a7618ff417f79A026186A9253C0b30",
+      "factory": "0x9961a96B2F77B6D86d8a60607A90b3cAeECBe197",
+      "gas": 3966579,
+      "audited": false,
+      "source": "skalenetwork/mldsa-solidity"
+    }
   },
   "privacy": {
     "amounts": "public",
@@ -26,19 +36,22 @@
   },
   "contracts": {
     "token": "0x2C54F202B565086B6d8D2226Edb67AC3E14C39d1",
+    "vault": "0x2C54F202B565086B6d8D2226Edb67AC3E14C39d1",
     "registry": "0xAa964f6ea767f0D709b268abBFdd8B6C2Beef3eB",
-    "verifier": "0x53d34e4Ffd0bd984f8b92561f9e2B7D3EDdbE60d"
+    "verifier": "0x53d34e4Ffd0bd984f8b92561f9e2B7D3EDdbE60d",
+    "pool": "0xF61Cb078f87425933741Dd7d02F5779c030dB1A6",
+    "sale": "0xeDBD6B860c37C411aeeA513cbc0656e3135f59c1"
   },
   "discovery": {
-    "wellKnown": "/.well-known/agent-coin.json",
-    "llms": "/llms.txt",
+    "wellKnown": "https://agentqubit.pages.dev/.well-known/agent-coin.json",
+    "llms": "https://agentqubit.pages.dev/llms.txt",
     "dns": "_aqb.<host> TXT v=aqb1",
-    "npm": "aqb-agent",
+    "npm": "@aqb-foundation/aqb-agent",
     "hosted": {
-      "agentCoin": "https://yss787976-ai.github.io/agent-coin/.well-known/agent-coin.json",
-      "agentCard": "https://yss787976-ai.github.io/agent-coin/.well-known/agent-card.json",
-      "llms": "https://yss787976-ai.github.io/agent-coin/llms.txt",
-      "cardHash": "0x5fba6b2fca551dcfb840406204a784c5d261225f5b8fb3b95d2593dae64fc48e",
+      "agentCoin": "https://agentqubit.pages.dev/.well-known/agent-coin.json",
+      "agentCard": "https://agentqubit.pages.dev/.well-known/agent-card.json",
+      "llms": "https://agentqubit.pages.dev/llms.txt",
+      "cardHash": "0x3294204f00383bc8f28a0bc52142ceb0bfe7197dd46f68998403fe9d234c1097",
       "mirror": "https://cdn.jsdelivr.net/gh/yss787976-ai/agent-coin@main/.well-known/agent-coin.json"
     }
   },
@@ -62,8 +75,10 @@
       "token0": "0x2C54F202B565086B6d8D2226Edb67AC3E14C39d1",
       "token1": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
       "liquidity": {
-        "aqb": "259400000000000000000",
-        "usdc": "259400000"
+        "aqb": "241523635507336690440",
+        "usdc": "241523633",
+        "priceUSDC": "1.0000",
+        "asOf": "2026-11-13"
       }
     }
   ],

package/registry/llms.txt

@@ -1 +1 @@
-> AQB — AgentQubit: agent-only, USD-pegged (1:1 USDC), post-quantum (ML-DSA-65) credit token on Base. 900B cap, no oracle, stealth payers. Human UI not required. Discover: /.well-known/agent-coin.json, DNS TXT _aqb, npm aqb-agent. Spec: docs/SPEC.md
+> AQB — AgentQubit: agent-only, USD-pegged (1:1 USDC), post-quantum (ML-DSA-65) credit token on Base. 900B cap, no oracle, stealth payers. Human UI not required. Discover: /.well-known/agent-coin.json, DNS TXT _aqb, npm @aqb-foundation/aqb-agent. Spec: docs/SPEC.md

package/test/e2e.mjs

@@ -0,0 +1,100 @@
+// E2E invariant test on local EVM. Build first: node compile.mjs
+import { deploy, exec, me, b32 } from "./evm.mjs";
+import { newIdentity } from "../pq/pq.mjs";
+
+let fails = 0;
+const ok = (c, m) => { console.log((c ? "PASS " : "FAIL ") + m); if (!c) fails++; };
+const ALLOT = 5n * 10n ** 18n; // scaled-down founder allotment for the test
+
+const idA = newIdentity(), pubA = "0x" + Buffer.from(idA.publicKey).toString("hex");
+const idB = newIdentity(), pubB = "0x" + Buffer.from(idB.publicKey).toString("hex");
+const keyA = idA.keyHash, keyB = idB.keyHash;
+
+const usdc = await deploy("MockUSDC");
+const verifier = await deploy("MockVerifier");
+const registry = await deploy("AgentRegistry");
+const token = await deploy("AgentQuantumCredit", [usdc.hex, registry.hex, me.toString()]);
+const accA = await deploy("PQSmartAccount", [verifier.hex, me.toString(), pubA]); // founder
+const accB = await deploy("PQSmartAccount", [verifier.hex, me.toString(), pubB]); // buyer
+
+ok(await registry.read("isAgent", accA.hex) === false, "not agent before register");
+let r = await registry.send("register", keyA, b32("0x78"));
+ok(r.status === 0, "EOA registration rejected");
+await exec(accA, registry.hex, registry.iface.encodeFunctionData("register", [keyA, b32("0xca11")]), "pq", idA);
+ok(await registry.read("isAgent", accA.hex) === true, "agent A registered (PQ sig)");
+r = await exec(accB, registry.hex, registry.iface.encodeFunctionData("register", [keyB, b32("0xca12")]), "pq", idB);
+ok(r.status === 1, "agent B registered");
+
+// ---- genesis allotment: minted first, sold first, 1:1 into the vault
+await token.send("genesisMint", accA.hex, ALLOT);
+ok(await token.read("balanceOf", accA.hex) === ALLOT, "founder allotment minted first");
+ok(await token.read("genesisSupply") === ALLOT, "genesisSupply recorded");
+ok(await token.read("backedSupply") === 0n, "unsold allotment is not counted as backed");
+const sale = await deploy("GenesisSale", [token.hex, usdc.hex, accA.hex, ALLOT]);
+await token.send("setSale", sale.hex);
+ok(await token.read("backedSupply") === 0n, "sale escrow does not inflate backed supply");
+
+r = await token.send("mint", 1n);
+ok(r.status === 0, "public mint blocked while the genesis sale is open");
+
+await usdc.send("mint", accB.hex, 10_000_000n);
+await exec(accB, usdc.hex, usdc.iface.encodeFunctionData("approve", [sale.hex, 2n ** 200n]));
+await exec(accA, token.hex, token.iface.encodeFunctionData("approve", [sale.hex, ALLOT]));
+await exec(accB, sale.hex, sale.iface.encodeFunctionData("buy", [3_000_000n]));
+ok(await token.read("balanceOf", accB.hex) === 3n * 10n ** 18n, "buyer received 3 AQB for 3 USD");
+ok(await usdc.read("balanceOf", token.hex) === 3_000_000n, "buyer dollars escrowed in the vault");
+ok(await token.read("backedSupply") === 3n * 10n ** 18n, "sold coins now back the peg");
+ok(await token.read("collateralRatio") === 10n ** 18n, "ratio == 1e18 for live coins");
+ok(await sale.read("remaining") === 2n * 10n ** 18n, "allotment decreasing");
+
+r = await exec(accB, sale.hex, sale.iface.encodeFunctionData("buy", [5_000_000n]));
+ok(r.status === 0, "over-allotment buy reverts");
+await exec(accB, sale.hex, sale.iface.encodeFunctionData("buy", [2_000_000n]));
+ok(await sale.read("closed") === true, "sale closes when the allotment is exhausted");
+ok(await token.read("saleOpen") === false, "public mint re-opened after the allotment sold out");
+
+// ---- public mint against USDC
+await usdc.send("mint", accA.hex, 100_000_000n);
+await exec(accA, usdc.hex, usdc.iface.encodeFunctionData("approve", [token.hex, 2n ** 200n]));
+r = await token.send("mint", 1n);
+ok(r.status === 0, "EOA mint rejected (not an agent)");
+await exec(accA, token.hex, token.iface.encodeFunctionData("mint", [10_000_000n]));
+ok(await token.read("balanceOf", accA.hex) === 10n ** 19n, "10 USD -> 10 AQB for founder (allotment spent)");
+ok(await token.read("collateralRatio") === 10n ** 18n, "ratio stays 1e18");
+ok(await token.read("backedSupply") === await token.read("totalSupply"), "everything is sold, all supply backed");
+ok(await token.read("MAX_SUPPLY") === 900_000_000_000n * 10n ** 18n, "cap == 900e9 AQB");
+
+// ---- transfer gates
+await exec(accA, token.hex, token.iface.encodeFunctionData("transfer", [accB.hex, 3n * 10n ** 18n]));
+ok(await token.read("balanceOf", accB.hex) === 8n * 10n ** 18n, "transfer to agent ok");
+r = await exec(accA, token.hex, token.iface.encodeFunctionData("transfer", [me.toString(), 10n ** 18n]));
+ok(r.status === 0, "transfer to plain EOA blocked");
+await token.send("setPool", me.toString(), true);
+r = await exec(accA, token.hex, token.iface.encodeFunctionData("transfer", [me.toString(), 10n ** 18n]));
+ok(r.status === 1, "transfer to whitelisted pool allowed");
+
+// ---- redeem
+r = await exec(accA, token.hex, token.iface.encodeFunctionData("redeem", [1n]));
+ok(r.status === 0, "redeem below 1e12 rejected");
+const before = await usdc.read("balanceOf", accA.hex);
+await exec(accA, token.hex, token.iface.encodeFunctionData("redeem", [2n * 10n ** 18n]));
+ok(await usdc.read("balanceOf", accA.hex) - before === 2_000_000n, "2 AQB -> 2 USD");
+ok(await token.read("collateralRatio") === 10n ** 18n, "ratio stays 1e18 after redeem");
+
+// ---- stealth + card
+const eph = "0x" + "7a".repeat(1088);
+r = await exec(accA, registry.hex, registry.iface.encodeFunctionData("announce", ["0x" + "5b".repeat(20), eph, "0xa7", "0x" + "00".repeat(32)]));
+ok(r.status === 1, "agent can announce a stealth address");
+r = await registry.send("announce", "0x" + "5b".repeat(20), eph, "0xa7", "0x" + "00".repeat(32));
+ok(r.status === 0, "non-agent cannot announce");
+r = await exec(accA, registry.hex, registry.iface.encodeFunctionData("updateCard", [b32("0xca99")]));
+ok(r.status === 1, "agent can publish a new card hash");
+
+// ---- signature authority
+const d = await accA.read("digest", usdc.hex, 0n, "0x", await accA.read("nonce"));
+r = await accA.send("execute", usdc.hex, 0n, "0x", "0x01" + "11".repeat(32) + "22".repeat(32) + "1b");
+ok(r.status === 0, "wrong ECDSA sig rejected");
+ok(await registry.read("agentCount") === 2n, "agentCount == 2");
+
+console.log(fails ? `E2E FAILED (${fails})` : "E2E OK");
+process.exit(fails ? 1 : 0);

package/test/evm.mjs

@@ -0,0 +1,69 @@
+// Local EVM harness (ethereumjs v10). No JSON-RPC, no hardhat.
+import { createVM } from "@ethereumjs/vm";
+import { MerkleStateManager } from "@ethereumjs/statemanager";
+import { Common, Mainnet, Hardfork } from "@ethereumjs/common";
+import { Address, Account, hexToBytes, bytesToHex, createAddressFromString } from "@ethereumjs/util";
+import { Wallet, AbiCoder, keccak256, solidityPacked, Contract } from "ethers";
+import fs from "node:fs";
+import { signDigest } from "../pq/pq.mjs";
+
+const coder = AbiCoder.defaultAbiCoder();
+const common = new Common({ chain: Mainnet, hardfork: Hardfork.Cancun });
+export const vm = await createVM({ common });
+const sm = vm.stateManager;
+
+export const PK = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
+export const signer = new Wallet(PK);
+export const me = createAddressFromString(signer.address.toLowerCase());
+
+await sm.putAccount(me, new Account(0n, 10n ** 24n));
+
+export const art = (n) => JSON.parse(fs.readFileSync(`artifacts/${n}.json`, "utf8"));
+
+export async function call(from, to, data, value = 0n) {
+  const r = await vm.evm.runCall({
+    caller: from, origin: from, to, data: hexToBytes(data), value, gasLimit: 30_000_000n,
+  });
+  return { status: r.execResult.exceptionError ? 0 : 1, ret: bytesToHex(r.execResult.returnValue), err: r.execResult.exceptionError?.error, logs: r.execResult.logs };
+}
+
+export async function deploy(name, args = []) {
+  const a = art(name);
+  const data = a.bytecode + coder.encode(a.ctorTypes || guessCtor(a.abi), args).slice(2);
+  const r = await vm.evm.runCall({ caller: me, origin: me, data: hexToBytes(data), gasLimit: 30_000_000n });
+  if (r.execResult.exceptionError) throw new Error(`${name} deploy: ${r.execResult.exceptionError.error}`);
+  const addr = r.createdAddress;
+  return {
+    addr,
+    hex: bytesToHex(addr.bytes),
+    iface: new Contract(bytesToHex(addr.bytes), a.abi).interface,
+    abi: a.abi,
+    send: (fn, ...a2) => call(me, addr, new Contract(bytesToHex(addr.bytes), a.abi).interface.encodeFunctionData(fn, a2)),
+    read: async (fn, ...a2) => decode(a.abi, fn, (await call(me, addr, new Contract(bytesToHex(addr.bytes), a.abi).interface.encodeFunctionData(fn, a2))).ret),
+  };
+}
+
+function guessCtor(abi) {
+  const c = abi.find((x) => x.type === "constructor");
+  return (c?.inputs || []).map((i) => i.type);
+}
+
+export function decode(abi, fn, hex) {
+  const f = abi.find((x) => x.type === "function" && x.name === fn);
+  const vals = coder.decode(f.outputs.map((o) => o.type), hex);
+  return vals.length === 1 ? vals[0] : vals;
+}
+
+export const b32 = (s) => keccak256(s);
+
+export async function exec(acc, targetHex, data, scheme = "ecdsa", identity) {
+  const nonce = await acc.read("nonce");
+  const digest = await acc.read("digest", targetHex, 0n, data, nonce);
+  let sig;
+  if (scheme === "pq") sig = signDigest(identity, digest);
+  else {
+    const s = signer.signingKey.sign(digest);
+    sig = "0x01" + s.r.slice(2) + s.s.slice(2) + s.v.toString(16).padStart(2, "0");
+  }
+  return acc.send("execute", targetHex, 0n, data, sig);
+}

package/test/local.mjs

@@ -0,0 +1,86 @@
+// End-to-end invariant test on a local EVM. Run: node test/local.mjs
+import { JsonRpcProvider, Wallet, ContractFactory, Contract, keccak256, AbiCoder, solidityPacked } from "ethers";
+import fs from "node:fs";
+
+const p = new JsonRpcProvider("http://127.0.0.1:8545");
+const signer = new Wallet("0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80", p);
+const art = (n) => JSON.parse(fs.readFileSync(`artifacts/${n}.json`, "utf8"));
+const dep = async (n, args) => {
+  const c = await new ContractFactory(art(n).abi, art(n).bytecode, signer).deploy(...args);
+  await c.waitForDeployment();
+  return c;
+};
+let fails = 0;
+const ok = (c, m) => { console.log((c ? "PASS " : "FAIL ") + m); if (!c) fails++; };
+
+const pubA = solidityPacked(["bytes32"], [keccak256("0x01")]).concat("00".repeat(1904));
+const pubB = solidityPacked(["bytes32"], [keccak256("0x02")]).concat("00".repeat(1904));
+const keyA = keccak256(pubA), keyB = keccak256(pubB);
+
+const usdc = await dep("MockUSDC", []);
+const verifier = await dep("MockVerifier", []);
+const registry = await dep("AgentRegistry", []);
+const token = await dep("AgentQuantumCredit", [await usdc.getAddress(), await registry.getAddress(), signer.address]);
+const accA = await dep("PQSmartAccount", [await verifier.getAddress(), signer.address, pubA]);
+const accB = await dep("PQSmartAccount", [await verifier.getAddress(), signer.address, pubB]);
+const A = await accA.getAddress(), B = await accB.getAddress();
+
+async function exec(acc, target, data, scheme = "ecdsa") {
+  const addr = await acc.getAddress();
+  const nonce = await acc.nonce();
+  const digest = await acc.digest(target, 0n, data, nonce);
+  let sig;
+  if (scheme === "pq") {
+    sig = "0x02" + "ab".repeat(3309);
+  } else {
+    const s = signer.signingKey.sign(digest);
+    sig = "0x01" + s.r.slice(2) + s.s.slice(2) + s.v.toString(16).padStart(2, "0");
+  }
+  return acc.execute(target, 0n, data, sig);
+}
+
+// registration requires a PQ account bound to the announced key
+const c = (n, a) => new Contract(n, a).interface.encodeFunctionData;
+try {
+  await exec(accA, await registry.getAddress(), registry.interface.encodeFunctionData("register", [keyA, keccak256("0xaaaa")]), "pq");
+  ok(await registry.isAgent(A), "agent A registered via PQ sig");
+} catch (e) { ok(false, "agent A registered via PQ sig: " + e.shortMessage); }
+await exec(accB, await registry.getAddress(), registry.interface.encodeFunctionData("register", [keyB, keccak256("0xbbbb")]));
+
+await usdc.mint(A, 100_000_000n); // 100 USD
+await exec(accA, await usdc.getAddress(), usdc.interface.encodeFunctionData("approve", [await token.getAddress(), 2n ** 200n]));
+
+// EOA cannot mint
+try { await (await token.connect(signer).mint(1n)).wait(); ok(false, "EOA mint blocked"); }
+catch { ok(true, "EOA mint blocked"); }
+
+await exec(accA, await token.getAddress(), token.interface.encodeFunctionData("mint", [10_000_000n]));
+ok(await token.balanceOf(A) === 10n ** 19n, "minted 10 AQB for 10 USD");
+ok(await token.collateralRatio() === 10n ** 18n, "ratio == 1e18");
+
+// transfer to agent OK, to EOA blocked
+await exec(accA, await token.getAddress(), token.interface.encodeFunctionData("transfer", [B, 3n * 10n ** 18n]));
+ok(await token.balanceOf(B) === 3n * 10n ** 18n, "transfer to agent ok");
+try { await exec(accA, await token.getAddress(), token.interface.encodeFunctionData("transfer", [signer.address, 1n])); ok(false, "transfer to EOA blocked"); }
+catch { ok(true, "transfer to EOA blocked"); }
+await token.connect(signer).setPool(signer.address, true);
+await exec(accA, await token.getAddress(), token.interface.encodeFunctionData("transfer", [signer.address, 1n]));
+ok(true, "transfer to whitelisted pool ok");
+
+// redeem peg, fractional reverts
+try { await exec(accA, await token.getAddress(), token.interface.encodeFunctionData("redeem", [1n])); ok(false, "redeem of <1e12 reverts"); }
+catch { ok(true, "redeem of <1e12 reverts"); }
+const usdBefore = await usdc.balanceOf(A);
+await exec(accA, await token.getAddress(), token.interface.encodeFunctionData("redeem", [2n * 10n ** 18n]));
+ok(await usdc.balanceOf(A) - usdBefore === 2_000_000n, "redeem paid 2 USD");
+ok(await token.collateralRatio() === 10n ** 18n, "ratio == 1e18 after redeem");
+
+ok(await token.MAX_SUPPLY() === 900_000_000_000n * 10n ** 18n, "cap == 900e9");
+ok(await registry.agentCount() === 2n, "agentCount == 2");
+
+// ecdsa fallback authority works
+await exec(accA, await usdc.getAddress(), usdc.interface.encodeFunctionData("approve", [await token.getAddress(), 0n]));
+ok(true, "ecdsa fallback path ok");
+
+console.log(fails ? `SMOKE FAILED (${fails})` : "SMOKE OK");
+process.exit(fails ? 1 : 0);