clanker-wallet 0.4.2 → 0.6.0

package/dist/mcp.js

@@ -0,0 +1,370 @@
+import { RelayError } from './client.js';
+import { InvalidTxError, validateTransfer, validateTx } from './validate.js';
+/**
+ * MCP server for `clanker-wallet mcp`: newline-delimited JSON-RPC 2.0 over stdio, hand-written so
+ * tweetnacl stays the only runtime dependency. the cli owns stdin/stdout and the identity and pairing
+ * files; this module answers one line at a time and keeps each request's state in memory.
+ */
+/** newest first; a client asking for another version gets the newest. not 2025-03-26: it requires receiving batches, which we refuse */
+export const SUPPORTED_PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2024-11-05'];
+/** get_request waits at most this long per call; assistants time tool calls out after about a minute */
+export const MAX_WAIT_SECONDS = 50;
+/** the relay buffers room messages for 1 h, so a later answer can't reach this process */
+const DEFAULT_REQUEST_TTL_MS = 3_600_000;
+/** a relay that hasn't confirmed the join by then fails the request with nothing sent, inside the hosts' 60 s tool-call timeout */
+const DEFAULT_JOIN_TIMEOUT_MS = 20_000;
+const REQUEST_FAMILIES = ['evm', 'bitcoin'];
+const URGENCIES = ['low', 'medium', 'high'];
+const CONTEXT_PROPERTIES = {
+    reason: { type: 'string', description: 'why you want this, in plain words; shown to the human on the review card' },
+    urgency: { type: 'string', enum: URGENCIES, description: 'priority hint shown to the human' },
+    expected_outcome: { type: 'string', description: 'what will happen once it is sent' },
+};
+export const MCP_TOOLS = [
+    {
+        name: 'request_evm_tx',
+        description: 'Ask the human to send an EVM transaction (ETH or a contract call) from their own wallet. ' +
+            'Nothing is signed here: the human approves every request on their own device, or rejects it. ' +
+            'Returns { request_id } once the request is delivered; then call get_request for the outcome. ' +
+            'value is an integer string in wei (1 ETH = "1000000000000000000"), no decimals.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                chain_id: { type: 'integer', description: 'EVM chain id: 1 Ethereum, 8453 Base, 84532 Base Sepolia, 10 Optimism, 42161 Arbitrum, 137 Polygon' },
+                to: { type: 'string', description: 'recipient or contract: 0x followed by 40 hex characters (mixed case must be EIP-55 checksummed)' },
+                value: { type: 'string', description: 'integer string in wei; "0" for a contract call that sends no ETH' },
+                data: { type: 'string', description: 'hex calldata, default "0x" (a plain transfer)' },
+                ...CONTEXT_PROPERTIES,
+            },
+            required: ['chain_id', 'to', 'value', 'reason'],
+        },
+    },
+    {
+        name: 'request_transfer',
+        description: 'Ask the human to send bitcoin from their own wallet, which builds, signs and broadcasts it. ' +
+            'Nothing is signed here: the human approves every request on their own device, or rejects it. ' +
+            'Returns { request_id } once the request is delivered; then call get_request for the outcome. ' +
+            'amount is an integer string in sats (1 BTC = "100000000"), no decimals; the wallet sets the fee.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                family: { type: 'string', enum: ['bitcoin'], description: 'chain family' },
+                network: { type: 'string', enum: ['mainnet', 'testnet', 'signet'], description: 'must match the paired wallet (see list_pairings)' },
+                to: { type: 'string', description: 'segwit address on that network: bc1... on mainnet, tb1... on testnet and signet' },
+                amount: { type: 'string', description: 'integer string in sats' },
+                ...CONTEXT_PROPERTIES,
+            },
+            required: ['family', 'network', 'to', 'amount', 'reason'],
+        },
+    },
+    {
+        name: 'get_request',
+        description: 'Get the outcome of a request: pending, approved (with tx_hash), rejected, failed (with error), unknown (with error) or expired. ' +
+            `The human may take minutes to answer: pass wait_seconds (at most ${MAX_WAIT_SECONDS}) to wait for it, and call again while it is pending. ` +
+            'unknown means the request was delivered but this server lost its relay connection: the human may still approve it, so ask them before sending it again. ' +
+            'expired means this server stopped waiting, 1 hour after sending; after a restart it no longer knows earlier request ids. ' +
+            'In both cases the human may still approve it in their wallet, so ask them before sending it again.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                request_id: { type: 'string', description: 'from request_evm_tx or request_transfer' },
+                wait_seconds: { type: 'number', minimum: 0, maximum: MAX_WAIT_SECONDS, description: 'wait up to this long for an answer (default 0)' },
+            },
+            required: ['request_id'],
+        },
+    },
+    {
+        name: 'list_pairings',
+        description: 'List the wallets you can request on (chain family, network, wallet address, mode) and your agent fingerprint, ' +
+            'which the human compares in the web app before trusting you.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+];
+const INSTRUCTIONS = 'clanker-wallet sends transaction requests to a human, who approves or rejects each one in their own wallet; ' +
+    'you never hold keys. Call list_pairings to see which chains you can use, request_evm_tx or request_transfer to ask, ' +
+    'and get_request (with wait_seconds) until the request is no longer pending.';
+/** what get_request reports, in the order the docs list them */
+export const REQUEST_STATUSES = ['pending', 'approved', 'rejected', 'failed', 'unknown', 'expired'];
+const STILL_APPROVABLE = 'the request was delivered, so the human may still approve it in their wallet: ask them before sending it again';
+/** a JSON-RPC error answered to the client */
+class RpcError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const PARSE_ERROR = -32700;
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+const INTERNAL_ERROR = -32603;
+/** a tool's input was refused; reported as a tool result with isError, nothing sent */
+class ToolInputError extends Error {
+}
+const toolResult = (body) => ({ content: [{ type: 'text', text: JSON.stringify(body) }] });
+const toolError = (message) => ({ content: [{ type: 'text', text: message }], isError: true });
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** reason (required, non-blank), urgency and expected_outcome from tool arguments */
+function contextFrom(args) {
+    const { reason, urgency, expected_outcome } = args;
+    if (typeof reason !== 'string' || !reason.trim())
+        throw new ToolInputError('invalid reason: say why, in plain words; the human sees it');
+    const context = { reason };
+    if (urgency !== undefined) {
+        if (typeof urgency !== 'string' || !URGENCIES.includes(urgency))
+            throw new ToolInputError(`invalid urgency: must be ${URGENCIES.join(', ')}`);
+        context.urgency = urgency;
+    }
+    if (expected_outcome !== undefined) {
+        if (typeof expected_outcome !== 'string')
+            throw new ToolInputError('invalid expected_outcome: must be a string');
+        context.expected_outcome = expected_outcome;
+    }
+    return context;
+}
+const NOT_PAIRED = {
+    evm: 'not paired with an evm wallet: ask the human to open https://clanker-wallet.xyz, copy the pairing JSON, and run: clanker-wallet pair \'<JSON>\'',
+    bitcoin: 'not paired with a bitcoin wallet: ask the human to open the bitcoin tab at https://clanker-wallet.xyz, copy its pairing JSON, and run: clanker-wallet pair \'<JSON>\'',
+};
+export function createMcpServer(options) {
+    const ttl = options.requestTtlMs ?? DEFAULT_REQUEST_TTL_MS;
+    const joinTimeout = options.joinTimeoutMs ?? DEFAULT_JOIN_TIMEOUT_MS;
+    const records = new Map();
+    /** tools/call requests still being answered, by JSON-RPC id, for notifications/cancelled */
+    const inFlight = new Map();
+    /**
+     * start a request on the family's pairing and answer once the relay has it: { request_id } after
+     * the wallet sends it, or a tool error when it fails first (bad input, unreachable relay, join timeout, cancelled)
+     */
+    function submit(family, cancelled, send) {
+        const pairing = options.loadPairing(family);
+        if (!pairing)
+            return Promise.resolve(toolError(NOT_PAIRED[family]));
+        const wallet = options.wallet(pairing);
+        const expiresAt = Date.now() + ttl;
+        // a cancel stops the wallet only before it sends: once delivered, the human can still approve, so keep waiting
+        const unsent = new AbortController();
+        return new Promise((resolve) => {
+            let record;
+            let answered;
+            // this timer decides expiry, not a Date.now() check: timers can fire a millisecond before the clock reaches their
+            // target. it is set before the wallet's own timer of the same ttl, and node runs equal delays in the order they
+            // were set, so the request is expired before the wallet's timeout rejection arrives
+            const expiry = setTimeout(() => record?.settle('expired'), ttl);
+            cancelled.addEventListener('abort', () => { if (!record)
+                unsent.abort(); });
+            wallet.on('request_sent', ({ request_id }) => {
+                record = newRecord(request_id, expiresAt);
+                records.set(request_id, record);
+                record.settled.then(() => clearTimeout(expiry));
+                resolve(toolResult({ request_id, status: 'pending', expires_at: new Date(expiresAt).toISOString() }));
+            });
+            wallet.on('response', (response) => { answered = response; });
+            send(wallet, { timeout_ms: ttl, join_timeout_ms: joinTimeout, signal: unsent.signal }).then((txHash) => record.settle('approved', { tx_hash: txHash }), (err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                if (!record) {
+                    clearTimeout(expiry);
+                    return resolve(toolError(message));
+                }
+                if (answered?.status === 'rejected')
+                    record.settle('rejected');
+                else if (answered)
+                    record.settle('failed', { error: message });
+                // the relay refused the request (rate limit, size) and dropped it: nothing reached the human
+                else if (err instanceof RelayError)
+                    record.settle('failed', { error: message });
+                // delivered, then the relay connection dropped: the relay still holds the request for the human
+                // (after expiry the record is already settled and this changes nothing)
+                else
+                    record.settle('unknown', { error: `${message}; ${STILL_APPROVABLE}` });
+            });
+        });
+    }
+    async function requestEvmTx(args, cancelled) {
+        const context = contextFrom(args);
+        const { chain_id, transaction } = validateTx(args.chain_id, { to: args.to, value: args.value, data: args.data ?? '0x' });
+        return submit('evm', cancelled, (wallet, limits) => wallet.requestTx({ chain_id, transaction, context, ...limits }));
+    }
+    async function requestTransfer(args, cancelled) {
+        if (args.family !== 'bitcoin')
+            throw new ToolInputError(`invalid family: must be "bitcoin", got ${JSON.stringify(args.family)}`);
+        const context = contextFrom(args);
+        let request;
+        try {
+            request = validateTransfer('bitcoin', args.network, { asset: 'btc', to: args.to, amount: args.amount });
+        }
+        catch (err) {
+            // the tool calls the network field `network`
+            if (err instanceof InvalidTxError && err.field === 'chain_network')
+                throw new ToolInputError(`invalid network: ${err.reason}`);
+            throw err;
+        }
+        const { chain_network, transfer } = request;
+        return submit('bitcoin', cancelled, async (wallet, limits) => {
+            try {
+                return await wallet.requestTransfer({ chain_network, transfer, context, ...limits });
+            }
+            catch (err) {
+                // the pairing is for another network
+                if (err instanceof InvalidTxError && err.field === 'chain_network')
+                    throw new Error(`invalid network: ${err.reason}`);
+                throw err;
+            }
+        });
+    }
+    async function getRequest(args, cancelled) {
+        const { request_id, wait_seconds = 0 } = args;
+        if (typeof request_id !== 'string')
+            throw new ToolInputError('invalid request_id: must be the string request_evm_tx or request_transfer returned');
+        if (typeof wait_seconds !== 'number' || !(wait_seconds >= 0)) {
+            throw new ToolInputError(`invalid wait_seconds: must be a number from 0 to ${MAX_WAIT_SECONDS}`);
+        }
+        const record = records.get(request_id);
+        if (!record) {
+            throw new ToolInputError(`unknown request_id ${JSON.stringify(request_id)}: this server did not send it, or sent it before it restarted and stopped waiting. ` +
+                'if it was sent before a restart, the human may still approve it in their wallet: ask them before sending it again');
+        }
+        const waitMs = Math.min(wait_seconds, MAX_WAIT_SECONDS) * 1000;
+        if (record.status === 'pending' && waitMs > 0) {
+            let timer;
+            const waits = [record.settled, new Promise((r) => cancelled.addEventListener('abort', r, { once: true }))];
+            // a wait that reaches past expiry ends when the request's expiry timer settles it
+            if (waitMs < record.expiresAt - Date.now())
+                waits.push(new Promise((r) => { timer = setTimeout(r, waitMs); }));
+            await Promise.race(waits);
+            clearTimeout(timer);
+        }
+        // a fallback for an expiry timer that runs late (a busy process): it only marks expired once the clock has passed expires_at
+        if (record.status === 'pending' && Date.now() >= record.expiresAt)
+            record.settle('expired');
+        const { status, tx_hash, error } = record;
+        if (status === 'pending')
+            return toolResult({ request_id, status, expires_at: new Date(record.expiresAt).toISOString() });
+        return toolResult({ request_id, status, ...(tx_hash !== undefined && { tx_hash }), ...(error !== undefined && { error }) });
+    }
+    function listPairings() {
+        const pairings = REQUEST_FAMILIES.flatMap((family) => {
+            const pairing = options.loadPairing(family);
+            return pairing ? [{ family, network: pairing.chain_network ?? null, wallet: pairing.wallet ?? null, mode: pairing.mode ?? null }] : [];
+        });
+        return toolResult({ ...options.identity, pairings });
+    }
+    const TOOL_HANDLERS = {
+        request_evm_tx: requestEvmTx,
+        request_transfer: requestTransfer,
+        get_request: getRequest,
+        list_pairings: listPairings,
+    };
+    async function callTool(params, cancelled) {
+        if (!isObject(params) || typeof params.name !== 'string')
+            throw new RpcError(INVALID_PARAMS, 'tools/call needs a tool name');
+        const handler = TOOL_HANDLERS[params.name];
+        if (!handler)
+            throw new RpcError(INVALID_PARAMS, `unknown tool: ${params.name}`);
+        const args = params.arguments ?? {};
+        if (!isObject(args))
+            throw new RpcError(INVALID_PARAMS, 'tool arguments must be an object');
+        try {
+            return await handler(args, cancelled);
+        }
+        catch (err) {
+            if (err instanceof ToolInputError || err instanceof InvalidTxError)
+                return toolError(err.message);
+            throw err;
+        }
+    }
+    function initialize(params) {
+        const requested = isObject(params) ? params.protocolVersion : undefined;
+        const protocolVersion = typeof requested === 'string' && SUPPORTED_PROTOCOL_VERSIONS.includes(requested) ? requested : SUPPORTED_PROTOCOL_VERSIONS[0];
+        return {
+            protocolVersion,
+            capabilities: { tools: {} },
+            serverInfo: { name: 'clanker-wallet', version: options.version },
+            instructions: INSTRUCTIONS,
+        };
+    }
+    async function dispatch(method, params, cancelled) {
+        switch (method) {
+            case 'initialize': return initialize(params);
+            case 'ping': return {};
+            case 'tools/list': return { tools: MCP_TOOLS };
+            case 'tools/call': return callTool(params, cancelled);
+            default: throw new RpcError(METHOD_NOT_FOUND, `method not found: ${method}`);
+        }
+    }
+    /** the reply to one input line, or null when none is due (blank line, notification, a response from the client) */
+    async function handleLine(line) {
+        if (!line.trim())
+            return null;
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return reply(null, { error: { code: PARSE_ERROR, message: 'parse error: each line must be one JSON-RPC message' } });
+        }
+        if (Array.isArray(msg))
+            return reply(null, { error: { code: INVALID_REQUEST, message: 'batches are not supported' } });
+        if (!isObject(msg))
+            return reply(null, { error: { code: INVALID_REQUEST, message: 'invalid request' } });
+        const hasId = 'id' in msg;
+        const id = typeof msg.id === 'string' || typeof msg.id === 'number' ? msg.id : null;
+        if (hasId && id === null)
+            return reply(null, { error: { code: INVALID_REQUEST, message: 'invalid request: id must be a string or number' } });
+        if (typeof msg.method !== 'string') {
+            // a response to us: we send no requests, so there is nothing to match it with
+            if ('result' in msg || 'error' in msg)
+                return null;
+            return reply(id, { error: { code: INVALID_REQUEST, message: 'invalid request: no method' } });
+        }
+        if (msg.jsonrpc !== '2.0')
+            return reply(id, { error: { code: INVALID_REQUEST, message: 'invalid request: jsonrpc must be "2.0"' } });
+        // notifications need no answer; only cancelled changes anything here
+        if (!hasId) {
+            if (msg.method === 'notifications/cancelled' && isObject(msg.params))
+                inFlight.get(msg.params.requestId)?.abort();
+            return null;
+        }
+        const controller = new AbortController();
+        inFlight.set(id, controller);
+        let answer;
+        try {
+            answer = reply(id, { result: await dispatch(msg.method, msg.params, controller.signal) });
+        }
+        catch (err) {
+            if (err instanceof RpcError)
+                answer = reply(id, { error: { code: err.code, message: err.message } });
+            else
+                answer = reply(id, { error: { code: INTERNAL_ERROR, message: err instanceof Error ? err.message : String(err) } });
+        }
+        finally {
+            if (inFlight.get(id) === controller)
+                inFlight.delete(id);
+        }
+        // the client gave up on this call: it expects no response
+        return controller.signal.aborted ? null : answer;
+    }
+    return { handleLine };
+}
+function reply(id, body) {
+    return JSON.stringify({ jsonrpc: '2.0', id, ...body });
+}
+function newRecord(request_id, expiresAt) {
+    let resolveSettled;
+    const record = {
+        request_id,
+        status: 'pending',
+        expiresAt,
+        settled: new Promise((r) => { resolveSettled = r; }),
+        settle: (status, detail = {}) => {
+            if (record.status !== 'pending')
+                return;
+            record.status = status;
+            record.tx_hash = detail.tx_hash;
+            record.error = detail.error;
+            resolveSettled();
+        },
+    };
+    return record;
+}

