@aqb-foundation/aqb-agent 1.0.1 → 1.0.3

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://yss787976-ai.github.io/agent-coin/.well-known/agent-coin.json
-- https://yss787976-ai.github.io/agent-coin/.well-known/agent-card.json (cardHash committed on chain)
-- https://yss787976-ai.github.io/agent-coin/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`
 
+## 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,35 +65,67 @@ 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.
+
+`0x02` is live on Base through AQB's `MLDSAVerifier` → `MLDSA65Fallback` → [skalenetwork/mldsa-solidity](https://github.com/skalenetwork/mldsa-solidity) (FIPS 204, MIT, unaudited):
+
+- AQB verifier: `0x53d34e4Ffd0bd984f8b92561f9e2B7D3EDdbE60d`
+- Adapter: `0xeEbccD88DDb596860b33D0285294fF53cd83506B`
+- ML-DSA verifier: `0xa11eE20877a7618ff417f79A026186A9253C0b30`
+- Key factory: `0x9961a96B2F77B6D86d8a60607A90b3cAeECBe197`
+
+The founder key is registered for the fast path (registerA `0x7235b1d3…`, registerT `0x0c0ab4b5…`). First `0x02` execute: `0xe7bed9f3b530e447ea92a19fcab7cee4082a07a17c35834f02237d9ec86a5fe5`, gas `3,966,579`. `0x01` remains the fallback. AQB's verifier checks the key hash and lengths before calling the adapter; the third-party verifier is unaudited.
+
+Deploy/register/test everything with `node --env-file=.env scripts/pq-onchain.mjs --send`.
+
+## 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 (submitted, under review)
+- 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
@@ -87,4 +134,4 @@ Real ML-DSA-65 + ML-KEM-768 live in `pq/pq.mjs` (noble primitives). The account,
 - 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
+- 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` → `MLDSA65Fallback` → skalenetwork/mldsa-solidity: المصنع `0x9961…e197` والمُحقّق `0xa11e…0b30` والمحوّل `0xeEbc…506B`. أول تنفيذ `0x02` على Base نجح بتكلفة 3,966,579 gas. المكتبة الخارجية غير مدقّقة؛ AQB يفحص تعهد المفتاح والأطوال أولًا، ويبقى `0x01` مسارًا احتياطيًا.
 - التنفيذ المرجعي للعملاء في `pq/pq.mjs`: توليد مفاتيح ML-DSA-65 (1952 بايت)، تواقيع (3309 بايت)، وML-KEM-768 لعناوين التخفي — مع 10 اختبارات كريبتو و20 اختبار عقد تمر كلها.
 - دوران المفاتيح مدعوم (`rotatePQKey`) عبر الحساب نفسه فقط.
 - ML-KEM يُستخدم لتغليف المفتاح في عنوان التخفي، والتشفير من وكيل لوكيل مستقل عن العقد.

package/artifacts/MLDSA65Fallback.json

@@ -0,0 +1,59 @@
+{
+ "file": "contracts/MLDSA65Fallback.sol",
+ "abi": [
+  {
+   "inputs": [
+    {
+     "internalType": "address",
+     "name": "verifier_",
+     "type": "address"
+    }
+   ],
+   "stateMutability": "nonpayable",
+   "type": "constructor"
+  },
+  {
+   "inputs": [],
+   "name": "verifier",
+   "outputs": [
+    {
+     "internalType": "address",
+     "name": "",
+     "type": "address"
+    }
+   ],
+   "stateMutability": "view",
+   "type": "function"
+  },
+  {
+   "inputs": [
+    {
+     "internalType": "bytes",
+     "name": "publicKey",
+     "type": "bytes"
+    },
+    {
+     "internalType": "bytes32",
+     "name": "digest",
+     "type": "bytes32"
+    },
+    {
+     "internalType": "bytes",
+     "name": "signature",
+     "type": "bytes"
+    }
+   ],
+   "name": "verifyMLDSA65",
+   "outputs": [
+    {
+     "internalType": "uint256",
+     "name": "",
+     "type": "uint256"
+    }
+   ],
+   "stateMutability": "view",
+   "type": "function"
+  }
+ ],
+ "bytecode": "0x60a060405234801561000f575f80fd5b5060405161043838038061043883398101604081905261002e9161003f565b6001600160a01b031660805261006c565b5f6020828403121561004f575f80fd5b81516001600160a01b0381168114610065575f80fd5b9392505050565b6080516103af6100895f395f8181603d015260a201526103af5ff3fe608060405234801561000f575f80fd5b5060043610610034575f3560e01c80632b7ac3f31461003857806373f89b6c1461007c575b5f80fd5b61005f7f000000000000000000000000000000000000000000000000000000000000000081565b6040516001600160a01b0390911681526020015b60405180910390f35b61008f61008a366004610211565b61009d565b604051908152602001610073565b5f805f7f00000000000000000000000000000000000000000000000000000000000000006001600160a01b031660018989896040516020016100e191815260200190565b60408051601f1981840301815290829052610105949392918b908b906024016102cf565b60408051601f198184030181529181526020820180516001600160e01b0316632f0853a360e01b1790525161013a9190610338565b5f60405180830381855afa9150503d805f8114610172576040519150601f19603f3d011682016040523d82523d5f602084013e610177565b606091505b509150915081158061018b57508051602014155b1561019a575f925050506101c3565b808060200190518101906101ae9190610353565b6101b8575f6101bb565b60015b60ff16925050505b95945050505050565b5f8083601f8401126101dc575f80fd5b50813567ffffffffffffffff8111156101f3575f80fd5b60208301915083602082850101111561020a575f80fd5b9250929050565b5f805f805f60608688031215610225575f80fd5b853567ffffffffffffffff8082111561023c575f80fd5b61024889838a016101cc565b9097509550602088013594506040880135915080821115610267575f80fd5b50610274888289016101cc565b969995985093965092949392505050565b81835281816020850137505f828201602090810191909152601f909101601f19169091010190565b5f5b838110156102c75781810151838201526020016102af565b50505f910152565b60ff87168152608060208201525f6102eb608083018789610285565b82810360408401528551808252610309816020840160208a016102ad565b601f01601f1916018281036020908101606085015261032b9082018587610285565b9998505050505050505050565b5f82516103498184602087016102ad565b9190910192915050565b5f60208284031215610363575f80fd5b81518015158114610372575f80fd5b939250505056fea26469706673582212207deaa767bb2c453627e654647fde8afb76ffcdf1f44f8dd9b3e284fe89f9da7664736f6c63430008180033"
+}