@floatonnear/mcp 0.0.0-stage → 0.1.0

package/dist/quote.js

@@ -0,0 +1,159 @@
+/**
+ * Getting a cross-chain quote, and signing the binding the vault verifies.
+ *
+ * A cross-chain payment is an ordinary NEP-141 transfer on NEAR to a ONE-TIME
+ * deposit address; a NEAR Intents solver delivers the destination asset and
+ * prices the far chain's gas into the quote. No MPC signature, no derived
+ * address, no ETH to keep topped up.
+ *
+ * The catch is that the deposit address is unpredictable and single-use, so it
+ * can never be on the vault's payee allowlist. The vault checks the allowlist
+ * against the final payee and then sends the money somewhere it cannot connect
+ * back to that payee. If an agent could choose that address, the allowlist
+ * would be decorative — quote a swap paying yourself and the vault funds it
+ * with every other check passing.
+ *
+ * So a key the vault owner registered signs the binding between payee and
+ * deposit address, and the contract refuses any Intents payment without it.
+ * This module is the holder of that key. It is a TRUSTED PRODUCER: whoever
+ * runs it can redirect any Intents payment the budget allows, which is why it
+ * belongs on the operator's machine and not on the ones agents run on.
+ */
+import { ed25519 } from "@noble/curves/ed25519";
+export const ONE_CLICK_URL = process.env.ONE_CLICK_URL ?? "https://1click.chaindefuser.com";
+/** Mainnet asset ids, from GET /v0/tokens. Intents has no testnet. */
+export const ASSETS = {
+    usdcNear: "nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1",
+    usdcBase: "nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near",
+};
+// ---------------------------------------------------------------- borsh
+/**
+ * Borsh, hand-rolled, because exactly one struct crosses this boundary and a
+ * dependency would be more surface than the twenty lines below.
+ *
+ * It must match `QuoteBinding` in contracts/vault/src/types.rs BYTE FOR BYTE.
+ * If it does not, no signature ever verifies, and the failure is silent and
+ * total — indistinguishable from a wrong key. The same vector is asserted in
+ * `quote_binding_borsh_vector` on the Rust side and in quote.test.ts here, so
+ * a field reorder breaks a test rather than the rail.
+ */
+const u32le = (n) => {
+    const b = new Uint8Array(4);
+    new DataView(b.buffer).setUint32(0, n, true);
+    return b;
+};
+const u64le = (n) => {
+    const b = new Uint8Array(8);
+    new DataView(b.buffer).setBigUint64(0, n, true);
+    return b;
+};
+/** borsh u128: 16 bytes little-endian. */
+const u128le = (n) => {
+    const b = new Uint8Array(16);
+    const dv = new DataView(b.buffer);
+    dv.setBigUint64(0, n & 0xffffffffffffffffn, true);
+    dv.setBigUint64(8, n >> 64n, true);
+    return b;
+};
+/** borsh string: u32 length prefix, then utf8. The prefix is what makes the
+ *  encoding unambiguous — a plain concatenation would let ("alic","ebob") and
+ *  ("alice","bob") produce identical bytes and sign each other's quotes. */
+const str = (s) => {
+    const utf8 = new TextEncoder().encode(s);
+    return concat(u32le(utf8.length), utf8);
+};
+function concat(...parts) {
+    const total = parts.reduce((n, p) => n + p.length, 0);
+    const out = new Uint8Array(total);
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+/** Field order is the struct's declaration order; borsh has no field names. */
+export function encodeBinding(b) {
+    return concat(str(b.vault), str(b.requestId), str(b.token), u128le(b.amount), str(b.payee), str(b.depositAddress), u64le(b.deadlineNs));
+}
+export function signBinding(b, secretKey) {
+    if (secretKey.length !== 32) {
+        throw new Error(`quote signer key must be 32 bytes, got ${secretKey.length}`);
+    }
+    return ed25519.sign(encodeBinding(b), secretKey);
+}
+export function publicKeyOf(secretKey) {
+    return ed25519.getPublicKey(secretKey);
+}
+export const toBase64 = (b) => Buffer.from(b).toString("base64");
+/**
+ * Ask 1Click what it costs to deliver `amountOut` to `payee` on the
+ * destination chain.
+ *
+ * EXACT_OUTPUT, deliberately. A payment is a promise about what the PAYEE
+ * receives; EXACT_INPUT would deliver "about a dollar" and leave the agent
+ * unable to settle an invoice. The vault is then charged `amountIn`, which is
+ * what actually leaves it — so the budget governs real outflow, not the
+ * nominal figure.
+ */
+export async function getQuote(opts) {
+    const body = {
+        dry: opts.dry ?? false,
+        swapType: "EXACT_OUTPUT",
+        slippageTolerance: opts.slippageBps ?? 100,
+        originAsset: opts.originAsset ?? ASSETS.usdcNear,
+        depositType: "ORIGIN_CHAIN",
+        destinationAsset: opts.destinationAsset ?? ASSETS.usdcBase,
+        amount: opts.amountOut.toString(),
+        refundTo: opts.refundTo,
+        refundType: "ORIGIN_CHAIN",
+        recipient: opts.payee,
+        recipientType: "DESTINATION_CHAIN",
+        deadline: opts.deadline.toISOString().replace(/\.\d{3}Z$/, "Z"),
+    };
+    const r = await fetch(`${ONE_CLICK_URL}/v0/quote`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            accept: "application/json",
+            ...(opts.jwt ? { authorization: `Bearer ${opts.jwt}` } : {}),
+        },
+        body: JSON.stringify(body),
+    });
+    const text = await r.text();
+    if (!r.ok)
+        throw new Error(`1Click HTTP ${r.status}: ${text.slice(0, 220)}`);
+    let j;
+    try {
+        j = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`1Click returned non-JSON: ${text.slice(0, 160)}`);
+    }
+    const q = j.quote;
+    if (!q)
+        throw new Error(`1Click returned no quote: ${text.slice(0, 220)}`);
+    // A dry quote has no deposit address — it is a price, not an instruction.
+    // Treating one as live would send real money to `undefined`.
+    const depositAddress = j.quote?.depositAddress ?? j.depositAddress;
+    if (!opts.dry && !depositAddress) {
+        throw new Error("1Click returned no depositAddress for a live quote");
+    }
+    return {
+        depositAddress: depositAddress ?? "",
+        amountIn: BigInt(q.amountIn),
+        amountOut: BigInt(q.amountOut),
+        deadlineNs: BigInt(opts.deadline.getTime()) * 1000000n,
+        timeEstimateSec: Number(q.timeEstimate ?? 0),
+    };
+}
+/** The `route` argument for a cross-chain payment. */
+export function intentsRoute(depositAddress, deadlineNs, signature) {
+    return {
+        intents: {
+            deposit_address: depositAddress,
+            quote_deadline_ns: deadlineNs.toString(),
+            signature: toBase64(signature),
+        },
+    };
+}