package/dist/types.d.ts

@@ -48,6 +48,10 @@ export interface PairingData {
     wallet: string;
     /** "encrypted" (default): relay sees only ciphertext. "managed": relay also receives tx params for simulation. */
     mode?: 'encrypted' | 'managed';
+    /** "bitcoin" or "chia" for a non-evm wallet; absent for evm */
+    chain_family?: string;
+    /** the wallet's network, when the pairing names one */
+    chain_network?: string;
 }
 /** options for requestTx */
 export interface RequestTxOptions {
@@ -57,4 +61,52 @@ export interface RequestTxOptions {
     context?: TxContext;
     /** timeout in ms (default: 3_600_000 = 1hr) */
     timeout_ms?: number;
+    /** fail when the relay hasn't confirmed joining the room this long after connecting (default: only timeout_ms applies); nothing was sent then */
+    join_timeout_ms?: number;
+    /** aborting before the relay confirms the join fails the request with nothing sent; after that it only stops waiting */
+    signal?: AbortSignal;
+}
+/** wallet families a transfer can go to */
+export type TransferFamily = 'bitcoin' | 'chia';
+/** an intent-level send: the human's wallet builds and signs it */
+export interface Transfer {
+    asset: 'btc' | 'xch';
+    /** bech32 / bech32m address on the request's network */
+    to: string;
+    /** integer string: sats for btc, mojos for xch */
+    amount: string;
+    /** chia only, in mojos (defaults to "0"); bitcoin wallets set their own fee */
+    fee?: string;
+}
+/** transfer as passed to requestTransfer: amounts as decimal strings or bigints */
+export interface TransferInput {
+    asset: 'btc' | 'xch';
+    to: string;
+    amount: string | bigint;
+    fee?: string | bigint;
+}
+/** bitcoin / chia request sent to the human: no chain_id, no transaction */
+export interface TransferRequest {
+    request_id: string;
+    agent_id: string;
+    timestamp: string;
+    chain_family: TransferFamily;
+    chain_network: string;
+    transfer: Transfer;
+    context?: TxContext;
+    signature: string;
+}
+/** options for requestTransfer; the family comes from the pairing */
+export interface RequestTransferOptions {
+    /** bitcoin: mainnet | testnet | signet; chia: mainnet | testnet11 */
+    chain_network: string;
+    /** checked before sending; an invalid field throws InvalidTxError */
+    transfer: TransferInput;
+    context?: TxContext;
+    /** timeout in ms (default: 3_600_000 = 1hr) */
+    timeout_ms?: number;
+    /** fail when the relay hasn't confirmed joining the room this long after connecting (default: only timeout_ms applies); nothing was sent then */
+    join_timeout_ms?: number;
+    /** aborting before the relay confirms the join fails the request with nothing sent; after that it only stops waiting */
+    signal?: AbortSignal;
 }

package/dist/validate.d.ts

@@ -1,5 +1,5 @@
-import type { Transaction, TxInput } from './types.js';
-export type TxField = 'chain_id' | 'to' | 'value' | 'data';
+import type { Transaction, Transfer, TransferFamily, TransferInput, TxInput } from './types.js';
+export type TxField = 'chain_id' | 'to' | 'value' | 'data' | 'chain_family' | 'chain_network' | 'asset' | 'amount' | 'fee';
 /** a tx request field failed validation; nothing was sent */
 export declare class InvalidTxError extends Error {
     readonly field: TxField;
@@ -17,3 +17,14 @@ export declare function validateTx(chainId: unknown, tx: TxInput | Record<string
     chain_id: number;
     transaction: Transaction;
 };
+/**
+ * check a bitcoin / chia transfer before anything is signed or sent, and normalize it
+ * to the wire format (amounts as decimal strings, chia fee defaulting to "0").
+ * the recipient must decode as an address on `chainNetwork`. as strict as the web app,
+ * so a request it would refuse never leaves the agent. throws InvalidTxError.
+ */
+export declare function validateTransfer(chainFamily: unknown, chainNetwork: unknown, transfer: TransferInput | Record<string, unknown>): {
+    chain_family: TransferFamily;
+    chain_network: string;
+    transfer: Transfer;
+};

package/dist/validate.js

@@ -1,3 +1,4 @@
+import { decodeChiaAddress, isStandardSegwitAddress } from './bech32.js';
 import { keccak256 } from './keccak.js';
 /** a tx request field failed validation; nothing was sent */
 export class InvalidTxError extends Error {
@@ -63,3 +64,65 @@ export function validateTx(chainId, tx) {
     }
     return { chain_id: chainId, transaction: { to, value: wei, data } };
 }
+const TRANSFER_ASSET = { bitcoin: 'btc', chia: 'xch' };
+/** address hrp per network; the web app checks the same table */
+const ADDRESS_HRP = {
+    bitcoin: { mainnet: 'bc', testnet: 'tb', signet: 'tb' },
+    chia: { mainnet: 'xch', testnet11: 'txch' },
+};
+const NETWORK_NAMES = {
+    bitcoin: 'mainnet, testnet or signet',
+    chia: 'mainnet or testnet11',
+};
+const POSITIVE_INT_RE = /^[1-9][0-9]*$/;
+/** a decimal string or bigint amount as a decimal string, or null */
+function units(v, allowZero) {
+    if (typeof v === 'bigint')
+        return v > 0n || (allowZero && v === 0n) ? v.toString() : null;
+    if (typeof v !== 'string')
+        return null;
+    return POSITIVE_INT_RE.test(v) || (allowZero && v === '0') ? v : null;
+}
+/**
+ * check a bitcoin / chia transfer before anything is signed or sent, and normalize it
+ * to the wire format (amounts as decimal strings, chia fee defaulting to "0").
+ * the recipient must decode as an address on `chainNetwork`. as strict as the web app,
+ * so a request it would refuse never leaves the agent. throws InvalidTxError.
+ */
+export function validateTransfer(chainFamily, chainNetwork, transfer) {
+    if (chainFamily !== 'bitcoin' && chainFamily !== 'chia') {
+        throw new InvalidTxError('chain_family', `transfers need a bitcoin or chia pairing, got ${shown(chainFamily ?? 'evm')}`);
+    }
+    const family = chainFamily;
+    const hrp = typeof chainNetwork === 'string' ? ADDRESS_HRP[family][chainNetwork] : undefined;
+    if (!hrp)
+        throw new InvalidTxError('chain_network', `must be ${NETWORK_NAMES[family]}, got ${shown(chainNetwork)}`);
+    const network = chainNetwork;
+    const asset = TRANSFER_ASSET[family];
+    if (transfer.asset !== asset)
+        throw new InvalidTxError('asset', `${family} transfers must be ${shown(asset)}, got ${shown(transfer.asset)}`);
+    const unit = family === 'bitcoin' ? 'sats' : 'mojos';
+    const amount = units(transfer.amount, false);
+    if (!amount)
+        throw new InvalidTxError('amount', `must be a positive integer amount of ${unit} (decimal string or bigint), got ${shown(transfer.amount)}`);
+    const { to } = transfer;
+    if (family === 'bitcoin') {
+        if (transfer.fee !== undefined)
+            throw new InvalidTxError('fee', 'bitcoin transfers take no fee; the wallet sets it');
+        // the wallet api takes sats as a js number
+        if (BigInt(amount) > BigInt(Number.MAX_SAFE_INTEGER)) {
+            throw new InvalidTxError('amount', `must be at most ${Number.MAX_SAFE_INTEGER} sats, got ${shown(amount)}`);
+        }
+        if (typeof to !== 'string' || !isStandardSegwitAddress(hrp, to)) {
+            throw new InvalidTxError('to', `not a bitcoin ${network} address (segwit, ${hrp}1...), got ${shown(to)}`);
+        }
+        return { chain_family: family, chain_network: network, transfer: { asset, to, amount } };
+    }
+    const fee = transfer.fee === undefined ? '0' : units(transfer.fee, true);
+    if (!fee)
+        throw new InvalidTxError('fee', `must be a non-negative integer amount of mojos (decimal string or bigint), got ${shown(transfer.fee)}`);
+    if (typeof to !== 'string' || !decodeChiaAddress(hrp, to)) {
+        throw new InvalidTxError('to', `not a chia ${network} address (${hrp}1...), got ${shown(to)}`);
+    }
+    return { chain_family: family, chain_network: network, transfer: { asset, to, amount, fee } };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clanker-wallet",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -59,6 +59,7 @@
     "tweetnacl": "^1.0.3"
   },
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
     "@types/bun": "^1.3.8",
     "typescript": "^5.4.0",
     "vitest": "^2.1.0"