jerry/apex-mcp-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: wallet/tx family is keyless - security notice, tool tables, spend-limit scope

Browse Source 
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.
This commit is contained in:
FilipBl4gojevic
2026-07-29 14:22:31 +02:00
parent dde221fdba
commit 714d4ebcd4
4 changed files with 68 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.env.example
View File

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

49
README.md
View File

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

94
docs/VECTOR.md
View File

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

2
docs/architecture/non-custodial-split.md
View File

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