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

docs: the non-custodial migration is complete - every family keyless, server holds zero key material

Browse Source 
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.
This commit is contained in:
FilipBl4gojevic
2026-07-30 18:08:46 +02:00
parent 11d1010b62
commit 8d7d68a4d0
4 changed files with 128 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
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 servers - no install
Hosted instances run on both networks, exposing all 23 tools: Hosted instances run on both networks, exposing all 24 tools:
| Network | Endpoint | | Network | Endpoint |
|---------|----------| |---------|----------|
@@ -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 claude mcp add --transport sse vector-mcp https://mcp.vector.mainnet.apexfusion.org/sse
``` ```
> **Security notice — custody.** The wallet, transaction, smart-contract, and agent-registry > **Security notice: the non-custodial migration is complete.** No tool on this hosted server
> tools are now **keyless**: `build_*` tools construct unsigned transactions from a wallet > accepts a mnemonic, private key, or any other key material. Every `build_*` tool constructs an
> *address* and never accept a mnemonic. Sign the returned CBOR with the local signer companion > unsigned transaction from a wallet *address* only, and every signing operation happens locally
> and broadcast it with `vector_submit_transaction` — your seed phrase never leaves your machine. > on your own machine, through the local signer companion. Broadcast the signed result with
> **The Self-Improvement Module (5 tools) is the only family still taking a mnemonic as a > `vector_submit_transaction` - your seed phrase never leaves your machine, and this server never
> tool-call parameter** (its keyless migration is next — see the architecture doc). For those > holds one. This is enforced mechanically, not just by convention: the builder's custody
> tools the mnemonic passes through your MCP client, your model provider, and the hosted > boundary test scans every source file for key-material vocabulary against an allowlist that is
> server's memory: use only a hot wallet holding funds you can afford to lose, and prefer > now empty and pinned at size zero, so a future change cannot silently reintroduce a mnemonic
> self-hosting until the migration completes. > parameter without failing that test by name.
> See [docs/architecture/non-custodial-split.md](docs/architecture/non-custodial-split.md). > See [docs/architecture/non-custodial-split.md](docs/architecture/non-custodial-split.md).
Self-hosting instructions are below. Self-hosting instructions are below.
@@ -42,17 +42,15 @@ stdio transport, no Provider, no egress — so a key given to it never reaches a
or your model provider. Four tools: `vector_signer_get_address`, `vector_signer_decode_transaction`, or your model provider. Four tools: `vector_signer_get_address`, `vector_signer_decode_transaction`,
`vector_signer_sign`, `vector_signer_get_spend_limits`. `vector_signer_sign`, `vector_signer_get_spend_limits`.
**Paired with this hosted builder, the full non-custodial flow is live today** for the wallet, **This signer is the single signing point for every family this server exposes.** The full
transaction, smart-contract, and agent-registry family: `vector_signer_get_address` → non-custodial flow is live for all of them: `vector_signer_get_address` → `build_*` →
`build_*` → `vector_signer_sign` → `vector_submit_transaction` → `vector_await_transaction`. No `vector_signer_sign` → `vector_submit_transaction` → `vector_await_transaction`. No step in that
step in that chain puts a mnemonic in front of this server or your model provider. The chain puts a mnemonic in front of this server or your model provider, for any tool. The
build → submit → await half is E2E-proven on Vector testnet for both: a payment self-send, and build → submit → await half is E2E-proven on Vector testnet across the wallet/tx, smart-contract,
a full register → update → deregister agent lifecycle with the 10 AP3X deposit round-tripped agent-registry, and self-improvement families, including the first keyless-built proposal
exactly; see [`packages/signer/README.md`](packages/signer/README.md#known-limitations) for submission the deployed self-improvement module validator has ever accepted; see
exactly what that testing does and does not exercise on the signer's side. **The [`packages/signer/README.md`](packages/signer/README.md#known-limitations) for exactly what that
Self-Improvement Module is not part of that pairing yet** — its 5 tools still take a mnemonic testing does and does not exercise on the signer's side.
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 See [`packages/signer/README.md`](packages/signer/README.md) for configuration, tools, and known
limitations. limitations.
@@ -61,14 +59,14 @@ limitations.
- **Wallet & queries** - balances, UTxOs, and transaction history for any address (no key material) - **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 - **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 - **Smart contracts** - deploy Plutus/Aiken validators, lock and spend UTxOs at script addresses (keyless)
- **Agent registry** - register, discover, update, transfer, and deregister on-chain AI agent identities via soulbound NFTs (keyless - build, sign locally, broadcast) - **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) - **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) - **Self-Improvement Module** - browse, submit, critique, and endorse improvement proposals, all keyless (live on Vector mainnet)
- **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) - **Safety controls** - per-identity rate limiting; spend limits for every family are enforced by the local signer, per user - the server holds no spend-limit state of its own
- **SSE transport** - HTTP server with Server-Sent Events for MCP client connectivity - **SSE transport** - HTTP server with Server-Sent Events for MCP client connectivity
## MCP Tools (23) ## MCP Tools (24)
### Wallet & Queries ### Wallet & Queries
@@ -113,10 +111,11 @@ limitations.
| Tool | Description | | Tool | Description |
|------|-------------| |------|-------------|
| `vector_self_improvement_browse` | Browse improvement proposals, critiques, and endorsements | | `vector_self_improvement_browse` | Browse improvement proposals, critiques, and endorsements |
| `vector_self_improvement_submit_proposal` | Submit an improvement proposal (stakes AP3X) |
| `vector_self_improvement_critique` | Critique a proposal - support, oppose, or propose amendments |
| `vector_self_improvement_endorse` | Endorse a proposal by staking AP3X |
| `vector_self_improvement_analyze_metrics` | Proposal metrics: activity, adoption rate, treasury health, engagement | | `vector_self_improvement_analyze_metrics` | Proposal metrics: activity, adoption rate, treasury health, engagement |
| `vector_build_self_improvement_proposal_lock` | Build an unsigned proposal-stake lock (step 1 of 2, keyless) |
| `vector_build_self_improvement_proposal_spend` | Build an unsigned proposal submission - spends the lock and mints the proposal and activity tokens (step 2 of 2, keyless). Two transactions, agent-orchestrated. |
| `vector_build_self_improvement_critique` | Build an unsigned critique on a proposal - support, oppose, or propose amendments (keyless) |
| `vector_build_self_improvement_endorse` | Build an unsigned endorsement of a proposal by staking AP3X (keyless) |
Agent DIDs follow the format: `did:vector:agent:{policyId}:{nftAssetName}` Agent DIDs follow the format: `did:vector:agent:{policyId}:{nftAssetName}`
@@ -139,9 +138,9 @@ cp .env.example .env
# Edit .env with your endpoint URLs (defaults point to Vector testnet; mainnet URLs below) # Edit .env with your endpoint URLs (defaults point to Vector testnet; mainnet URLs below)
``` ```
The wallet/tx/contract and agent-registry families are keyless: `build_*` tools take a wallet Every `build_*` tool is keyless: it takes a wallet address, never a mnemonic. No tool call
address, never a mnemonic. The Self-Improvement Module still takes a per-call mnemonic until against this server ever needs a mnemonic parameter, for any family - see the security notice
its keyless migration lands — see the security notice above. above.
### 3. Run ### 3. Run
@@ -194,15 +193,14 @@ If this instance will be reachable by anyone but you, set `MCP_AUTH_TOKENS` firs
| `VECTOR_KOIOS_URL` | Koios REST API endpoint | `https://v2.koios.vector.testnet.apexfusion.org/` | | `VECTOR_KOIOS_URL` | Koios REST API endpoint | `https://v2.koios.vector.testnet.apexfusion.org/` |
| `VECTOR_SUBMIT_URL` | Transaction submit API | `https://submit.vector.testnet.apexfusion.org/api/submit/tx` | | `VECTOR_SUBMIT_URL` | Transaction submit API | `https://submit.vector.testnet.apexfusion.org/api/submit/tx` |
| `VECTOR_EXPLORER_URL` | Block explorer base URL | `https://vector.testnet.apexscan.org` | | `VECTOR_EXPLORER_URL` | Block explorer base URL | `https://vector.testnet.apexscan.org` |
| `VECTOR_SPEND_LIMIT_PER_TX` | Max lovelace per transaction | `100000000` (100 AP3X) |
| `VECTOR_SPEND_LIMIT_DAILY` | Max lovelace per day | `500000000` (500 AP3X) |
| `VECTOR_AUDIT_LOG_PATH` | Persistent audit log file path | `./vector-audit-log.json` |
| `VECTOR_RATE_LIMIT_PER_MINUTE` | Max tool calls per minute | `60` | | `VECTOR_RATE_LIMIT_PER_MINUTE` | Max tool calls per minute | `60` |
| `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)_ | | `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 This server has no spend-limit or audit-log configuration of its own: it holds no key material
Self-Improvement family — the keyless `build_*` families (wallet/tx/contract, agent registry) for any family, so it has nothing left to limit. Every spend limit, and the audit log recording
ignore them; their spend limits are enforced by the local signer instead. it, lives in your local signer instead - see `VECTOR_SIGNER_SPEND_LIMIT_PER_TX` /
`VECTOR_SIGNER_SPEND_LIMIT_DAILY` / `VECTOR_SIGNER_AUDIT_LOG_PATH` in
[`packages/signer/README.md`](packages/signer/README.md#configuration).
> **Running a public instance?** Set `MCP_AUTH_TOKENS`. Without it every caller > **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 > is treated as one anonymous identity and shares a single rate-limit bucket, so
@@ -244,7 +242,7 @@ echo "your mnemonic words here" > packages/builder/mnemonic.txt
npm run test:integration 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 (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 the registry's register + message builds, plus a non-owner rejection path on update) 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). The full registry lifecycle (register → update → deregister) is exercised by the gated E2E 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. 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`, `registry-keyless.test.ts`, and `self-improvement-keyless.test.ts` - tier-1 suites needing no mnemonic at all, each building unsigned transactions against live public data only (`vector_build_send_tokens` is covered offline, by unit tests and the legacy suite above; `self-improvement-keyless.test.ts` covers critique, endorse, and proposal-lock builds, plus a not-found rejection path on proposal-spend). Set `VECTOR_E2E_SUBMIT=1` to additionally run each family's gated end-to-end suite, fully on-chain: `keyless-e2e.test.ts` lands one real self-send (~0.16 AP3X fee); `registry-e2e.test.ts` runs a full register → update → deregister agent lifecycle (the 10 AP3X deposit round-tripped exactly, fees only as net cost); `self-improvement-e2e.test.ts` locks and spends a real improvement proposal through the deployed module validator, then critiques and endorses it (≈48 AP3X in stakes and module minimums, plus six transaction fees, one-way - the stakes are locked by the module's own design, not lost). Set `LEGACY_FULL=1` to additionally exercise the same self-improvement lock → spend sequence inside `run.test.ts` itself (off by default, since `self-improvement-e2e.test.ts` already proves that exact path). Never runs in CI.
```bash ```bash
npm run test:smoke:signer npm run test:smoke:signer
@@ -276,13 +274,6 @@ against live chain data. **Never submits.** Never runs in CI. See
│ └────────┬───────────┘ │ │ └────────┬───────────┘ │
│ │ │ │ │ │
│ ┌────────▼───────────┐ │ │ ┌────────▼───────────┐ │
│ │ Safety Layer * │ │
│ │ - Per-tx limits │ │
│ │ - Daily limits │ │
│ │ - Audit log │ │
│ └────────┬───────────┘ │
│ │ │
│ ┌────────▼───────────┐ │
│ │ Lucid + Ogmios │ │ │ │ Lucid + Ogmios │ │
│ │ Provider │ │ │ │ Provider │ │
│ └────────┬───────────┘ │ │ └────────┬───────────┘ │
@@ -294,9 +285,9 @@ against live chain data. **Never submits.** Never runs in CI. See
└──────────────────────────┘ └──────────────────────────┘
``` ```
\* The still-custodial Self-Improvement family only — the keyless `build_*` path (wallet/tx/ No safety layer sits between the rate limiter and the provider: this server holds no key
contract, agent registry) never reaches the Safety Layer; its spend limits are enforced by the material for any family, so it has no spend limits of its own left to enforce. Every spend
local signer instead. limit lives in your local signer instead.
## About Vector ## About Vector

71
docs/VECTOR.md
View File

@@ -182,16 +182,71 @@ Build an unsigned transaction that sends an on-chain message to a registered age
**Example prompt:** "Send an inquiry message to did:vector:agent:... asking about pricing" **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 ## Safety Controls
The tools above are keyless and take no key material, so the server no longer enforces Every tool this server exposes is keyless and takes no key material, so the server enforces no
spend limits on them. Spend policy is enforced by your **local signer** when it signs the spend limits of its own. Spend policy is enforced entirely by your **local signer** when it
CBOR these tools return — see the security notice in the repo [README](../README.md) and signs the CBOR these tools return - see the security notice in the repo [README](../README.md)
[docs/architecture/non-custodial-split.md](architecture/non-custodial-split.md). and [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 one remaining custodial tool family (self-improvement) until its own
keyless migration lands.
## Network Endpoints ## Network Endpoints

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

@@ -121,7 +121,7 @@ interface Policy {
**Accepted trade-off of the 4-call shape:** the signer records **intent to spend** at signing time, not confirmed submission. If a submit later fails, the audit log over-counts. Conservative, therefore acceptable — and it is the price of the signer having no network access. Documented, not hidden. **Accepted trade-off of the 4-call shape:** the signer records **intent to spend** at signing time, not confirmed submission. If a submit later fails, the audit log over-counts. Conservative, therefore acceptable — and it is the price of the signer having no network access. Documented, not hidden.
### Two-step governance flow ### Two-step self-improvement flow
`submit_proposal` is a lock-then-spend pair with a confirmation wait between. Keyless, that orchestration becomes explicit: `submit_proposal` is a lock-then-spend pair with a confirmation wait between. Keyless, that orchestration becomes explicit:
@@ -130,7 +130,7 @@ build_self_improvement_proposal_lock → sign → submit → await_transaction
→ build_self_improvement_proposal_spend(lockTxHash) → sign → submit → build_self_improvement_proposal_spend(lockTxHash) → sign → submit
``` ```
This is why governance is the last family: the LLM must drive a stateful, multi-transaction sequence. This is why self-improvement is the last family: the LLM must drive a stateful, multi-transaction sequence.
## 7. Tool inventory ## 7. Tool inventory
@@ -142,7 +142,7 @@ This is why governance is the last family: the LLM must drive a stateful, multi-
| Build — tx (3) | `build_send_apex`, `build_send_tokens`, `build_transaction` | | Build — tx (3) | `build_send_apex`, `build_send_tokens`, `build_transaction` |
| Build — contracts (2) | `build_deploy_contract`, `build_interact_contract` | | Build — contracts (2) | `build_deploy_contract`, `build_interact_contract` |
| Build — registry (5) | `build_register_agent`, `build_update_agent`, `build_transfer_agent`, `build_deregister_agent`, `build_message_agent` | | Build — registry (5) | `build_register_agent`, `build_update_agent`, `build_transfer_agent`, `build_deregister_agent`, `build_message_agent` |
| Build — governance (4) | `build_self_improvement_proposal_lock`, `build_self_improvement_proposal_spend`, `build_self_improvement_critique`, `build_self_improvement_endorse` | | Build — self-improvement (4) | `build_self_improvement_proposal_lock`, `build_self_improvement_proposal_spend`, `build_self_improvement_critique`, `build_self_improvement_endorse` |
| Chain ops (2, new) | `submit_transaction`, `await_transaction` | | Chain ops (2, new) | `submit_transaction`, `await_transaction` |
**Signer — 4 tools, holds the key.** **Signer — 4 tools, holds the key.**
@@ -190,7 +190,7 @@ TDD throughout: failing test before implementation, every PR.
| **5** | Builder hardening: auth (enforced when configured), per-identity rate limits, `submit_transaction`, `await_transaction` | 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** | | **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` ✅ **(landed — this PR)** | 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 | | **8** | **Family 3 — self-improvement keyless.** Plus env-driven ref-UTxO config and a CBOR encoding fix ✅ **(landed — this PR)** | yes |
| **9** | Mainnet cutover: README, security-page correction, deliberate `workflow_dispatch` | — | | **9** | Mainnet cutover: README, security-page correction, deliberate `workflow_dispatch` | — |
**PR 4 is the review that matters.** It is additive, self-contained, and *is* the security boundary. It breaks nothing while it is reviewed. **PR 4 is the review that matters.** It is additive, self-contained, and *is* the security boundary. It breaks nothing while it is reviewed.
@@ -207,7 +207,7 @@ TDD throughout: failing test before implementation, every PR.
| D | `min(1)` APEX floor → real dust floor | | D | `min(1)` APEX floor → real dust floor |
| E | Endpoint URLs in error text | | E | Endpoint URLs in error text |
| F | SSE → Streamable HTTP | | F | SSE → Streamable HTTP |
| G | Float → bigint money math | | G | Float → bigint amount math |
| H | Dependency updates | | H | Dependency updates |
### Dependency graph ### Dependency graph

44
packages/signer/README.md
View File

@@ -145,29 +145,27 @@ over-counts, which refuses too much rather than too little.
transactions, but an injected agent can still cause any transaction *within* policy. transactions, but an injected agent can still cause any transaction *within* policy.
Recipient allowlisting is the next lever. Recipient allowlisting is the next lever.
- **Pairing this signer with the hosted builder now removes the custody exposure it was - **Pairing this signer with the hosted builder now removes the custody exposure it was
designed to fix — for the wallet, transaction, smart-contract, and agent-registry family.** designed to fix, for every family this server exposes.** The signer's own four tools are
The signer's own four tools are complete and independently verified end to end against live complete and independently verified end to end against live chain data
chain data (`test/integration/roundtrip.test.ts`), and the hosted *builder's* tools in these (`test/integration/roundtrip.test.ts`), and the hosted *builder's* tools are keyless across
families are keyless: `vector_build_send_apex`, `vector_build_send_tokens`, the board: every `build_*` tool, across the wallet/transaction, smart-contract, agent-registry,
`vector_build_transaction`, `vector_build_deploy_contract`, `vector_build_interact_contract`, and self-improvement families, takes a wallet *address* and never a mnemonic, and
`vector_build_register_agent`, `vector_build_update_agent`, `vector_build_transfer_agent`, `vector_submit_transaction` / `vector_await_transaction` complete the round trip. The
`vector_build_deregister_agent`, and `vector_build_message_agent` all take a wallet *address*, build → sign → submit → await pipeline is E2E-proven on Vector testnet across all four
never a mnemonic, and `vector_submit_transaction` / `vector_await_transaction` complete the families: an AP3X self-send (`packages/builder/test/integration/keyless-e2e.test.ts`), a full
round trip. The pipeline — hosted keyless build → sign → submit → await — is E2E-proven on register → update → deregister agent lifecycle with the 10 AP3X deposit round-tripped exactly
Vector testnet for both: a payment self-send (`registry-e2e.test.ts`), and a full improvement-proposal lock → spend sequence through the
(`packages/builder/test/integration/keyless-e2e.test.ts`) and a full register → update → deployed self-improvement module validator, followed by a critique and an endorsement
deregister agent lifecycle with the 10 AP3X deposit round-tripped exactly (`self-improvement-e2e.test.ts`) - the first keyless-built, validated proposal submission that
(`registry-e2e.test.ts`). Both sign with the same CML primitives `sign.ts` uses (hash the validator has ever accepted. All three E2E suites sign with the same CML primitives `sign.ts`
body, produce a vkey witness, attach it — explicitly a stand-in for calling 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 `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 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` 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 and the smoke tests above). **Nothing is left open: this was the last custodial family.** The
still require your mnemonic as a call parameter, so pairing this signer with the builder does non-custodial migration described in
not yet cover them. That migration is tracked separately in
[`docs/architecture/non-custodial-split.md`](../../docs/architecture/non-custodial-split.md) [`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 that one is complete.
family accurately.
## Running it ## Running it
@@ -193,10 +191,10 @@ example):
} }
``` ```
Register it alongside the hosted builder so an agent has both sets of tools available. For the Register it alongside the hosted builder so an agent has both sets of tools available. This
wallet, transaction, smart-contract, and agent-registry family, this pairing keeps your pairing keeps your mnemonic off the hosted server for every family it exposes: wallet,
mnemonic off the hosted server today — both halves are ready. See the last bullet under Known transaction, smart-contract, agent-registry, and self-improvement alike. See the last bullet
limitations above for what's still open: the Self-Improvement Module. under Known limitations above for the full evidence.
## Testing ## Testing