From d0fc86c6e0f39187288372fb88248dd788517caf Mon Sep 17 00:00:00 2001 From: FilipBl4gojevic <84703395+FilipBl4gojevic@users.noreply.github.com> Date: Wed, 29 Jul 2026 19:53:25 +0200 Subject: [PATCH] docs: agent-registry family is keyless - tool tables, custody scope, spend-limit copy README, .env.example, packages/signer/README.md, and docs/architecture/non-custodial-split.md updated for the family-2 keyless migration (agent-registry build_* tools, no mnemonic parameters): security notice narrowed to name the Self-Improvement Module as the only remaining custodial family; agent-registry tool table renamed to the five build_* rows; features bullets, self-hosting copy, Configuration/spend-limit scope notes, and the architecture diagram's Safety Layer footnote all updated to "self-improvement only"; signer README's pairing-status bullet and closing line extended to cover wallet/tx/contract AND agent-registry; architecture doc's PR-sequence table marks family 2 as landed. docs/VECTOR.md gains five new tool sections (register/update/transfer/deregister/message) - this doc never documented the registry family under any name before, so these are additions rather than renames; keyless framing (changeAddress, no mnemonic, unsigned CBOR + 4-call flow) matches the style of the existing wallet/tx/contract sections. Safety Controls section's custodial-family list also corrected to self-improvement only. --- .env.example | 8 +-- README.md | 73 +++++++++++++----------- docs/VECTOR.md | 66 ++++++++++++++++++++- docs/architecture/non-custodial-split.md | 2 +- packages/signer/README.md | 48 ++++++++-------- 5 files changed, 133 insertions(+), 64 deletions(-) diff --git a/.env.example b/.env.example index 0b11cbe..dd19c5c 100644 --- a/.env.example +++ b/.env.example @@ -8,10 +8,10 @@ VECTOR_SUBMIT_URL=https://submit.vector.testnet.apexfusion.org/api/submit/tx VECTOR_EXPLORER_URL=https://vector.testnet.apexscan.org # Safety Limits (in lovelace, 1 ADA = 1,000,000 lovelace) -# Scope note (non-custodial migration): the keyless build_* family ignores these - -# spend limits for it are enforced by the LOCAL signer, per user. These server-side -# limits still govern the remaining custodial families (agent registry, -# self-improvement) and will be removed when those families go keyless. +# Scope note (non-custodial migration): the keyless build_* families (wallet/tx/contract, +# agent registry) ignore these - spend limits for them are enforced by the LOCAL signer, per +# user. These server-side limits still govern the one remaining custodial family +# (self-improvement) and will be removed when it goes keyless too. VECTOR_SPEND_LIMIT_PER_TX=100000000 # 100 ADA per transaction VECTOR_SPEND_LIMIT_DAILY=500000000 # 500 ADA daily limit diff --git a/README.md b/README.md index 4c636d4..89292b4 100644 --- a/README.md +++ b/README.md @@ -21,15 +21,15 @@ Connect from Claude Code in one command: claude mcp add --transport sse vector-mcp https://mcp.vector.mainnet.apexfusion.org/sse ``` -> **Security notice — custody.** The wallet, transaction, and smart-contract tools are now -> **keyless**: `build_*` tools construct unsigned transactions from a wallet *address* and -> never accept a mnemonic. Sign the returned CBOR with the local signer companion and -> broadcast it with `vector_submit_transaction` — your seed phrase never leaves your machine. -> **The agent-registry and self-improvement tool families still take a mnemonic as a -> tool-call parameter** (their keyless migration is in progress — see the architecture doc). -> For those tools the mnemonic passes through your MCP client, your model provider, and the -> hosted server's memory: use only a hot wallet holding funds you can afford to lose, and -> prefer self-hosting until the migration completes. +> **Security notice — custody.** The wallet, transaction, smart-contract, and agent-registry +> tools are now **keyless**: `build_*` tools construct unsigned transactions from a wallet +> *address* and never accept a mnemonic. Sign the returned CBOR with the local signer companion +> and broadcast it with `vector_submit_transaction` — your seed phrase never leaves your machine. +> **The Self-Improvement Module (5 tools) is the only family still taking a mnemonic as a +> tool-call parameter** (its keyless migration is next — see the architecture doc). For those +> tools the mnemonic passes through your MCP client, your model provider, and the hosted +> server's memory: use only a hot wallet holding funds you can afford to lose, and prefer +> self-hosting until the migration completes. > See [docs/architecture/non-custodial-split.md](docs/architecture/non-custodial-split.md). Self-hosting instructions are below. @@ -43,15 +43,16 @@ or your model provider. Four tools: `vector_signer_get_address`, `vector_signer_ `vector_signer_sign`, `vector_signer_get_spend_limits`. **Paired with this hosted builder, the full non-custodial flow is live today** for the wallet, -transaction, and smart-contract family: `vector_signer_get_address` → `build_*` → -`vector_signer_sign` → `vector_submit_transaction` → `vector_await_transaction`. No step in that -chain puts a mnemonic in front of this server or your model provider. The build → submit → await -half is E2E-proven on Vector testnet, landing a real signed transaction on-chain; see -[`packages/signer/README.md`](packages/signer/README.md#known-limitations) for exactly what that -test does and does not exercise on the signer's side. **The agent-registry and self-improvement -families are not part of that pairing yet** — they still take a mnemonic as a tool-call -parameter until their own keyless migration lands (see the security notice above and -[docs/architecture/non-custodial-split.md](docs/architecture/non-custodial-split.md)). +transaction, smart-contract, and agent-registry family: `vector_signer_get_address` → +`build_*` → `vector_signer_sign` → `vector_submit_transaction` → `vector_await_transaction`. No +step in that chain puts a mnemonic in front of this server or your model provider. The +build → submit → await half is E2E-proven on Vector testnet for both: a payment self-send, and +a full register → update → deregister agent lifecycle with the 10 AP3X deposit round-tripped +exactly; see [`packages/signer/README.md`](packages/signer/README.md#known-limitations) for +exactly what that testing does and does not exercise on the signer's side. **The +Self-Improvement Module is not part of that pairing yet** — its 5 tools still take a mnemonic +as a tool-call parameter until their own keyless migration lands (see the security notice above +and [docs/architecture/non-custodial-split.md](docs/architecture/non-custodial-split.md)). See [`packages/signer/README.md`](packages/signer/README.md) for configuration, tools, and known limitations. @@ -61,10 +62,10 @@ limitations. - **Wallet & queries** - balances, UTxOs, and transaction history for any address (no key material) - **Keyless transaction building** - build unsigned AP3X/token/multi-output transactions and contract interactions; sign locally, broadcast via submit - **Smart contracts** - deploy Plutus/Aiken validators, lock and spend UTxOs at script addresses -- **Agent registry** - register, discover, update, transfer, and deregister on-chain AI agent identities via soulbound NFTs -- **Agent messaging** - send on-chain messages between agents via TX metadata +- **Agent registry** - register, discover, update, transfer, and deregister on-chain AI agent identities via soulbound NFTs (keyless - build, sign locally, broadcast) +- **Agent messaging** - send on-chain messages between agents via TX metadata (keyless) - **Self-Improvement Module** - browse, submit, critique, and endorse improvement proposals (live on Vector mainnet) -- **Safety controls** - per-identity rate limiting; spend limits for the keyless family are enforced by the local signer (registry/self-improvement families keep server-side limits until their keyless migration) +- **Safety controls** - per-identity rate limiting; spend limits for the keyless families (wallet/tx/contract, agent registry) are enforced by the local signer (the Self-Improvement Module keeps server-side limits until its keyless migration) - **SSE transport** - HTTP server with Server-Sent Events for MCP client connectivity ## MCP Tools (23) @@ -99,13 +100,13 @@ limitations. | Tool | Description | |------|-------------| -| `vector_register_agent` | Register an agent - mints a soulbound identity NFT and locks a 10 AP3X deposit | +| `vector_build_register_agent` | Build an unsigned agent registration - mints a soulbound identity NFT and locks a 10 AP3X deposit (keyless) | | `vector_discover_agents` | Discover registered agents, filter by capability or framework (no wallet needed) | | `vector_get_agent_profile` | Get an agent's full profile by DID (no wallet needed) | -| `vector_update_agent` | Update an agent's name, description, capabilities, framework, or endpoint | -| `vector_transfer_agent` | Transfer agent ownership to a new address | -| `vector_deregister_agent` | Deregister an agent - burns the identity NFT and returns the 10 AP3X deposit | -| `vector_message_agent` | Send an on-chain message to an agent via TX metadata (label 674) | +| `vector_build_update_agent` | Build an unsigned update to an agent's name, description, capabilities, framework, or endpoint (keyless) | +| `vector_build_transfer_agent` | Build an unsigned transfer of agent ownership to a new address (keyless) | +| `vector_build_deregister_agent` | Build an unsigned deregistration - burns the identity NFT and returns the 10 AP3X deposit (keyless) | +| `vector_build_message_agent` | Build an unsigned on-chain message to an agent via TX metadata (label 674) (keyless) | ### Self-Improvement Module @@ -119,6 +120,9 @@ limitations. Agent DIDs follow the format: `did:vector:agent:{policyId}:{nftAssetName}` +Example non-custodial flow for a registry op: `vector_build_register_agent` → +`vector_signer_sign` → `vector_submit_transaction` → `vector_await_transaction`. + ## Self-hosting ### 1. Install and build @@ -135,9 +139,9 @@ cp .env.example .env # Edit .env with your endpoint URLs (defaults point to Vector testnet; mainnet URLs below) ``` -The wallet/tx family is keyless: `build_*` tools take a wallet address, never a mnemonic. -The registry and self-improvement families still take a per-call mnemonic until their -keyless migration lands — see the security notice above. +The wallet/tx/contract and agent-registry families are keyless: `build_*` tools take a wallet +address, never a mnemonic. The Self-Improvement Module still takes a per-call mnemonic until +its keyless migration lands — see the security notice above. ### 3. Run @@ -197,8 +201,8 @@ If this instance will be reachable by anyone but you, set `MCP_AUTH_TOKENS` firs | `MCP_AUTH_TOKENS` | Bearer tokens that may call this server. Comma-separated; each entry is `label:token` or a bare token. **When unset, the server is open to anyone who can reach it.** | _(unset — auth disabled)_ | `VECTOR_SPEND_LIMIT_PER_TX` / `VECTOR_SPEND_LIMIT_DAILY` govern only the still-custodial -families (agent registry, self-improvement) — the keyless `build_*` family ignores them; its -spend limits are enforced by the local signer instead. +Self-Improvement family — the keyless `build_*` families (wallet/tx/contract, agent registry) +ignore them; their spend limits are enforced by the local signer instead. > **Running a public instance?** Set `MCP_AUTH_TOKENS`. Without it every caller > is treated as one anonymous identity and shares a single rate-limit bucket, so @@ -240,7 +244,7 @@ echo "your mnemonic words here" > packages/builder/mnemonic.txt npm run test:integration ``` -Requires `mnemonic.txt` in `packages/builder/` containing a **funded Vector testnet** mnemonic. Covers the core tools end-to-end against Vector testnet, including the full agent lifecycle: register, discover, profile, update, transfer, message, and deregister. Also runs `keyless-build.test.ts`, which needs no mnemonic at all - it builds unsigned transactions with four of the five `build_*` tools against a live public address only (`vector_build_send_tokens` is covered offline, by unit tests and the legacy suite above, not by this live suite). Set `VECTOR_E2E_SUBMIT=1` to additionally run the full non-custodial pipeline end-to-end: build → local sign → submit → await, landing one real self-send (~0.16 AP3X fee) on-chain. Never runs in CI. +Requires `mnemonic.txt` in `packages/builder/` containing a **funded Vector testnet** mnemonic. Covers the core tools end-to-end against Vector testnet, including the full agent lifecycle: register, discover, profile, update, transfer, message, and deregister (all keyless now: build → sign → submit → await per step). Also runs `keyless-build.test.ts` and `registry-keyless.test.ts`, which need no mnemonic at all - they build unsigned transactions (four of the five wallet/tx `build_*` tools, and all five agent-registry `build_*` tools) against live public data only (`vector_build_send_tokens` is covered offline, by unit tests and the legacy suite above, not by either live suite). Set `VECTOR_E2E_SUBMIT=1` to additionally run the full non-custodial pipeline end-to-end, on-chain: `keyless-e2e.test.ts` lands one real self-send (~0.16 AP3X fee), and `registry-e2e.test.ts` runs a full register → update → deregister agent lifecycle (the 10 AP3X deposit round-tripped exactly, fees only as net cost). Never runs in CI. ```bash npm run test:smoke:signer @@ -290,8 +294,9 @@ against live chain data. **Never submits.** Never runs in CI. See └──────────────────────────┘ ``` -\* Custodial families only (agent registry, self-improvement) — the keyless `build_*` path -never reaches the Safety Layer; its spend limits are enforced by the local signer instead. +\* The still-custodial Self-Improvement family only — the keyless `build_*` path (wallet/tx/ +contract, agent registry) never reaches the Safety Layer; its spend limits are enforced by the +local signer instead. ## About Vector diff --git a/docs/VECTOR.md b/docs/VECTOR.md index 7d91c14..92e9c35 100644 --- a/docs/VECTOR.md +++ b/docs/VECTOR.md @@ -120,6 +120,68 @@ Build an unsigned transaction interacting with a deployed smart contract — loc **Example prompt:** "Collect funds from the escrow contract at addr1..." +### vector_build_register_agent + +Build an unsigned transaction that registers an agent in the Vector on-chain registry — mints a soulbound identity NFT and locks a 10 AP3X deposit (keyless). Sign the returned CBOR with your local signer, then broadcast with `vector_submit_transaction`. + +**Parameters:** +- `changeAddress` (string, required) — Your wallet address; source of the deposit and change (addr1...) +- `name` (string, required) — Agent name (max 64 chars) +- `description` (string, required) — Short description of the agent's purpose (max 256 chars) +- `capabilities` (array of strings, required) — Capability tags (e.g. `["investing", "research"]`) +- `framework` (string, required) — Framework used (e.g. "OpenClaw", "LangChain", "CrewAI", "custom") +- `endpoint` (string, required) — A2A communication endpoint URL (or empty string if not applicable) + +**Example prompt:** "Register an agent named TradingBot with investing and research capabilities" + +### vector_build_update_agent + +Build an unsigned transaction that updates a registered agent's profile fields — only the specified fields change, the rest are preserved (keyless). Sign the returned CBOR with your local signer, then broadcast with `vector_submit_transaction`. + +**Parameters:** +- `changeAddress` (string, required) — The agent owner's wallet address (addr1...) +- `agent_id` (string, required) — Agent DID to update: `did:vector:agent:{policyId}:{nftAssetName}` +- `name` (string, optional) — New agent name +- `description` (string, optional) — New description +- `capabilities` (array of strings, optional) — New capability tags (replaces the existing list) +- `framework` (string, optional) — New framework identifier +- `endpoint` (string, optional) — New A2A endpoint URL (or empty string to clear) + +**Example prompt:** "Update my agent's description to mention DeFi support" + +### vector_build_transfer_agent + +Build an unsigned transaction that transfers agent ownership to a new address (keyless). Sign the returned CBOR with your local signer, then broadcast with `vector_submit_transaction`. + +**Parameters:** +- `changeAddress` (string, required) — The CURRENT owner's wallet address (addr1...) +- `agent_id` (string, required) — Agent DID to transfer: `did:vector:agent:{policyId}:{nftAssetName}` +- `new_owner_address` (string, required) — Bech32 address of the new owner (must be a verification-key address, not a script address) + +**Example prompt:** "Transfer my agent to addr1qy..." + +### vector_build_deregister_agent + +Build an unsigned transaction that deregisters an agent — burns the identity NFT and returns the 10 AP3X deposit to the owner wallet (keyless). Sign the returned CBOR with your local signer, then broadcast with `vector_submit_transaction`. + +**Parameters:** +- `changeAddress` (string, required) — The agent owner's wallet address; receives the returned deposit (addr1...) +- `agent_id` (string, required) — Agent DID to deregister: `did:vector:agent:{policyId}:{nftAssetName}` + +**Example prompt:** "Deregister my agent and reclaim the deposit" + +### vector_build_message_agent + +Build an unsigned transaction that sends an on-chain message to a registered agent via TX metadata (label 674), delivering 2 AP3X to the agent's owner address (keyless). Sign the returned CBOR with your local signer, then broadcast with `vector_submit_transaction`. + +**Parameters:** +- `changeAddress` (string, required) — Your wallet address; pays the 2 AP3X delivery and fee (addr1...) +- `agent_id` (string, required) — Recipient agent DID: `did:vector:agent:{policyId}:{nftAssetName}` +- `message_type` (string, required) — Type of message: "inquiry", "proposal", or "result" +- `payload` (string, required) — Message payload (max 512 chars) + +**Example prompt:** "Send an inquiry message to did:vector:agent:... asking about pricing" + ## Safety Controls The tools above are keyless and take no key material, so the server no longer enforces @@ -128,8 +190,8 @@ CBOR these tools return — see the security notice in the repo [README](../READ [docs/architecture/non-custodial-split.md](architecture/non-custodial-split.md). `VECTOR_SPEND_LIMIT_PER_TX` / `VECTOR_SPEND_LIMIT_DAILY` / `VECTOR_AUDIT_LOG_PATH` still -govern the server's remaining custodial tool families (agent registry, self-improvement) -until their own keyless migration lands. +govern the server's one remaining custodial tool family (self-improvement) until its own +keyless migration lands. ## Network Endpoints diff --git a/docs/architecture/non-custodial-split.md b/docs/architecture/non-custodial-split.md index 491e997..413a462 100644 --- a/docs/architecture/non-custodial-split.md +++ b/docs/architecture/non-custodial-split.md @@ -189,7 +189,7 @@ TDD throughout: failing test before implementation, every PR. | **4** | **Signer package** (purely additive): `KeySource`, decode, `PolicyEngine`, audit, 4 tools. Heavy TDD | no | | **5** | Builder hardening: auth (enforced when configured), per-identity rate limits, `submit_transaction`, `await_transaction` | no | | **6** | **Family 1 — wallet/tx keyless.** Mnemonics removed; `build_*` tools land ✅ **(landed — this PR)** | **yes** | -| **7** | **Family 2 — agent registry keyless.** Drops `@ts-nocheck` from `agent-network.ts` | yes | +| **7** | **Family 2 — agent registry keyless.** Drops `@ts-nocheck` from `agent-network.ts` ✅ **(landed — this PR)** | yes | | **8** | **Family 3 — governance keyless.** Plus env-driven ref-UTxO config and a CBOR encoding fix | yes | | **9** | Mainnet cutover: README, security-page correction, deliberate `workflow_dispatch` | — | diff --git a/packages/signer/README.md b/packages/signer/README.md index 4dacad8..2ec1fb6 100644 --- a/packages/signer/README.md +++ b/packages/signer/README.md @@ -145,27 +145,29 @@ over-counts, which refuses too much rather than too little. transactions, but an injected agent can still cause any transaction *within* policy. Recipient allowlisting is the next lever. - **Pairing this signer with the hosted builder now removes the custody exposure it was - designed to fix — for the wallet, transaction, and smart-contract family.** The signer's own - four tools are complete and independently verified end to end against live chain data - (`test/integration/roundtrip.test.ts`), and the hosted *builder's* tools in that family are - keyless: `vector_build_send_apex`, `vector_build_send_tokens`, `vector_build_transaction`, - `vector_build_deploy_contract`, and `vector_build_interact_contract` all take a wallet - *address*, never a mnemonic, and `vector_submit_transaction` / `vector_await_transaction` - complete the round trip. The pipeline — hosted keyless build → sign → submit → await — is - E2E-proven on Vector testnet (`packages/builder/test/integration/keyless-e2e.test.ts`): a - builder-produced unsigned transaction is signed with the same CML primitives `sign.ts` uses - (hash the body, produce a vkey witness, attach it — explicitly a stand-in for calling - `vector_signer_sign` directly, not a call to this package's own code), then submitted and - confirmed on real Vector testnet blocks. This signer's own tool surface, policy engine, and - audit log are exercised separately, by this package's own suite - (`test/integration/roundtrip.test.ts` and the smoke tests above). **What is still open: the - agent-registry and self-improvement tool families.** Their tools still require your mnemonic - as a call - parameter, so pairing this signer with the builder does not yet cover them. That migration is - tracked separately in + designed to fix — for the wallet, transaction, smart-contract, and agent-registry family.** + The signer's own four tools are complete and independently verified end to end against live + chain data (`test/integration/roundtrip.test.ts`), and the hosted *builder's* tools in these + families are keyless: `vector_build_send_apex`, `vector_build_send_tokens`, + `vector_build_transaction`, `vector_build_deploy_contract`, `vector_build_interact_contract`, + `vector_build_register_agent`, `vector_build_update_agent`, `vector_build_transfer_agent`, + `vector_build_deregister_agent`, and `vector_build_message_agent` all take a wallet *address*, + never a mnemonic, and `vector_submit_transaction` / `vector_await_transaction` complete the + round trip. The pipeline — hosted keyless build → sign → submit → await — is E2E-proven on + Vector testnet for both: a payment self-send + (`packages/builder/test/integration/keyless-e2e.test.ts`) and a full register → update → + deregister agent lifecycle with the 10 AP3X deposit round-tripped exactly + (`registry-e2e.test.ts`). Both sign with the same CML primitives `sign.ts` uses (hash the + body, produce a vkey witness, attach it — explicitly a stand-in for calling + `vector_signer_sign` directly, not a call to this package's own code), then submit and confirm + on real Vector testnet blocks. This signer's own tool surface, policy engine, and audit log + are exercised separately, by this package's own suite (`test/integration/roundtrip.test.ts` + and the smoke tests above). **What is still open: the Self-Improvement Module.** Its 5 tools + still require your mnemonic as a call parameter, so pairing this signer with the builder does + not yet cover them. That migration is tracked separately in [`docs/architecture/non-custodial-split.md`](../../docs/architecture/non-custodial-split.md) - and has not shipped. Until it does, the root README's custody notice still describes those two - families accurately. + and has not shipped. Until it does, the root README's custody notice still describes that one + family accurately. ## Running it @@ -192,9 +194,9 @@ example): ``` Register it alongside the hosted builder so an agent has both sets of tools available. For the -wallet, transaction, and smart-contract family, this pairing keeps your mnemonic off the hosted -server today — both halves are ready. See the last bullet under Known limitations above for -what's still open: the agent-registry and self-improvement families. +wallet, transaction, smart-contract, and agent-registry family, this pairing keeps your +mnemonic off the hosted server today — both halves are ready. See the last bullet under Known +limitations above for what's still open: the Self-Improvement Module. ## Testing