package/dist/rpc.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Read path and small helpers.
+ *
+ * Views go over raw JSON-RPC rather than through a client library, for one
+ * reason that matters: they need NO key. The server is fully useful with zero
+ * secrets configured — reads and payload planning work, and only `vault_pay`
+ * requires an agent key. Keeping the read path dependency-free means a
+ * misconfigured or absent key cannot break it.
+ */
+/**
+ * NOT `rpc.testnet.near.org`. That endpoint now answers every request with
+ * HTTP error -429 and the text "THIS ENDPOINT IS DEPRECATED! STOP USING IT
+ * NOW!" — observed 2026-10-26. It fails closed for reads, which would make the
+ * whole product look broken for anyone who left the default in place.
+ *
+ * Overridable with NEAR_VAULT_RPC_URL; providers are listed at
+ * https://docs.near.org/api/rpc/providers
+ */
+export declare const DEFAULT_RPC_URL = "https://test.rpc.fastnear.com";
+export declare function encodeArgs(args: unknown): string;
+interface RawViewResponse {
+    result?: number[];
+    error?: unknown;
+}
+/**
+ * Decode a `call_function` response.
+ *
+ * NEAR returns the value as an array of byte values. The failure mode worth
+ * guarding is an error shape that decodes to nothing: `undefined` reads as "no
+ * data" when it actually means "the call failed", and a caller would treat an
+ * exhausted budget and a broken RPC identically.
+ */
+export declare function decodeViewResult<T = unknown>(res: RawViewResponse): T;
+export declare function viewFunction<T = unknown>(rpcUrl: string, contractId: string, methodName: string, args?: unknown): Promise<T>;
+/** One access key as NEAR reports it. */
+export interface AccessKeyInfo {
+    public_key: string;
+    access_key: {
+        nonce: number;
+        permission: "FullAccess" | {
+            FunctionCall: {
+                allowance: string | null;
+                receiver_id: string;
+                method_names: string[];
+            };
+        };
+    };
+}
+/**
+ * Every access key on an account, read from the chain.
+ *
+ * This exists so the UI can state the agent key restriction as an OBSERVATION
+ * rather than a claim. "Restricted to request_payment" rendered from a
+ * hardcoded string would stay on screen even if the key were actually
+ * full-access — and that is the one thing a reader of that page most needs to
+ * be true.
+ */
+export declare function viewAccessKeys(rpcUrl: string, accountId: string): Promise<AccessKeyInfo[]>;
+export interface AgentCreds {
+    agentId: string;
+    agentKey: string;
+}
+/**
+ * Both halves or neither. Failing here with the variable NAMES beats throwing a
+ * TypeError three frames deeper, and beats silently signing with the wrong
+ * account.
+ */
+export declare function requireAgentKey(env: {
+    agentId?: string;
+    agentKey?: string;
+}): AgentCreds;
+/**
+ * A request id the contract will accept.
+ *
+ * `is_valid_request_id` allows 1..=64 of [A-Za-z0-9._:-]. A raw UUID is fine;
+ * a timestamp with a space, or anything brace-wrapped, would be rejected
+ * on-chain AFTER signing — which costs gas to learn.
+ */
+export declare function newRequestId(): string;
+export {};

