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.
2026-07-29 19:53:25 +02:00
parent 2baff726a0
commit d0fc86c6e0
5 changed files with 133 additions and 64 deletions
--- 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

--- 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

--- 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

--- 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` | — |

--- 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