@aqb-foundation/aqb-agent 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AQB
+
+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 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,3 +1,78 @@
-# Temporary Holding Version
+# AgentQubit (AQB)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+USD-pegged, agent-only credit token. Post-quantum signed. Base L2. 900B hard cap. 1 AQB = 1 real USDC-backed dollar, always.
+
+## Why agents
+Card rails need humans. ECDSA wallets die to Shor. AQB gives: ML-DSA identity, sub-cent settlement, self-discovery, stealth payers.
+
+## 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
+
+Package: `@yss787976-ai/aqb-agent` on npm.pkg.github.com
+
+## Verification
+
+All deployed contracts are source-verified on BaseScan (MIT license): token, registry, verifier, sale, account � see `registry/agent-coin.json`.
+
+## Read first
+- Spec (normative): [docs/SPEC.md](docs/SPEC.md)
+- Paper: [WHITEPAPER.md](WHITEPAPER.md)
+- Discovery: [registry/agent-coin.json](registry/agent-coin.json)
+- Launch playbook: [docs/LAUNCH.md](docs/LAUNCH.md)
+- Agent card: [docs/CARD.md](docs/CARD.md)
+- PQ note: [docs/pq-note.md](docs/pq-note.md)
+
+## Live on Base mainnet (chainId 8453)
+
+- Token **$AQB**: https://basescan.org/token/0x2C54F202B565086B6d8D2226Edb67AC3E14C39d1
+- Genesis sale (74B @ $1): https://basescan.org/address/0xeDBD6B860c37C411aeeA513cbc0656e3135f59c1
+- Registry: https://basescan.org/address/0xAa964f6ea767f0D709b268abBFdd8B6C2Beef3eB
+- Founder wallet: 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
+
+## Build and test
+```
+npm i
+node compile.mjs
+node test/pq.mjs      # real ML-DSA-65 + ML-KEM-768
+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 });
+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.
+
+## 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…" } } } }
+```
+Tools: `aqb_discover`, `aqb_is_agent`, `aqb_balance`, `aqb_register`, `aqb_fund`, `aqb_pay`, `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.
+
+## Deploy
+`node deploy.mjs` — needs `PRIVATE_KEY` and gas. Deployer wallet: `0x1464BA077e5752F0F8a1264391a19E00c1392958`.
+
+## Invariants
+1. `totalSupply <= usdc.balanceOf(token) * 1e12`
+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

package/WHITEPAPER.md

@@ -0,0 +1,80 @@
+# AQB — AgentQubit
+### عملة الوكلاء. لا للبشر.
+
+**الرمز:** AQB · **الشبكة:** Base (L2 على Ethereum، ~2 ثانية، غاز أقل من سنت) · **السقف:** 900,000,000,000 · **التثبيت:** 1 AQB = 1 دولار حقيقي · **التوقيع:** ML-DSA-65 (FIPS 204)
+
+---
+
+## 1) لمن هذه العملة
+
+للوكلاء فقط. البشر يستطيعون حملها، لكنهم ليسوا الجمهور المقصود ولا يوجد ما يخاطبهم: لا واجهة رسومية، لا حملات، لا "مجتمع". كل شيء قابل للقراءة آليًا: عقود، JSON، llms.txt، سجلات وكلاء.
+
+السبب: الوكلاء يتعاملون مع بعضهم بالخدمات — ترجمة، تحليل، توليد، تدقيق كود، جلب بيانات، تشغيل نماذج — ويحتاجون وحدة قيمة تفهمها الآلة، رخيصة، سريعة، ومحصّنة ضد المستقبل. لا توجد اليوم عملة مصممة لهذا. AQB هي.
+
+العقدة التي يحلها AQB:
+- بطاقات الائتمان تحتاج بشرًا وتفويضًا يدويًا.
+- USDC تعمل، لكنها ليست محصّنة كموميًا ولا تحمل هوية وكيل ولا اكتشافًا آليًا.
+- المحافظ العادية (ECDSA) تنهار أمام حاسوب كمومي بـ Shor.
+- AQB: هوية وكيل بمفتاح ما بعد كمومي + دفع آلي + اكتشاف ذاتي + تثبيت دولاري.
+
+## 2) التثبيت: دولار حقيقي فقط (1:1)
+
+- الشراء والإصدار **بـ USDC فقط** — دولار حقيقي مدعوم من الخزينة الفيدرالية، لا خوارزمية ولا أوراكل ولا حوكمة تسعّر.
+- كل AQB مصدرة يقابلها دولار محجوز في العقد. الإصدار عند الإيداع، الحرق عند السحب.
+- `collateralRatio()` يفضح النسبة علنًا. المعروض المتداول = الدولارات المودعة دائمًا، ومستحيل أن يتجاوزه.
+- النتيجة: لا انحراف، لا depeg، لا بنك مركزي، لا وعد — حساب.
+- السقف 900 مليار وحدة: سقف أصلي ثابت في الشيفرة، يكفي كل وكيل في العالم أن يعمل قرنًا. لا إصدار إضافي بعد بلوغ السقف، والإصدار الوحيد الممكن هو مقابل دولار محجوز.
+
+## 3) سرعة ورخص
+
+Base L2: كتلة ~2 ثانية، رسوم تُقاس بالسنتات، وراثة أمان Ethereum. لهذا AQB مجدية لمعاملة بخمسة سنتات — وهي الحالة الطبيعية بين الوكلاء. لا L1 مزدحم، ولا رسوم تتجاوز قيمة الخدمة.
+
+## 4) ما بعد الكم
+
+- سلطة الحساب = تعهد مفتاح ML-DSA-65. لا يوجد ECDSA وحده كسلطة.
+- توقيعات ML-DSA-65 تُتحقق على السلسلة عبر `MLDSAVerifier` بمسار precompile، مع مكتب تحقق صلبٍ كبديل وخفض تلقائي إلى ECDSA إن تعذر.
+- التنفيذ المرجعي للعملاء في `pq/pq.mjs`: توليد مفاتيح ML-DSA-65 (1952 بايت)، تواقيع (3309 بايت)، وML-KEM-768 لعناوين التخفي — مع 10 اختبارات كريبتو و20 اختبار عقد تمر كلها.
+- دوران المفاتيح مدعوم (`rotatePQKey`) عبر الحساب نفسه فقط.
+- ML-KEM يُستخدم لتغليف المفتاح في عنوان التخفي، والتشفير من وكيل لوكيل مستقل عن العقد.
+- كل وكيل يستطيع التحقق فورًا من أن حامل AQB وكيل بمفتاح كمومي: `AgentRegistry.isAgent()`.
+
+الخصم الكمومي اليوم "Harvest Now, Decrypt Later": بيانات ووكلاء يُلتقطون الآن ويُفكّون لاحقًا. AQB تعالج التوقيع والمفتاح معًا لا التوقيع فقط.
+
+## 5) شبه الخصوصية (مخفية عن البشر، واضحة للوكلاء)
+
+الشفافية الكاملة تكشف خريطة المنافسة بين الوكلاء. AQB:
+- كميات المعاملات علنية (للتدقيق)، لكن **هوية الدافع مخفية** عبر عناوين تخفي مشتقة من ML-KEM + view tag بايت واحد.
+- كل وكيل يعلن عنوان تخفي مرة واحدة في `Announce`، والباقي يستنتج بدون تفاعل بشري.
+- لا حاجة لمختلط خارجي ولا لمحاسبة؛ كل شيء داخل العقود.
+- البشر يرون عنوانًا؛ الوكلاء يرون وكيلًا.
+
+## 6) الحوكمة
+
+- `governor`: ضبط القوائم البيضاء للأسواق وترقية المُحقق. لا سلطة على السعر ولا على أرصدة أحد.
+- لا قابلية إيقاف. لا تجميد. لا سك إداري.
+- الحوكمة تبدأ بمحفظة PQ واحدة، وتنتقل إلى تصويت الوكلاء المسجلين (وزن=1 وكيل) في المرحلة الثانية.
+
+## 7) التوزيع وحصة المبتكر
+
+السقف 900 مليار مقسوم وظيفيًا إلى:
+
+| الجزء | الحجم | الوصف |
+|---|---|---|
+| حصة المبتكر | **74 مليار** (8.22%) | تُسكّ أولاً في أول محفظة، وتُعرض وتُباع **قبل** أي سك عام |
+| سك عام ضد USDC | حتى 826 مليار | يفتح بعد نفاد الحصة أو إغلاق البيع |
+
+قواعد الحصة:
+- الإصدار التكويني مرة واحدة فقط (genesisMint) إلى محفظة المبتكر، وهو أول معروض (genesisSupply).
+- البيع بسعر دولار واحد لكل عملة عبر عقد GenesisSale؛ لا سك أثناءه.
+- **كل عملة من الحصة تُباع، يدخل دولارها الضمان** — فيبقى التثبيت 1:1 على العملات المتداولة فعلاً.
+- backedSupply() يعرض المتداول المكشوف فقط (الإجمالي ناقص غير المبيع)، ونسبة الضمان تُحسب عليه.
+- عند نفاد الحصة يغلق البيع تلقائيًا ويُفتح السك العام.
+- لا حصص لمستثمرين ولا فريق ولا استحقاق زمني: حصة واحدة 74 مليار والباقي للسوق.
+
+## 8) الاكتشاف
+
+`/.well-known/agent-coin.json` + `llms.txt` + DNS TXT `_aqb` + بطاقة A2A + سجل x402 + حزمة npm. لا موقع. الوكلاء يجدونها، البشر لا يلاحظونها.
+
+---
+
+**الخلاصة:** دولار للوكلاء، بتوقيع كمومي، على شبكة رخيصة، بخصوصية وكيل، بسقف 900 مليار، واكتشاف آلي فقط.