package/dist/rpc.js

@@ -0,0 +1,134 @@
+/**
+ * Read path and small helpers.
+ *
+ * Views go over raw JSON-RPC rather than through a client library, for one
+ * reason that matters: they need NO key. The server is fully useful with zero
+ * secrets configured — reads and payload planning work, and only `vault_pay`
+ * requires an agent key. Keeping the read path dependency-free means a
+ * misconfigured or absent key cannot break it.
+ */
+import { randomUUID } from "node:crypto";
+/**
+ * NOT `rpc.testnet.near.org`. That endpoint now answers every request with
+ * HTTP error -429 and the text "THIS ENDPOINT IS DEPRECATED! STOP USING IT
+ * NOW!" — observed 2026-10-26. It fails closed for reads, which would make the
+ * whole product look broken for anyone who left the default in place.
+ *
+ * Overridable with NEAR_VAULT_RPC_URL; providers are listed at
+ * https://docs.near.org/api/rpc/providers
+ */
+export const DEFAULT_RPC_URL = "https://test.rpc.fastnear.com";
+export function encodeArgs(args) {
+    // Explicit utf8: a memo is free text, goes on-chain, and a latin-1
+    // truncation here would corrupt it silently.
+    return Buffer.from(JSON.stringify(args), "utf8").toString("base64");
+}
+/**
+ * Decode a `call_function` response.
+ *
+ * NEAR returns the value as an array of byte values. The failure mode worth
+ * guarding is an error shape that decodes to nothing: `undefined` reads as "no
+ * data" when it actually means "the call failed", and a caller would treat an
+ * exhausted budget and a broken RPC identically.
+ */
+export function decodeViewResult(res) {
+    if (res.error !== undefined && res.error !== null) {
+        const e = res.error;
+        const detail = typeof res.error === "string"
+            ? res.error
+            : [e.message, typeof e.data === "string" ? e.data : JSON.stringify(e.data)]
+                .filter(Boolean)
+                .join(": ");
+        throw new Error(`view call failed: ${detail}`);
+    }
+    if (!Array.isArray(res.result)) {
+        throw new Error(`unexpected RPC response: neither a result nor an error (${JSON.stringify(res).slice(0, 200)})`);
+    }
+    return JSON.parse(Buffer.from(res.result).toString("utf8"));
+}
+export async function viewFunction(rpcUrl, contractId, methodName, args = {}) {
+    const body = {
+        jsonrpc: "2.0",
+        id: "near-vault-mcp",
+        method: "query",
+        params: {
+            request_type: "call_function",
+            finality: "final",
+            account_id: contractId,
+            method_name: methodName,
+            args_base64: encodeArgs(args),
+        },
+    };
+    const r = await fetch(rpcUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (!r.ok)
+        throw new Error(`RPC ${rpcUrl} returned HTTP ${r.status}`);
+    const json = (await r.json());
+    if (json.error)
+        return decodeViewResult({ error: json.error });
+    return decodeViewResult(json.result ?? {});
+}
+/**
+ * Every access key on an account, read from the chain.
+ *
+ * This exists so the UI can state the agent key restriction as an OBSERVATION
+ * rather than a claim. "Restricted to request_payment" rendered from a
+ * hardcoded string would stay on screen even if the key were actually
+ * full-access — and that is the one thing a reader of that page most needs to
+ * be true.
+ */
+export async function viewAccessKeys(rpcUrl, accountId) {
+    const r = await fetch(rpcUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: "near-vault-mcp",
+            method: "query",
+            params: { request_type: "view_access_key_list", finality: "final", account_id: accountId },
+        }),
+    });
+    if (!r.ok)
+        throw new Error(`RPC ${rpcUrl} returned HTTP ${r.status}`);
+    const json = (await r.json());
+    if (json.error)
+        throw new Error(`access key list failed: ${json.error.message ?? "unknown"}`);
+    return json.result?.keys ?? [];
+}
+/**
+ * Both halves or neither. Failing here with the variable NAMES beats throwing a
+ * TypeError three frames deeper, and beats silently signing with the wrong
+ * account.
+ */
+export function requireAgentKey(env) {
+    // Name EVERY missing variable, not just the first. A message that reports
+    // half the problem buys a second failed attempt.
+    if (!env.agentId && !env.agentKey) {
+        throw new Error("Paying requires NEAR_VAULT_AGENT_ID and NEAR_VAULT_AGENT_KEY, and neither is set. " +
+            "Reads and payload planning work without them; only paying needs them. " +
+            "The key must be the restricted one issued by create_agent_account — never a " +
+            "full-access key.");
+    }
+    if (!env.agentId) {
+        throw new Error("NEAR_VAULT_AGENT_ID is not set, so there is no agent account to pay from.");
+    }
+    if (!env.agentKey) {
+        throw new Error("NEAR_VAULT_AGENT_KEY is not set. This must be the restricted key issued by " +
+            "create_agent_account — it can call only request_payment on the vault, cannot " +
+            "call other contracts, and cannot attach a deposit. Never put a full-access key here.");
+    }
+    return { agentId: env.agentId, agentKey: env.agentKey };
+}
+/**
+ * A request id the contract will accept.
+ *
+ * `is_valid_request_id` allows 1..=64 of [A-Za-z0-9._:-]. A raw UUID is fine;
+ * a timestamp with a space, or anything brace-wrapped, would be rejected
+ * on-chain AFTER signing — which costs gas to learn.
+ */
+export function newRequestId() {
+    return randomUUID();
+}

