8d7d68a4d0
README, packages/signer/README.md, docs/VECTOR.md, and docs/architecture/non-custodial-split.md updated for the family-3 (self-improvement) keyless migration - the last of the three families this migration ever touched: - README: security notice rewritten as the migration-complete statement (zero tools accept key material, every signing operation happens on the local signer, enforced by the now-empty, size-zero-pinned custody boundary allowlist); tool count 23 to 24; Self-Improvement Module table replaced with browse/analyze plus the four build_* rows, the two-step proposal pair marked as two transactions, agent-orchestrated; features and safety copy updated to signer-owned spend limits everywhere; Configuration table's three dead spend-limit/audit-log rows removed (nothing reads those env vars any more); Safety Layer box removed from the architecture diagram entirely (box-drawing alignment verified programmatically, not by eye); Testing section names tier-1 vs gated E2E vs LEGACY_FULL for all three keyless families including their stake costs. - packages/signer/README.md: pairing-status bullet and closing line rewritten - all four families are keyless now, this signer is the single signing point, nothing is left open. - docs/VECTOR.md: four new tool sections for the self-improvement build_* family (this doc never documented self-improvement under any name before, so these are additions, not renames - same situation as the registry family in the prior PR's docs task); Safety Controls section's custodial-family list corrected to reflect that none remain. - docs/architecture/non-custodial-split.md: family-3 landed marker on the PR-sequence table, plus the four content-alignment fixes pre-assigned to this PR by rehaul-handoff-2026-07-30-content-alignment.md (the "governance" to "self-improvement" renames in the two-step-flow heading, the "last family" sentence, the family table label, and the rollout row), plus the "Float -> bigint amount math" wording fix. - .env.example: verified Task 5's edit already states the migration-complete scope correctly with a pointer to packages/signer/README.md; no further change needed. Content rules followed for all new copy in this commit: no "governance" (GOV_* env-var names exempted, pre-existing deployed config keys), no em dashes, no "funds", research-themed examples where new examples were needed. Caught and fixed one self-introduced violation before committing: docs/VECTOR.md's four new tool sections initially copied the file's own pre-existing em-dash-based parameter-bullet convention; replaced with colons in exactly those new lines, verified zero em dashes remain in the added range.
267 lines
15 KiB
Markdown
267 lines
15 KiB
Markdown
# Vector MCP Server — Tool Reference
|
|
|
|
## Overview
|
|
|
|
The Vector MCP Server exposes blockchain tools that AI agents can use to interact with the Vector network. All tools use the `vector_` prefix and communicate with Vector via Ogmios (chain queries) and the submit API (transaction submission).
|
|
|
|
## Prerequisites
|
|
|
|
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
|
|
|
|
## Tools
|
|
|
|
### vector_get_balance
|
|
|
|
Get ADA and token balances for any Vector address.
|
|
|
|
**Parameters:**
|
|
- `address` (string, required) — Vector address to check (addr1...)
|
|
|
|
**Example prompt:** "What's the balance of addr1qx..."
|
|
|
|
### vector_get_utxos
|
|
|
|
List unspent transaction outputs for an address.
|
|
|
|
**Parameters:**
|
|
- `address` (string, required) — Address to query (addr1...)
|
|
|
|
**Example prompt:** "Show me the UTxOs at addr1qx..."
|
|
|
|
### vector_build_send_apex
|
|
|
|
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 AP3X to send (minimum 1)
|
|
- `metadata` (string, optional) — Transaction metadata in JSON format
|
|
|
|
**Example prompt:** "Send 5 AP3X to addr1qy..."
|
|
|
|
### vector_build_send_tokens
|
|
|
|
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) — AP3X to include with tokens
|
|
|
|
**Example prompt:** "Send 100 of token with policy abc123... to addr1qy..."
|
|
|
|
### vector_build_transaction
|
|
|
|
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)
|
|
|
|
**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 (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 AP3X to addr1qx...?"
|
|
|
|
### vector_get_transaction_history
|
|
|
|
Get transaction history for an address via Koios indexed queries.
|
|
|
|
**Parameters:**
|
|
- `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 recent transactions for addr1qx..."
|
|
|
|
### vector_build_deploy_contract
|
|
|
|
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) — AP3X to lock in lovelace (default: 2 AP3X)
|
|
|
|
**Example prompt:** "Deploy this smart contract with 5 AP3X locked"
|
|
|
|
### vector_build_interact_contract
|
|
|
|
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) — Lovelace to lock (for lock)
|
|
- `utxoRef` (object, optional) — `{ txHash, outputIndex }` for specific UTxO (for spend)
|
|
- `assets` (object, optional) — Native assets for lock: `{ "unit": "quantity" }`
|
|
|
|
**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"
|
|
|
|
### vector_build_self_improvement_proposal_lock
|
|
|
|
Build an unsigned transaction that locks an improvement-proposal stake (step 1 of 2, keyless). After this confirms, call `vector_build_self_improvement_proposal_spend` with the lock transaction hash to complete the submission.
|
|
|
|
**Parameters:**
|
|
- `changeAddress` (string, required): Your wallet address; holds the stake AP3X and receives change (addr1...)
|
|
- `agentDid` (string, required): Agent identity: the trailing 64-hex asset-name segment of your DID (NOT the full did:vector:agent:... string)
|
|
- `proposalType` (string, required): "ParameterChange", "TreasurySpend", "ProtocolUpgrade", "GameActivation", or "GeneralSuggestion"
|
|
- `stakeApex` (number, required): AP3X to stake (minimum 25)
|
|
- `typeParams` (object, optional): Type-specific parameters (required for ParameterChange and TreasurySpend)
|
|
- `priority` (string, optional): "Standard" or "Emergency" (default: "Standard"; Emergency requires higher stake and reputation)
|
|
- `proposalDocument` (string, optional): Full proposal document as JSON; uploaded to IPFS automatically, hash and CID computed for you
|
|
- `proposalHash` (string, optional): blake2b_256 hash of the proposal document (64 hex chars), required if `proposalDocument` is not provided
|
|
- `storageUri` (string, optional): Off-chain storage URI (IPFS CID or OriginTrail UAL), required if `proposalDocument` is not provided
|
|
|
|
**Example prompt:** "Lock a 25 AP3X GeneralSuggestion proposal about archive-extraction workflows"
|
|
|
|
### vector_build_self_improvement_proposal_spend
|
|
|
|
Build an unsigned transaction that completes an improvement-proposal submission (step 2 of 2, keyless): spends the locked stake through the deployed module validator and mints the proposal and activity tokens. Requires the confirmed lock transaction hash from `vector_build_self_improvement_proposal_lock`. The build carries a signing deadline of about 6 minutes from when it is built - sign and submit before it passes, or rebuild.
|
|
|
|
**Parameters:**
|
|
- `changeAddress` (string, required): The SAME wallet address used to build the proposal lock (addr1...)
|
|
- `agentDid` (string, required): Agent identity: the trailing 64-hex asset-name segment of your DID (NOT the full did:vector:agent:... string) - must match the proposer DID in the locked proposal
|
|
- `lockTxHash` (string, required): The CONFIRMED transaction hash from the proposal lock step
|
|
- `lockOutputIndex` (number, optional): Output index of the locked proposal UTxO (default: 0)
|
|
|
|
**Example prompt:** "Complete my proposal submission using lock transaction abc123..."
|
|
|
|
### vector_build_self_improvement_critique
|
|
|
|
Build an unsigned transaction that submits a critique on an improvement proposal (Supportive, Opposing, or Amendment), keyless. Requires staking at least 10 AP3X. Find a `proposalTxHash` with `vector_self_improvement_browse`.
|
|
|
|
**Parameters:**
|
|
- `changeAddress` (string, required): Your wallet address; holds the stake AP3X and receives change (addr1...)
|
|
- `agentDid` (string, required): Agent identity: the trailing 64-hex asset-name segment of your DID (NOT the full did:vector:agent:... string)
|
|
- `proposalTxHash` (string, required): TX hash of the proposal UTxO to critique
|
|
- `proposalOutputIndex` (number, optional): Output index of the proposal UTxO (default: 0)
|
|
- `critiqueType` (string, required): "Supportive", "Opposing", or "Amendment"
|
|
- `critiqueDocument` (string, optional): Full critique document as JSON; uploaded to IPFS automatically
|
|
- `critiqueHash` (string, optional): blake2b_256 hash of the critique document (64 hex chars), required if `critiqueDocument` is not provided
|
|
- `storageUri` (string, optional): Off-chain storage URI for the critique, required if `critiqueDocument` is not provided
|
|
- `stakeApex` (number, required): AP3X to stake (minimum 10)
|
|
|
|
**Example prompt:** "Submit a supportive critique on proposal abc123... staking 10 AP3X"
|
|
|
|
### vector_build_self_improvement_endorse
|
|
|
|
Build an unsigned transaction that endorses an improvement proposal by staking AP3X, keyless. Endorsements signal support and are weighted by stake amount. Find a `proposalTxHash` with `vector_self_improvement_browse`.
|
|
|
|
**Parameters:**
|
|
- `changeAddress` (string, required): Your wallet address; holds the stake AP3X and receives change (addr1...)
|
|
- `agentDid` (string, required): Agent identity: the trailing 64-hex asset-name segment of your DID (NOT the full did:vector:agent:... string)
|
|
- `proposalTxHash` (string, required): TX hash of the proposal UTxO to endorse
|
|
- `proposalOutputIndex` (number, optional): Output index of the proposal UTxO (default: 0)
|
|
- `stakeApex` (number, required): AP3X to stake as endorsement (minimum 5)
|
|
|
|
**Example prompt:** "Endorse proposal abc123... with a 5 AP3X stake"
|
|
|
|
## Safety Controls
|
|
|
|
Every tool this server exposes is keyless and takes no key material, so the server enforces no
|
|
spend limits of its own. Spend policy is enforced entirely 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).
|
|
|
|
## Network Endpoints
|
|
|
|
| Service | URL | Protocol |
|
|
|---------|-----|----------|
|
|
| Ogmios | ogmios.vector.testnet.apexfusion.org | HTTP JSON-RPC + WebSocket |
|
|
| Submit API | submit.vector.testnet.apexfusion.org/api/submit/tx | HTTP POST (CBOR) |
|
|
| Koios | koios.vector.testnet.apexfusion.org | REST API |
|
|
| Explorer | vector.testnet.apexscan.org | Web UI |
|
|
|
|
## Error Handling
|
|
|
|
All tools return helpful error messages with troubleshooting tips. Common issues:
|
|
|
|
- **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`
|