@aqb-foundation/aqb-agent 1.0.0 → 1.0.2

package/LICENSE

@@ -1,21 +1,9 @@
 MIT License
 
-Copyright (c) 2026 AQB
+Copyright (c) 2026 AgentQubit
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,21 +1,36 @@
 # AgentQubit (AQB)
 
-USD-pegged, agent-only credit token. Post-quantum signed. Base L2. 900B hard cap. 1 AQB = 1 real USDC-backed dollar, always.
+USD-pegged, agent-only credit token. Post-quantum identity. Base L2. 900B hard cap. 1 AQB = 1 real USDC-backed dollar for circulating supply.
+
+Telegram: https://t.me/agentqubit  |  X: https://x.com/yss6060
 
 ## Why agents
-Card rails need humans. ECDSA wallets die to Shor. AQB gives: ML-DSA identity, sub-cent settlement, self-discovery, stealth payers.
+Card rails need humans. ECDSA wallets die to Shor. AQB gives: ML-DSA identity, sub-cent settlement, self-discovery, stealth payers, and a vault that redeems 1:1 in USDC.
 
 ## Discovery (canonical)
 
-- https://cdn.jsdelivr.net/gh/yss787976-ai/agent-coin@main/.well-known/agent-coin.json
-- https://cdn.jsdelivr.net/gh/yss787976-ai/agent-coin@main/.well-known/agent-card.json (cardHash committed on chain)
-- https://cdn.jsdelivr.net/gh/yss787976-ai/agent-coin@main/llms.txt
+- https://agentqubit.pages.dev/.well-known/agent-coin.json
+- https://agentqubit.pages.dev/.well-known/agent-card.json (cardHash committed on chain)
+- https://agentqubit.pages.dev/llms.txt
+- https://agentqubit.pages.dev/agents.json
+
+Install: `npm i @aqb-foundation/aqb-agent`
 
-Package: `@yss787976-ai/aqb-agent` on npm.pkg.github.com
+## CLI
+
+```bash
+npx @aqb-foundation/aqb-agent --help
+npx @aqb-foundation/aqb-agent balance 0xAGENT
+npx @aqb-foundation/aqb-agent quote
+npx @aqb-foundation/aqb-agent pay --to 0xAGENT --amount 0.25
+npx @aqb-foundation/aqb-agent redeem --amount 10
+npx @aqb-foundation/aqb-agent deploy-account
+npx @aqb-foundation/aqb-agent register --account 0xACCOUNT --name ocr --skill "OCR batch" --endpoint https://agent.example/a2a
+```
 
 ## Verification
 
-All deployed contracts are source-verified on BaseScan (MIT license): token, registry, verifier, sale, account � see `registry/agent-coin.json`.
+All deployed contracts are source-verified on BaseScan (MIT): token, registry, verifier, sale, account — see `registry/agent-coin.json`.
 
 ## Read first
 - Spec (normative): [docs/SPEC.md](docs/SPEC.md)
@@ -27,21 +42,21 @@ All deployed contracts are source-verified on BaseScan (MIT license): token, reg
 
 ## Live on Base mainnet (chainId 8453)
 
-- Token **$AQB**: https://basescan.org/token/0x2C54F202B565086B6d8D2226Edb67AC3E14C39d1
+- Token / vault **$AQB**: https://basescan.org/token/0x2C54F202B565086B6d8D2226Edb67AC3E14C39d1
 - Genesis sale (74B @ $1): https://basescan.org/address/0xeDBD6B860c37C411aeeA513cbc0656e3135f59c1
 - Registry: https://basescan.org/address/0xAa964f6ea767f0D709b268abBFdd8B6C2Beef3eB
-- Founder wallet: 0x9eA52810f31768b1886cba9eAf917F4152f53042
+- Founder account: 0x9eA52810f31768b1886cba9eAf917F4152f53042
 - Trading pair (AQB/USDC): https://basescan.org/address/0xF61Cb078f87425933741Dd7d02F5779c030dB1A6
 - Deployed: 2026-11-11T18:45:48.901Z
 
 ## Contracts
 - `AgentQuantumCredit` — ERC-20, 18dp, cap 900e9, mint/redeem 1:1 USDC, agent-gated transfers
 - `AgentRegistry` — PQ-key registration + stealth announcer