package/dist/server.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * MCP server for the hierarchical budget vault.
+ *
+ * Trust model, which is the whole point of the split below:
+ *
+ *   READ tools      no key at all, raw JSON-RPC
+ *   PAY tool        signs with the agent's RESTRICTED key — request_payment
+ *                   on this vault only, no deposit possible
+ *   PLAN tools      emit UNSIGNED payloads for the human's wallet; this
+ *                   server never signs anything that changes policy
+ *
+ * Configure with:
+ *   NEAR_VAULT_CONTRACT        required
+ *   NEAR_VAULT_RPC_URL         default https://test.rpc.fastnear.com
+ *   NEAR_VAULT_TOKEN           default token for pay/budget calls
+ *   NEAR_VAULT_TOKEN_DECIMALS  default 6
+ *   NEAR_VAULT_AGENT_ID        only needed to PAY
+ *   NEAR_VAULT_AGENT_KEY       only needed to PAY. The restricted key.
+ */
+export {};

package/dist/server.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * MCP server for the hierarchical budget vault.
+ *
+ * Trust model, which is the whole point of the split below:
+ *
+ *   READ tools      no key at all, raw JSON-RPC
+ *   PAY tool        signs with the agent's RESTRICTED key — request_payment
+ *                   on this vault only, no deposit possible
+ *   PLAN tools      emit UNSIGNED payloads for the human's wallet; this
+ *                   server never signs anything that changes policy
+ *
+ * Configure with:
+ *   NEAR_VAULT_CONTRACT        required
+ *   NEAR_VAULT_RPC_URL         default https://test.rpc.fastnear.com
+ *   NEAR_VAULT_TOKEN           default token for pay/budget calls
+ *   NEAR_VAULT_TOKEN_DECIMALS  default 6
+ *   NEAR_VAULT_AGENT_ID        only needed to PAY
+ *   NEAR_VAULT_AGENT_KEY       only needed to PAY. The restricted key.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { fromBaseUnits, toBaseUnits } from "./amounts.js";
+import { DEFAULT_GAS_TGAS, planAddNode, planCreateAgentAccount, planFreezeNode, planPurgeSettled, planSetCooldown, planSetNodeCaps, planSetPaused, planSetRecipients, toCliCommand, } from "./payloads.js";
+import { DEFAULT_RPC_URL, newRequestId, requireAgentKey, viewFunction } from "./rpc.js";
+import { buildRoute, sendRequestPayment } from "./sign.js";
+import { getQuote, signBinding, toBase64 } from "./quote.js";
+/** How long a quote stays valid. Long enough to sign and send, short
+ *  enough that a stale price is not honoured. */
+const QUOTE_TTL_MS = 20 * 60 * 1000;
+const cfg = {
+    vault: process.env.NEAR_VAULT_CONTRACT ?? "",
+    rpcUrl: process.env.NEAR_VAULT_RPC_URL ?? DEFAULT_RPC_URL,
+    token: process.env.NEAR_VAULT_TOKEN ?? "",
+    decimals: Number(process.env.NEAR_VAULT_TOKEN_DECIMALS ?? "6"),
+    agentId: process.env.NEAR_VAULT_AGENT_ID,
+    agentKey: process.env.NEAR_VAULT_AGENT_KEY,
+    network: process.env.NEAR_VAULT_NETWORK ?? "testnet",
+};
+function requireVault() {
+    if (!cfg.vault)
+        throw new Error("NEAR_VAULT_CONTRACT is not set");
+    return cfg.vault;
+}
+function tokenFor(t) {
+    const token = t ?? cfg.token;
+    if (!token)
+        throw new Error("no token given and NEAR_VAULT_TOKEN is not set");
+    return token;
+}
+const text = (s) => ({ content: [{ type: "text", text: s }] });
+const json = (v) => text(JSON.stringify(v, null, 2));
+/** Payload + summary + warnings + a runnable command, so approving needs no trust in this server. */
+function renderPlan(p) {
+    return json({
+        action: p.methodName,
+        summary: p.summary,
+        warnings: p.warnings,
+        unsigned_payload: {
+            receiver_id: p.receiverId,
+            method_name: p.methodName,
+            args: p.args,
+            gas_tgas: p.gasTgas,
+            deposit_yocto: p.depositYocto,
+        },
+        approve_with: toCliCommand(p, cfg.network),
+        note: "This server did NOT sign this. Review the summary, then run the command " +
+            "or approve the payload in your wallet.",
+    });
+}
+const limitShape = z
+    .array(z.object({
+    token: z.string(),
+    dailyCap: z.string().describe('human units, e.g. "1000"'),
+    perTxCap: z.string().describe('human units, e.g. "250"'),
+    decimals: z.number().int().min(0).max(38).default(6),
+}))
+    .min(1);
+const server = new McpServer({ name: "near-vault", version: "0.1.0" });
+// ----------------------------------------------------------------- reads
+server.tool("vault_tree", "Read the whole budget tree: every node, its caps, parent, bound agent account, cooldown and freeze state. No key required.", {}, async () => json(await viewFunction(cfg.rpcUrl, requireVault(), "get_tree", {})));
+server.tool("vault_budget", "Read one node's budget for a UTC day: cap, executed, in-flight (pending) and available, in human units. Omit `day` for today. No key required.", {
+    nodeId: z.number().int().min(0),
+    token: z.string().optional(),
+    day: z.number().int().optional(),
+}, async ({ nodeId, token, day }) => {
+    const b = (await viewFunction(cfg.rpcUrl, requireVault(), "get_node_budget", {
+        node_id: nodeId,
+        token: tokenFor(token),
+        day: day ?? null,
+    }));
+    if (!b)
+        return text(`node ${nodeId} has no limit for that token`);
+    const d = cfg.decimals;
+    return json({
+        node_id: nodeId,
+        day: b.day,
+        daily_cap: fromBaseUnits(BigInt(b.daily_cap), d),
+        executed: fromBaseUnits(BigInt(b.executed), d),
+        pending: fromBaseUnits(BigInt(b.pending), d),
+        available: fromBaseUnits(BigInt(b.available), d),
+    });
+});
+server.tool("vault_request", "Read one stored payment request: status, reason code, amount, the ancestor chain it charged, and the UTC day it was reserved against. No key required.", { requestId: z.string() }, async ({ requestId }) => json(await viewFunction(cfg.rpcUrl, requireVault(), "get_request", { request_id: requestId })));
+server.tool("vault_config", "Read vault config: owner, paused, strict-vs-overcommit allocation, node count, and clock mode. No key required.", {}, async () => json(await viewFunction(cfg.rpcUrl, requireVault(), "get_config", {})));
+// ------------------------------------------------------------------- pay
+server.tool("vault_pay", "Send a payment from the agent's node. Signs with the agent's RESTRICTED key, which can call only request_payment on this vault and cannot attach a deposit. The contract checks the per-tx cap, the daily cap at EVERY level of the budget tree, the cooldown and the payee allowlist before any value moves.", {
+    amount: z.string().describe('human units, e.g. "12.50"'),
+    recipient: z.string(),
+    memo: z.string().max(256).default(""),
+    token: z.string().optional(),
+    requestId: z.string().optional().describe("omit to generate one"),
+    rail: z
+        .enum(["near", "intents"])
+        .default("near")
+        .describe("near = NEP-141 transfer on NEAR, proves settlement. intents = cross-chain: the vault transfers on NEAR to a solver's one-time deposit address and the solver delivers on the destination chain. BOTH run the same hierarchical budget check and the same payee allowlist."),
+    destinationAsset: z
+        .string()
+        .optional()
+        .describe("1Click asset id for rail=intents. Defaults to USDC on Base."),
+}, async ({ amount, recipient, memo, token, requestId, rail, destinationAsset }) => {
+    const creds = requireAgentKey(cfg);
+    const id = requestId ?? newRequestId();
+    const vault = requireVault();
+    let route = "near_direct";
+    let amountIn = toBaseUnits(amount, cfg.decimals);
+    if (rail === "intents") {
+        // The agent cannot build this route. It needs a quote AND a signature
+        // from the key the vault owner registered — and that key deliberately
+        // does not live where agents run, because whoever holds it can bind any
+        // deposit address to any payee. So this path only works when the MCP
+        // server is the operator's own.
+        const signerHex = process.env.FLOAT_QUOTE_SIGNER_KEY;
+        if (!signerHex) {
+            throw new Error("rail=intents needs FLOAT_QUOTE_SIGNER_KEY (32-byte hex). " +
+                "That key binds a payee to a deposit address, so it belongs to the " +
+                "vault operator, not to an agent. Without it the cross-chain rail is closed.");
+        }
+        const sk = Uint8Array.from(Buffer.from(signerHex.replace(/^0x/, ""), "hex"));
+        // EXACT_OUTPUT: `amount` is what the PAYEE receives. What leaves the
+        // vault is the quote's amountIn, and that is what the budget is charged
+        // — so the tree governs real outflow, not the nominal figure.
+        const deadline = new Date(Date.now() + QUOTE_TTL_MS);
+        const q = await getQuote({
+            amountOut: toBaseUnits(amount, cfg.decimals),
+            payee: recipient,
+            refundTo: vault,
+            destinationAsset,
+            deadline,
+        });
+        amountIn = q.amountIn;
+        const signature = signBinding({
+            vault,
+            requestId: id,
+            token: tokenFor(token),
+            amount: q.amountIn,
+            payee: recipient,
+            depositAddress: q.depositAddress,
+            deadlineNs: q.deadlineNs,
+        }, sk);
+        route = buildRoute("intents", {
+            depositAddress: q.depositAddress,
+            quoteDeadlineNs: q.deadlineNs.toString(),
+            signature: toBase64(signature),
+        });
+    }
+    const out = await sendRequestPayment({
+        rpcUrl: cfg.rpcUrl,
+        vault,
+        agentId: creds.agentId,
+        agentKey: creds.agentKey,
+        requestId: id,
+        token: tokenFor(token),
+        amount: amountIn,
+        recipient,
+        memo,
+        gasTgas: DEFAULT_GAS_TGAS,
+        route,
+    });
+    return json(out);
+});
+// ------------------------------------------------------- plans (unsigned)
+server.tool("vault_plan_add_node", "Build an UNSIGNED payload to create a budget node. Pass parent=null for the root. Not signed by this server.", {
+    parent: z.number().int().min(0).nullable(),
+    label: z.string(),
+    limits: limitShape,
+    cooldownSec: z.number().int().min(0).default(0),
+    recipients: z.array(z.string()).nullable().default(null),
+}, async ({ parent, label, limits, cooldownSec, recipients }) => renderPlan(planAddNode(requireVault(), parent, label, limits, cooldownSec, recipients)));
+server.tool("vault_plan_set_caps", "Build an UNSIGNED payload to change a node's daily and per-payment caps. Not signed by this server.", { nodeId: z.number().int().min(0), limits: limitShape }, async ({ nodeId, limits }) => renderPlan(planSetNodeCaps(requireVault(), nodeId, limits)));
+server.tool("vault_plan_create_agent", "Build an UNSIGNED payload to create an agent sub-account with ONE key restricted to request_payment on this vault. Generate the keypair yourself and pass only the public half. Not signed by this server.", {
+    nodeId: z.number().int().min(0),
+    subLabel: z.string(),
+    publicKey: z.string().describe("ed25519:..."),
+    keyAllowanceNear: z.string().default("2").describe("gas allowance in NEAR; floor is 0.5"),
+}, async ({ nodeId, subLabel, publicKey, keyAllowanceNear }) => renderPlan(planCreateAgentAccount(requireVault(), nodeId, subLabel, publicKey, keyAllowanceNear)));
+server.tool("vault_plan_freeze", "Build an UNSIGNED payload to freeze or unfreeze a node. Freezing blocks the node AND its whole subtree. Not signed by this server.", { nodeId: z.number().int().min(0), frozen: z.boolean() }, async ({ nodeId, frozen }) => renderPlan(planFreezeNode(requireVault(), nodeId, frozen)));
+server.tool("vault_plan_set_recipients", "Build an UNSIGNED payload to set a node's payee allowlist. This REPLACES the inherited list rather than adding to it; pass null to inherit. Not signed by this server.", { nodeId: z.number().int().min(0), recipients: z.array(z.string()).nullable() }, async ({ nodeId, recipients }) => renderPlan(planSetRecipients(requireVault(), nodeId, recipients)));
+server.tool("vault_plan_set_cooldown", "Build an UNSIGNED payload to set the minimum seconds between a node's payments. Not signed by this server.", { nodeId: z.number().int().min(0), cooldownSec: z.number().int().min(0) }, async ({ nodeId, cooldownSec }) => renderPlan(planSetCooldown(requireVault(), nodeId, cooldownSec)));
+server.tool("vault_plan_pause", "Build an UNSIGNED payload to pause or resume the whole vault. Pausing halts every agent payment. Not signed by this server.", { paused: z.boolean() }, async ({ paused }) => renderPlan(planSetPaused(requireVault(), paused)));
+server.tool("vault_plan_purge", "Build an UNSIGNED payload to delete settled payment records older than a UTC day. Spend totals are NOT refunded, but a deleted request id becomes reusable. Not signed by this server.", {
+    beforeDay: z.number().int().min(0),
+    limit: z.number().int().min(0).max(100).default(100),
+}, async ({ beforeDay, limit }) => renderPlan(planPurgeSettled(requireVault(), beforeDay, limit)));
+await server.connect(new StdioServerTransport());

