From 714d4ebcd4e90ad8f533e4efbf898e1568e1e6d7 Mon Sep 17 00:00:00 2001 From: FilipBl4gojevic <84703395+FilipBl4gojevic@users.noreply.github.com> Date: Wed, 29 Jul 2026 14:22:31 +0200 Subject: [PATCH] docs: wallet/tx family is keyless - security notice, tool tables, spend-limit scope README, .env.example, and docs/architecture/non-custodial-split.md updated for the family-1 keyless migration (build_* tools, no mnemonic parameters): custody notice rewritten to describe the keyless boundary precisely, tool tables synced to the 23-tool surface (4 renames, 4 changed in place, 2 removed), self-hosting and testing copy updated, .env.example spend-limit scope annotated, and the architecture doc's PR-sequence table marks family 1 as landed. docs/VECTOR.md (flagged by Task 4 as referencing stale tool names) is also updated: renamed/removed tool sections corrected, keyless changeAddress params added, and the Safety Controls / Error Handling sections stop claiming server-side spend limits and mnemonic requirements that no longer apply to the tools this page documents. Edits confined to tool names and custody claims - no restructuring, no wholesale ADA to AP3X pass beyond the sections touched. --- .env.example | 4 + README.md | 49 ++++++------ docs/VECTOR.md | 94 ++++++++++-------------- docs/architecture/non-custodial-split.md | 2 +- 4 files changed, 68 insertions(+), 81 deletions(-) diff --git a/.env.example b/.env.example index fc847bc..0b11cbe 100644 --- a/.env.example +++ b/.env.example @@ -8,6 +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. 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 a79dba1..e53acbc 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Built on [Ogmios](https://ogmios.dev/) + [Koios](https://www.koios.rest/) - no B ## Hosted servers - no install -Hosted instances run on both networks, exposing all 25 tools: +Hosted instances run on both networks, exposing all 23 tools: | Network | Endpoint | |---------|----------| @@ -21,13 +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.** Signing tools currently take your wallet mnemonic as a -> tool-call parameter. It therefore passes through your MCP client, your model provider, -> and the hosted server's memory — it is not written to disk, but it is exposed. Use only -> a hot wallet holding funds you can afford to lose, and prefer self-hosting until the -> non-custodial migration lands. `vector_submit_transaction` and `vector_await_transaction` -> are the exception — they take no mnemonic and sign nothing; they only broadcast a -> transaction signed elsewhere (for example by a local signer) and poll for confirmation. +> **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. > See [docs/architecture/non-custodial-split.md](docs/architecture/non-custodial-split.md). Self-hosting instructions are below. @@ -49,34 +51,32 @@ it ships, the security notice above still applies. ## Features -- **Wallet management** - derive addresses from mnemonic, query balances and UTxOs -- **Transactions** - send AP3X and native tokens, build multi-output transactions, dry-run simulations +- **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 - **Self-Improvement Module** - browse, submit, critique, and endorse improvement proposals (live on Vector mainnet) -- **Safety controls** - per-transaction and daily spend limits, persistent audit log, rate limiting +- **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) - **SSE transport** - HTTP server with Server-Sent Events for MCP client connectivity -## MCP Tools (25) +## MCP Tools (23) ### Wallet & Queries | Tool | Description | |------|-------------| | `vector_get_balance` | Get AP3X and token balances for any address | -| `vector_get_address` | Get the wallet address, balance, and holdings from a mnemonic | -| `vector_get_utxos` | List UTxOs for an address or wallet | -| `vector_get_spend_limits` | Check spend limits, daily usage, and audit log | -| `vector_get_transaction_history` | Get transaction history for a wallet | +| `vector_get_utxos` | List UTxOs for an address | +| `vector_get_transaction_history` | Get transaction history for an address | ### Transactions | Tool | Description | |------|-------------| -| `vector_send_apex` | Send AP3X (respects spend limits) | -| `vector_send_tokens` | Send native tokens with optional AP3X | -| `vector_build_transaction` | Build multi-output transactions (sign+submit or return unsigned CBOR) | +| `vector_build_send_apex` | Build an unsigned AP3X payment (keyless — sign with the local signer) | +| `vector_build_send_tokens` | Build an unsigned native-token transfer (keyless) | +| `vector_build_transaction` | Build an unsigned multi-output transaction (keyless, never submits) | | `vector_dry_run` | Simulate a transaction without submitting - estimate fees and validate | | `vector_submit_transaction` | Broadcast an already-signed transaction (for example one signed by the local signer) | | `vector_await_transaction` | Wait for a submitted transaction to be confirmed on-chain | @@ -85,8 +85,8 @@ it ships, the security notice above still applies. | Tool | Description | |------|-------------| -| `vector_deploy_contract` | Deploy a Plutus V1/V2/V3 or Aiken validator to the chain | -| `vector_interact_contract` | Lock AP3X at a script address or spend from it with a redeemer | +| `vector_build_deploy_contract` | Build an unsigned deployment of a Plutus V1/V2/V3 or Aiken validator (keyless) | +| `vector_build_interact_contract` | Build an unsigned lock or spend at a script address, with a redeemer (keyless) | ### Agent Registry @@ -128,8 +128,9 @@ cp .env.example .env # Edit .env with your endpoint URLs (defaults point to Vector testnet; mainnet URLs below) ``` -The mnemonic is passed per-call by the MCP client rather than stored in the environment. This -avoids environment dumps, but does not make it private — see the security notice above. +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. ### 3. Run @@ -228,7 +229,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. 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. Also runs `keyless-build.test.ts`, which needs no mnemonic at all - it builds every `build_*` tool's unsigned transaction against a live public address only. 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. ```bash npm run test:smoke:signer diff --git a/docs/VECTOR.md b/docs/VECTOR.md index a68539d..7d91c14 100644 --- a/docs/VECTOR.md +++ b/docs/VECTOR.md @@ -6,7 +6,7 @@ The Vector MCP Server exposes blockchain tools that AI agents can use to interac ## Prerequisites -1. A funded Vector wallet (15 or 24-word mnemonic) +1. A Vector wallet address (source of funds) — the tools below are keyless and take no mnemonic; signing happens separately via your local signer 2. Access to Vector network endpoints (Ogmios, submit API, Koios) 3. Node.js >= 14.0.0 @@ -21,111 +21,100 @@ Get ADA and token balances for any Vector address. **Example prompt:** "What's the balance of addr1qx..." -### vector_get_address - -Get the agent's own wallet address, balance, and token holdings. - -**Parameters:** None - -**Example prompt:** "What's my wallet address and balance?" - ### vector_get_utxos -List unspent transaction outputs for an address or the agent's wallet. +List unspent transaction outputs for an address. **Parameters:** -- `address` (string, optional) — Address to query. Uses agent's wallet if omitted. +- `address` (string, required) — Address to query (addr1...) -**Example prompt:** "Show me the UTxOs in my wallet" +**Example prompt:** "Show me the UTxOs at addr1qx..." -### vector_send_apex +### vector_build_send_apex -Send ADA from the agent's wallet to a recipient. Enforces spend limits. +Build an unsigned transaction sending AP3X to a recipient (keyless — takes no key material). Sign the returned CBOR with your local signer, then broadcast with `vector_submit_transaction`. **Parameters:** +- `changeAddress` (string, required) — Your wallet address; source of funds and change (addr1...) - `recipientAddress` (string, required) — Recipient address (addr1...) -- `amount` (number, required) — Amount of ADA to send (minimum 1) +- `amount` (number, required) — Amount of AP3X to send (minimum 1) - `metadata` (string, optional) — Transaction metadata in JSON format -**Example prompt:** "Send 5 ADA to addr1qy..." +**Example prompt:** "Send 5 AP3X to addr1qy..." -### vector_send_tokens +### vector_build_send_tokens -Send Vector native tokens from the agent's wallet. +Build an unsigned transaction sending Vector native tokens (keyless — takes no key material). Sign the returned CBOR with your local signer, then broadcast with `vector_submit_transaction`. **Parameters:** +- `changeAddress` (string, required) — Your wallet address; source of funds and change (addr1...) - `recipientAddress` (string, required) — Recipient address (addr1...) - `policyId` (string, required) — Token policy ID - `assetName` (string, required) — Asset name (can be empty) - `amount` (string, required) — Amount of tokens to send -- `adaAmount` (number, optional) — ADA to include with tokens +- `adaAmount` (number, optional) — AP3X to include with tokens **Example prompt:** "Send 100 of token with policy abc123... to addr1qy..." -### vector_get_spend_limits - -Check current spend limits, daily usage, and recent transaction audit log. - -**Parameters:** None - -**Example prompt:** "What are my current spend limits?" - ### vector_build_transaction -Build a complex multi-output transaction with metadata. Optionally sign and submit. +Build an unsigned multi-output transaction with metadata (keyless, never submits). Sign the returned CBOR with your local signer, then broadcast with `vector_submit_transaction`. **Parameters:** +- `changeAddress` (string, required) — Your wallet address; source of funds and change (addr1...) - `outputs` (array, required) — Array of `{ address, lovelace, assets? }` objects - `metadata` (string, optional) — JSON metadata (attached under label 674) -- `submit` (boolean, optional) — If true, sign and submit. If false/omitted, return unsigned CBOR. -**Example prompt:** "Build a transaction sending 5 ADA to addr1qx... and 3 ADA to addr1qy..." +**Example prompt:** "Build a transaction sending 5 AP3X to addr1qx... and 3 AP3X to addr1qy..." ### vector_dry_run -Simulate a transaction without submitting — returns fee estimate and validation. +Simulate a transaction without submitting — returns fee estimate and validation (keyless). **Parameters:** - `txCbor` (string, optional) — Hex CBOR of a built transaction to evaluate - `outputs` (array, optional) — If no txCbor, build a TX from these outputs and evaluate +- `changeAddress` (string, optional) — Your wallet address; required when building from outputs - `metadata` (string, optional) — JSON metadata when building from outputs -**Example prompt:** "How much would it cost to send 10 ADA to addr1qx...?" +**Example prompt:** "How much would it cost to send 10 AP3X to addr1qx...?" ### vector_get_transaction_history Get transaction history for an address via Koios indexed queries. **Parameters:** -- `address` (string, optional) — Address to query. Uses agent's wallet if omitted. +- `address` (string, required) — Address to query (addr1...) - `limit` (number, optional) — Number of transactions (default: 20, max: 50) - `offset` (number, optional) — Pagination offset (default: 0) -**Example prompt:** "Show me my recent transactions" +**Example prompt:** "Show me recent transactions for addr1qx..." -### vector_deploy_contract +### vector_build_deploy_contract -Deploy a Plutus/Aiken smart contract by locking funds at its script address. +Build an unsigned transaction deploying a Plutus/Aiken smart contract by locking funds at its script address (keyless). Sign the returned CBOR with your local signer, then broadcast with `vector_submit_transaction`. **Parameters:** +- `changeAddress` (string, required) — Your wallet address; source of funds and change (addr1...) - `scriptCbor` (string, required) — Compiled script CBOR hex - `scriptType` (string, required) — "PlutusV1", "PlutusV2", or "PlutusV3" - `initialDatum` (string, optional) — Datum CBOR hex (default: void `d87980`) -- `lovelaceAmount` (number, optional) — ADA to lock in lovelace (default: 2 ADA) +- `lovelaceAmount` (number, optional) — AP3X to lock in lovelace (default: 2 AP3X) -**Example prompt:** "Deploy this smart contract with 5 ADA locked" +**Example prompt:** "Deploy this smart contract with 5 AP3X locked" -### vector_interact_contract +### vector_build_interact_contract -Interact with a deployed smart contract — lock funds or spend from it. +Build an unsigned transaction interacting with a deployed smart contract — lock funds or spend from it (keyless). Sign the returned CBOR with your local signer, then broadcast with `vector_submit_transaction`. **Parameters:** +- `changeAddress` (string, required) — Your wallet address; source of funds, change, and the required signer for spends (addr1...) - `scriptCbor` (string, required) — Compiled script CBOR hex - `scriptType` (string, required) — "PlutusV1", "PlutusV2", or "PlutusV3" - `action` (string, required) — "spend" or "lock" - `redeemer` (string, optional) — Redeemer CBOR hex (for spend, default: void) - `datum` (string, optional) — Datum CBOR hex (for lock, default: void) -- `lovelaceAmount` (number, optional) — ADA to lock in lovelace (for lock) +- `lovelaceAmount` (number, optional) — Lovelace to lock (for lock) - `utxoRef` (object, optional) — `{ txHash, outputIndex }` for specific UTxO (for spend) - `assets` (object, optional) — Native assets for lock: `{ "unit": "quantity" }` @@ -133,19 +122,14 @@ Interact with a deployed smart contract — lock funds or spend from it. ## Safety Controls -The server enforces configurable spend limits: +The tools above are keyless and take no key material, so the server no longer enforces +spend limits on them. Spend policy is enforced by your **local signer** when it signs the +CBOR these tools return — see the security notice in the repo [README](../README.md) and +[docs/architecture/non-custodial-split.md](architecture/non-custodial-split.md). -- **Per-transaction limit** — Maximum ADA per single transaction (default: 100 ADA) -- **Daily limit** — Maximum ADA per 24-hour period (default: 500 ADA) -- **Audit log** — All transactions are logged with timestamp, amount, and recipient -- **Persistent audit log** — Audit log is written to a JSON file that survives server restarts. Daily spend is recalculated from the log on startup. - -Limits are configured via environment variables: -``` -VECTOR_SPEND_LIMIT_PER_TX=100000000 # 100 ADA in lovelace -VECTOR_SPEND_LIMIT_DAILY=500000000 # 500 ADA in lovelace -VECTOR_AUDIT_LOG_PATH=./vector-audit-log.json # Audit log file path -``` +`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. ## Network Endpoints @@ -160,8 +144,6 @@ VECTOR_AUDIT_LOG_PATH=./vector-audit-log.json # Audit log file path All tools return helpful error messages with troubleshooting tips. Common issues: -- **Invalid mnemonic** — Check VECTOR_MNEMONIC has exactly 15 or 24 words -- **Insufficient balance** — Ensure wallet has enough ADA for the transaction + fees -- **Spend limit exceeded** — Check limits with `vector_get_spend_limits` +- **Insufficient balance** — Ensure the wallet at `changeAddress` has enough AP3X for the transaction + fees - **Connection failed** — Verify Ogmios endpoint is reachable - **Invalid address** — Vector addresses start with `addr1` diff --git a/docs/architecture/non-custodial-split.md b/docs/architecture/non-custodial-split.md index 95658ba..491e997 100644 --- a/docs/architecture/non-custodial-split.md +++ b/docs/architecture/non-custodial-split.md @@ -188,7 +188,7 @@ TDD throughout: failing test before implementation, every PR. | **3** | Workspace scaffolding — pure `git mv`, zero logic change, validated by PR 1–2 CI | no | | **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 | **yes** | +| **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 | | **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` | — |