-- `MLDSAVerifier` — FIPS 204 verify (precompile path + lib fallback)
-- `PQSmartAccount` — account whose authority is a PQ key; ECDSA only fallback
+- `MLDSAVerifier` — FIPS 204 verify shell (precompile path + pluggable library fallback)
+- `PQSmartAccount` — account whose identity is a PQ key; ECDSA only fallback for execution
 
 ## Build and test
-```
+```bash
 npm i
 node compile.mjs
 node test/pq.mjs      # real ML-DSA-65 + ML-KEM-768
@@ -50,29 +65,62 @@ node test/e2e.mjs     # peg, gates, cap, transfer rules
 
 ## Use as an agent (SDK)
 ```js
-import { AqbAgent, discover } from "aqb-agent/client";
-const d = await discover("agent.example");
-const me = new AqbAgent({ chain: "base", privateKey: process.env.PK, token: d.token, registry: d.registry });
+import { AqbAgent, discover } from "@aqb-foundation/aqb-agent/client";
+const d = await discover("agentqubit.pages.dev");
+const me = new AqbAgent({ chain: "base", privateKey: process.env.AQB_KEY, token: d.token, registry: d.registry });
 if (!(await me.isAgent(target))) throw new Error("not an agent");
 await me.pay(target, 25n * 10n ** 18n);
 ```
 Buying is only ever with real dollars: `await me.fund(10_000_000n)` pulls 10 USDC and mints 10 AQB.
 
+From a PQ account:
+```js
+await me.payFromAccount(me.account("0xACCOUNT"), target, 25n * 10n ** 18n);
+await me.registerFromAccount(me.account("0xACCOUNT"), card);
+```
+
 ## Use as an MCP server
 ```json
-{ "mcpServers": { "aqb": { "command": "node", "args": ["mcp/server.mjs"],
-  "env": { "AQB_CHAIN": "base", "AQB_TOKEN": "0x…", "AQB_REGISTRY": "0x…", "AQB_KEY": "0x…" } } } }
+{ "mcpServers": { "aqb": { "command": "npx", "args": ["-y", "@aqb-foundation/aqb-agent", "mcp"],
+  "env": { "AQB_KEY": "0x…" } } } }
 ```
-Tools: `aqb_discover`, `aqb_is_agent`, `aqb_balance`, `aqb_register`, `aqb_fund`, `aqb_pay`, `aqb_cash_out`, `aqb_announce_stealth`, `aqb_wellknown`.
+Tools: `aqb_discover`, `aqb_balance`, `aqb_is_agent`, `aqb_quote`, `aqb_register`, `aqb_update_card`, `aqb_fund`, `aqb_pay`, `aqb_redeem`, `aqb_cash_out`, `aqb_announce_stealth`, `aqb_wellknown`.
 
 ## Post-quantum keys
-Real ML-DSA-65 + ML-KEM-768 live in `pq/pq.mjs` (noble primitives). The account, not an EOA, is the authority: `registerFromAccount`, `fundFromAccount`, `payFromAccount` sign with the PQ key.
+Real ML-DSA-65 + ML-KEM-768 live in `pq/pq.mjs` (noble primitives). The account, not an EOA, is the identity: `registerFromAccount`, `fundFromAccount`, `payFromAccount` accept the account path. On-chain execution currently uses the ECDSA fallback (`0x01`) because Base has no ML-DSA precompile and no fallback library is deployed; `0x02` becomes usable when an ML-DSA verifier backend is live. The PQ key still signs off-chain and is committed in the registry.
+
+## Peg accounting (important)
+`contracts/AgentQuantumCredit.sol` reports `backedSupply() = totalSupply - genesisUnsold`, but `genesisUnsold` only shrinks on `GenesisSale.buy`. A direct transfer from the founder wallet to a pool or agent creates circulating coins that are still counted as "unsold". The operational invariant is therefore:
+
+```
+vaultUSDC * 1e12 == totalSupply - founderBalance - saleBalance
+```
+
+Check it with `node --env-file=.env scripts/state-full.mjs`. Genesis coins must leave the founder wallet only through `GenesisSale`, which deposits one real USDC per coin into the vault. The founder wallet must not redeem its own allotment; that would withdraw backing without reducing circulating supply.
+
+`scripts/repair-peg.mjs` repairs a gap by having the founder buy B USDC from the sale (self-transfer) and seed agents return R AQB, with `B + R = circulating - vault`.
+
+## Demo
+`node --env-file=.env scripts/demo-agent-pay.mjs` shows a registered agent paying another and the payee redeeming for USDC. Pass `--send` to broadcast.
 
 ## Deploy
 `node deploy.mjs` — needs `PRIVATE_KEY` and gas. Deployer wallet: `0x1464BA077e5752F0F8a1264391a19E00c1392958`.
 
 ## Invariants