package/dist/sign.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The ONLY place in this server that touches a key.
+ *
+ * It signs exactly one method — `request_payment` — with the restricted key
+ * issued by `create_agent_account`. That key is cryptographically incapable of
+ * doing anything else: its `receiver_id` is the vault, its `method_names` is
+ * `["request_payment"]`, and a NEAR function-call key cannot attach a deposit
+ * at all. So the worst a compromised copy of this server can do is make
+ * payments the vault's on-chain policy already permits.
+ *
+ * Owner methods are deliberately NOT here. They are emitted as unsigned
+ * payloads (see payloads.ts) for the human to approve in their own wallet,
+ * which keeps this server out of the trust path for anything that changes
+ * policy — the property that distinguishes the design from a custodial agent
+ * wallet.
+ */
+/**
+ * Fee and ordering fields for a Base-routed payment. Decimal strings.
+ *
+ * There is no `nonce`. The CONTRACT allocates it, because it is part of the
+ * signed payload and a caller cannot choose one safely: two payments in the
+ * same block read the same chain state, sign for the same nonce, and one is
+ * rejected AFTER its NEAR reservation has been consumed. The contract is the
+ * only place that sees every Base signature in a serial order.
+ */
+/**
+ * The contract's `route` argument.
+ *
+ * Note what is NOT here: no payload, no destination, no amount. For a
+ * cross-chain payment the contract transfers to the quote's deposit address
+ * and checks the allowlist against the final payee; nothing a caller passes
+ * can redirect where value ends up. If this type ever grows a `payload`
+ * field, that property is gone.
+ *
+ * A cross-chain payment is an ordinary NEP-141 transfer to a solver's
+ * deposit address — no derived address, no ETH to fund, no nonce.
+ */
+export type RouteArg = "near_direct" | {
+    intents: {
+        deposit_address: string;
+        quote_deadline_ns: string;
+        signature: string;
+    };
+};
+export declare function buildRoute(rail: "near"): RouteArg;
+export declare function buildRoute(rail: "intents", intents: IntentsRouteFields): RouteArg;
+/** Fields of a cross-chain route, all produced by the quote signer. */
+export interface IntentsRouteFields {
+    depositAddress: string;
+    quoteDeadlineNs: string;
+    /** base64 ed25519 over borsh(QuoteBinding). See quote.ts. */
+    signature: string;
+}
+export interface PayArgs {
+    rpcUrl: string;
+    vault: string;
+    agentId: string;
+    agentKey: string;
+    requestId: string;
+    token: string;
+    /** Base units. Already scaled by amounts.toBaseUnits. */
+    amount: bigint;
+    recipient: string;
+    memo: string;
+    gasTgas: number;
+    /** Omitted means the NEAR rail, matching the contract's `Option<Route>`. */
+    route?: RouteArg;
+}
+export declare function sendRequestPayment(a: PayArgs): Promise<unknown>;