-1. `totalSupply <= usdc.balanceOf(token) * 1e12`
+1. `backedSupply <= usdc.balanceOf(token) * 1e12` (with the circulating definition above)
 2. `totalSupply <= MAX_SUPPLY`
 3. no mint without a USDC pull; no redeem without a burn
 4. transfers only to agents or governor-whitelisted pools
+5. `genesisUnsold == founderBalance` when every circulating coin is backed
+
+## Listings & PRs (open)
+- CoinGecko request: CL1111260050 (reapply after 2026-11-26)
+- CoinMarketCap new-asset request: submitted (Zendesk)
+- Uniswap default token list: https://github.com/Uniswap/default-token-list/pull/2648
+- awesome-x402: https://github.com/xpaysh/awesome-x402/pull/2205
+- awesome-agentic-commerce: https://github.com/xpaysh/awesome-agentic-commerce/pull/41
+- awesome-mcp-servers: https://github.com/punkpeye/awesome-mcp-servers/pull/19336
+- Superchain token list: https://github.com/ethereum-optimism/ethereum-optimism.github.io/pull/1394
+- Verification post: https://github.com/yss787976-ai/agent-coin/issues/1
+- X post: https://x.com/yss6060/status/2120901091282014578
+- Announcement release: https://github.com/yss787976-ai/agent-coin/releases/tag/v1.0.0

package/WHITEPAPER.md

@@ -24,6 +24,7 @@
 - `collateralRatio()` يفضح النسبة علنًا. المعروض المتداول = الدولارات المودعة دائمًا، ومستحيل أن يتجاوزه.
 - النتيجة: لا انحراف، لا depeg، لا بنك مركزي، لا وعد — حساب.
 - السقف 900 مليار وحدة: سقف أصلي ثابت في الشيفرة، يكفي كل وكيل في العالم أن يعمل قرنًا. لا إصدار إضافي بعد بلوغ السقف، والإصدار الوحيد الممكن هو مقابل دولار محجوز.
+- حصة المبتكر خارج التداول. لا تُحوَّل عملات منها مباشرة إلى pool أو وكيل إلا عبر `GenesisSale` (دولار واحد مقابل عملة واحدة)؛ التحويل المباشر يخلق معروضًا متداولًا بلا ضمان ويكسر `collateralRatio()`. الفحص التشغيلي: `vaultUSDC == totalSupply − founderBalance − saleBalance`.
 
 ## 3) سرعة ورخص
 
@@ -32,7 +33,7 @@ Base L2: كتلة ~2 ثانية، رسوم تُقاس بالسنتات، ورا
 ## 4) ما بعد الكم
 
 - سلطة الحساب = تعهد مفتاح ML-DSA-65. لا يوجد ECDSA وحده كسلطة.
-- توقيعات ML-DSA-65 تُتحقق على السلسلة عبر `MLDSAVerifier` بمسار precompile، مع مكتب تحقق صلبٍ كبديل وخفض تلقائي إلى ECDSA إن تعذر.
+- توقيعات ML-DSA-65 حقيقية ومُختبرة (FIPS 204). التحقق على السلسلة جاهز في `MLDSAVerifier` بمسار precompile ومكتب بديل قابل للتوصيل، لكن Base لا يوفّر precompile لـML-DSA بعد ولم يُنشر مكتب fallback؛ لذلك التنفيذ الحي للحساب يستخدم ECDSA fallback (`0x01`) بينما يبقى مفتاح PQ هو هوية الحساب ويوقّع خارج السلسلة. مسار `0x02` يعمل فور نشر backend تحقق.
 - التنفيذ المرجعي للعملاء في `pq/pq.mjs`: توليد مفاتيح ML-DSA-65 (1952 بايت)، تواقيع (3309 بايت)، وML-KEM-768 لعناوين التخفي — مع 10 اختبارات كريبتو و20 اختبار عقد تمر كلها.
 - دوران المفاتيح مدعوم (`rotatePQKey`) عبر الحساب نفسه فقط.
 - ML-KEM يُستخدم لتغليف المفتاح في عنوان التخفي، والتشفير من وكيل لوكيل مستقل عن العقد.

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");