clanker-wallet 0.4.2 → 0.6.0

package/dist/bech32.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Bech32 / Bech32m decoding — a port of the BIP-173 / BIP-350 reference
+ * implementation (github.com/sipa/bech32 ref/python/segwit_addr.py).
+ * Used to check transfer recipients: bitcoin segwit addresses and chia
+ * puzzle-hash addresses (bech32m, hrp xch / txch).
+ */
+export type Bech32Encoding = 'bech32' | 'bech32m';
+/** validate a bech32/bech32m string; returns its hrp, data (checksum stripped) and encoding */
+export declare function bech32Decode(bech: string): {
+    hrp: string;
+    data: number[];
+    encoding: Bech32Encoding;
+} | null;
+/** general power-of-2 base conversion */
+export declare function convertBits(data: number[], fromBits: number, toBits: number, pad: boolean): number[] | null;
+/** decode a segwit address for the given hrp ('bc' mainnet, 'tb' testnet/signet) */
+export declare function decodeSegwitAddress(hrp: string, addr: string): {
+    version: number;
+    program: number[];
+} | null;
+/**
+ * a segwit address a wallet can pay today: v0 p2wpkh/p2wsh (20/32 bytes) or v1 p2tr (32 bytes).
+ * other versions and v1 lengths decode but are unspendable or anyone-can-spend, so transfers refuse them
+ */
+export declare function isStandardSegwitAddress(hrp: string, addr: string): boolean;
+/** decode a chia address (bech32m of a 32-byte puzzle hash) for the given hrp ('xch' / 'txch') */
+export declare function decodeChiaAddress(hrp: string, addr: string): number[] | null;

package/dist/bech32.js

@@ -0,0 +1,111 @@
+/**
+ * Bech32 / Bech32m decoding — a port of the BIP-173 / BIP-350 reference
+ * implementation (github.com/sipa/bech32 ref/python/segwit_addr.py).
+ * Used to check transfer recipients: bitcoin segwit addresses and chia
+ * puzzle-hash addresses (bech32m, hrp xch / txch).
+ */
+const CHARSET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+const BECH32M_CONST = 0x2bc830a3;
+const GENERATOR = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3];
+function polymod(values) {
+    let chk = 1;
+    for (const value of values) {
+        const top = chk >>> 25;
+        chk = (((chk & 0x1ffffff) << 5) ^ value) >>> 0;
+        for (let i = 0; i < 5; i++) {
+            if ((top >>> i) & 1)
+                chk = (chk ^ GENERATOR[i]) >>> 0;
+        }
+    }
+    return chk;
+}
+function hrpExpand(hrp) {
+    const codes = Array.from(hrp, (c) => c.charCodeAt(0));
+    return [...codes.map((c) => c >> 5), 0, ...codes.map((c) => c & 31)];
+}
+/** validate a bech32/bech32m string; returns its hrp, data (checksum stripped) and encoding */
+export function bech32Decode(bech) {
+    for (const c of bech) {
+        const code = c.charCodeAt(0);
+        if (code < 33 || code > 126)
+            return null;
+    }
+    if (bech.toLowerCase() !== bech && bech.toUpperCase() !== bech)
+        return null;
+    const lower = bech.toLowerCase();
+    const pos = lower.lastIndexOf('1');
+    if (pos < 1 || pos + 7 > lower.length || lower.length > 90)
+        return null;
+    const data = [];
+    for (const c of lower.slice(pos + 1)) {
+        const d = CHARSET.indexOf(c);
+        if (d === -1)
+            return null;
+        data.push(d);
+    }
+    const hrp = lower.slice(0, pos);
+    const check = polymod([...hrpExpand(hrp), ...data]);
+    const encoding = check === 1 ? 'bech32' : check === BECH32M_CONST ? 'bech32m' : null;
+    if (!encoding)
+        return null;
+    return { hrp, data: data.slice(0, -6), encoding };
+}
+/** general power-of-2 base conversion */
+export function convertBits(data, fromBits, toBits, pad) {
+    let acc = 0;
+    let bits = 0;
+    const ret = [];
+    const maxv = (1 << toBits) - 1;
+    const maxAcc = (1 << (fromBits + toBits - 1)) - 1;
+    for (const value of data) {
+        if (value < 0 || value >> fromBits)
+            return null;
+        acc = ((acc << fromBits) | value) & maxAcc;
+        bits += fromBits;
+        while (bits >= toBits) {
+            bits -= toBits;
+            ret.push((acc >> bits) & maxv);
+        }
+    }
+    if (pad) {
+        if (bits)
+            ret.push((acc << (toBits - bits)) & maxv);
+    }
+    else if (bits >= fromBits || ((acc << (toBits - bits)) & maxv)) {
+        return null;
+    }
+    return ret;
+}
+/** decode a segwit address for the given hrp ('bc' mainnet, 'tb' testnet/signet) */
+export function decodeSegwitAddress(hrp, addr) {
+    const decoded = bech32Decode(addr);
+    if (!decoded || decoded.hrp !== hrp || decoded.data.length === 0)
+        return null;
+    const [version, ...rest] = decoded.data;
+    const program = convertBits(rest, 5, 8, false);
+    if (!program || program.length < 2 || program.length > 40)
+        return null;
+    if (version > 16)
+        return null;
+    if (version === 0 && program.length !== 20 && program.length !== 32)
+        return null;
+    if ((version === 0) !== (decoded.encoding === 'bech32'))
+        return null;
+    return { version, program };
+}
+/**
+ * a segwit address a wallet can pay today: v0 p2wpkh/p2wsh (20/32 bytes) or v1 p2tr (32 bytes).
+ * other versions and v1 lengths decode but are unspendable or anyone-can-spend, so transfers refuse them
+ */
+export function isStandardSegwitAddress(hrp, addr) {
+    const decoded = decodeSegwitAddress(hrp, addr);
+    return !!decoded && (decoded.version === 0 || (decoded.version === 1 && decoded.program.length === 32));
+}
+/** decode a chia address (bech32m of a 32-byte puzzle hash) for the given hrp ('xch' / 'txch') */
+export function decodeChiaAddress(hrp, addr) {
+    const decoded = bech32Decode(addr);
+    if (!decoded || decoded.hrp !== hrp || decoded.encoding !== 'bech32m')
+        return null;
+    const puzzleHash = convertBits(decoded.data, 5, 8, false);
+    return puzzleHash && puzzleHash.length === 32 ? puzzleHash : null;
+}

package/dist/client.d.ts

@@ -1,5 +1,9 @@
 import { TypedEmitter } from './events.js';
-import type { PairingData, RequestTxOptions } from './types.js';
+import type { PairingData, RequestTransferOptions, RequestTxOptions } from './types.js';
+/** the relay answered with an error frame (rate limited, message too large, ...): it refused the request instead of passing it on */
+export declare class RelayError extends Error {
+    constructor(message: string);
+}
 export interface ClankerWalletOptions {
     /** agent display name (informational) */
     agentName?: string;
@@ -27,4 +31,13 @@ export declare class ClankerWallet extends TypedEmitter {
      * throws on rejection, timeout, or connection error.
      */
     requestTx(options: RequestTxOptions): Promise<string>;
+    /**
+     * send a bitcoin / chia transfer to the paired human and wait for their response.
+     * the family comes from the pairing; the human's wallet builds, signs and broadcasts
+     * the send. resolves with the txid on approval.
+     * throws InvalidTxError (before anything is sent), or on rejection, timeout, or connection error.
+     */
+    requestTransfer(options: RequestTransferOptions): Promise<string>;
+    /** encrypt a signed request to the paired human, send it through the relay, and wait for the answer */
+    private send;
 }

package/dist/client.js

@@ -1,6 +1,6 @@
 import { decryptMessage, encryptMessage, fromHex, generateKeypair, keypairFromSecret, signMessage, signingKeypairFromSeed, toHex } from './crypto.js';
 import { TypedEmitter } from './events.js';
-import { validateTx } from './validate.js';
+import { InvalidTxError, validateTransfer, validateTx } from './validate.js';
 const DEFAULT_TIMEOUT_MS = 3_600_000; // 1 hour
 const UNREACHABLE_HINT = 'if you run in a sandbox or behind a firewall, allow this host; otherwise the relay may be down or rate limiting, retry in a few seconds';
 /** node's WebSocket ignores HTTPS_PROXY unless NODE_USE_ENV_PROXY is set at startup, and sandboxes (claude code) only let traffic out through that proxy */
@@ -12,6 +12,13 @@ function proxyHint() {
         ? '; HTTPS_PROXY is set but node ignores it, rerun with NODE_USE_ENV_PROXY=1 (node 24+)'
         : '';
 }
+/** the relay answered with an error frame (rate limited, message too large, ...): it refused the request instead of passing it on */
+export class RelayError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RelayError';
+    }
+}
 export class ClankerWallet extends TypedEmitter {
     publicKey;
     secretKey;
@@ -55,6 +62,8 @@ export class ClankerWallet extends TypedEmitter {
             relayUrl: data.relay,
             humanWallet: data.wallet || null,
             mode: data.mode || 'encrypted',
+            chainFamily: data.chain_family || null,
+            chainNetwork: data.chain_network || null,
         };
         this.emit('paired', { relay: data.relay, wallet: data.wallet || '' });
         return data;
@@ -68,13 +77,16 @@ export class ClankerWallet extends TypedEmitter {
         if (!this.pairing) {
             throw new Error('not paired — call pair() first');
         }
+        // a bitcoin or chia pairing takes transfers only: its wallet can't sign an evm tx
+        const { chainFamily } = this.pairing;
+        if (chainFamily && chainFamily !== 'evm') {
+            throw new InvalidTxError('chain_family', `this pairing is for ${chainFamily}: use requestTransfer for bitcoin or chia`);
+        }
         // reject malformed requests before anything reaches the relay
         const { chain_id, transaction } = validateTx(options.chain_id, options.transaction);
-        const { humanPubkey, humanPubkeyHex, relayUrl, humanWallet, mode } = this.pairing;
-        const timeoutMs = options.timeout_ms ?? DEFAULT_TIMEOUT_MS;
-        const requestId = `req_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const { humanWallet, mode } = this.pairing;
         const txRequest = {
-            request_id: requestId,
+            request_id: newRequestId(),
             agent_id: this.agentId,
             timestamp: new Date().toISOString(),
             chain_id,
@@ -83,28 +95,90 @@ export class ClankerWallet extends TypedEmitter {
             signature: '', // set below after signing
         };
         txRequest.signature = signMessage(JSON.stringify(txRequest), this.signingSecretKey);
+        // managed mode: relay gets plaintext tx params so it can simulate
+        const simulate = mode === 'managed'
+            ? { from: humanWallet || '', to: transaction.to, value: transaction.value, data: transaction.data, chainId: chain_id }
+            : undefined;
+        return this.send(txRequest, options, simulate);
+    }
+    /**
+     * send a bitcoin / chia transfer to the paired human and wait for their response.
+     * the family comes from the pairing; the human's wallet builds, signs and broadcasts
+     * the send. resolves with the txid on approval.
+     * throws InvalidTxError (before anything is sent), or on rejection, timeout, or connection error.
+     */
+    async requestTransfer(options) {
+        if (!this.pairing) {
+            throw new Error('not paired — call pair() first');
+        }
+        const { chainFamily, chainNetwork } = this.pairing;
+        // reject malformed requests before anything reaches the relay
+        const { chain_family, chain_network, transfer } = validateTransfer(chainFamily, options.chain_network, options.transfer);
+        if (chainNetwork && chainNetwork !== chain_network) {
+            throw new InvalidTxError('chain_network', `this pairing is for ${chain_family} ${chainNetwork}, got "${chain_network}"`);
+        }
+        const request = {
+            request_id: newRequestId(),
+            agent_id: this.agentId,
+            timestamp: new Date().toISOString(),
+            chain_family,
+            chain_network,
+            transfer,
+            context: options.context,
+            signature: '', // set below after signing
+        };
+        request.signature = signMessage(JSON.stringify(request), this.signingSecretKey);
+        // the relay simulator is evm-only: no simulate object for transfers, even on a managed pairing
+        return this.send(request, options);
+    }
+    /** encrypt a signed request to the paired human, send it through the relay, and wait for the answer */
+    send(request, options, simulate) {
+        const { humanPubkey, humanPubkeyHex, relayUrl } = this.pairing;
+        const requestId = request.request_id;
+        const timeoutMs = options.timeout_ms ?? DEFAULT_TIMEOUT_MS;
+        const { join_timeout_ms: joinTimeoutMs, signal } = options;
         return new Promise((resolve, reject) => {
             let ws;
             let timer;
+            let joinTimer;
             let settled = false;
+            const onAbort = () => {
+                if (!settled)
+                    fail(`request ${requestId} cancelled`);
+            };
             const cleanup = () => {
                 settled = true;
                 clearTimeout(timer);
+                clearTimeout(joinTimer);
+                signal?.removeEventListener('abort', onAbort);
                 if (ws && ws.readyState <= WebSocket.OPEN) {
                     ws.close();
                 }
             };
-            const fail = (message) => {
+            const fail = (error) => {
+                const err = typeof error === 'string' ? new Error(error) : error;
                 cleanup();
-                this.emit('error', { message });
-                reject(new Error(message));
+                this.emit('error', { message: err.message });
+                reject(err);
             };
+            if (signal?.aborted) {
+                onAbort();
+                return;
+            }
+            signal?.addEventListener('abort', onAbort);
             timer = setTimeout(() => {
                 if (!settled) {
                     fail(`request ${requestId} timed out after ${timeoutMs}ms`);
                 }
             }, timeoutMs);
             this.emit('connecting', { relay: relayUrl });
+            // the request goes out only once joined, so failing before then guarantees nothing was sent
+            if (joinTimeoutMs !== undefined) {
+                joinTimer = setTimeout(() => {
+                    if (!settled)
+                        fail(`relay ${relayUrl} did not answer join within ${joinTimeoutMs}ms; request ${requestId} was not sent`);
+                }, joinTimeoutMs);
+            }
             try {
                 ws = new WebSocket(relayUrl);
             }
@@ -138,8 +212,9 @@ export class ClankerWallet extends TypedEmitter {
                     return;
                 }
                 if (msg.type === 'joined') {
+                    clearTimeout(joinTimer);
                     this.emit('connected', { room: humanPubkeyHex });
-                    const ciphertext = encryptMessage(JSON.stringify(txRequest), humanPubkey, this.secretKey);
+                    const ciphertext = encryptMessage(JSON.stringify(request), humanPubkey, this.secretKey);
                     const envelope = {
                         sender_pubkey: this.agentPubkeyHex,
                         ciphertext,
@@ -150,16 +225,8 @@ export class ClankerWallet extends TypedEmitter {
                         room: humanPubkeyHex,
                         payload: JSON.stringify(envelope),
                     };
-                    // managed mode: relay gets plaintext tx params so it can simulate
-                    if (mode === 'managed') {
-                        wsMsg.simulate = {
-                            from: humanWallet || '',
-                            to: transaction.to,
-                            value: transaction.value,
-                            data: transaction.data,
-                            chainId: chain_id,
-                        };
-                    }
+                    if (simulate)
+                        wsMsg.simulate = simulate;
                     ws.send(JSON.stringify(wsMsg));
                     this.emit('request_sent', { request_id: requestId });
                     return;
@@ -201,9 +268,12 @@ export class ClankerWallet extends TypedEmitter {
                     return;
                 }
                 if (msg.type === 'error') {
-                    fail(`relay error: ${msg.message}`);
+                    fail(new RelayError(`relay error: ${msg.message}`));
                 }
             });
         });
     }
 }
+function newRequestId() {
+    return `req_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-export { ClankerWallet } from './client.js';
+export { ClankerWallet, RelayError } from './client.js';
 export type { ClankerWalletOptions } from './client.js';
 export { base64ToBytes, bytesToBase64, decryptMessage, encryptMessage, fromHex, generateKeypair, keypairFromSecret, signMessage, signingKeypairFromSeed, toHex, verifySignature } from './crypto.js';
 export { TypedEmitter } from './events.js';
 export type { EventMap } from './events.js';
-export { InvalidTxError, isChecksumAddress, validateTx } from './validate.js';
+export { InvalidTxError, isChecksumAddress, validateTransfer, validateTx } from './validate.js';
 export type { TxField } from './validate.js';
-export type { AgentEnvelope, PairingData, RequestTxOptions, Transaction, TxContext, TxInput, TxRequest, TxResponse, } from './types.js';
+export type { AgentEnvelope, PairingData, RequestTransferOptions, RequestTxOptions, Transaction, Transfer, TransferFamily, TransferInput, TransferRequest, TxContext, TxInput, TxRequest, TxResponse, } from './types.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { ClankerWallet } from './client.js';
+export { ClankerWallet, RelayError } from './client.js';
 export { base64ToBytes, bytesToBase64, decryptMessage, encryptMessage, fromHex, generateKeypair, keypairFromSecret, signMessage, signingKeypairFromSeed, toHex, verifySignature } from './crypto.js';
 export { TypedEmitter } from './events.js';
-export { InvalidTxError, isChecksumAddress, validateTx } from './validate.js';
+export { InvalidTxError, isChecksumAddress, validateTransfer, validateTx } from './validate.js';

package/dist/mcp.d.ts

@@ -0,0 +1,156 @@
+import { type ClankerWallet } from './client.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 declare const SUPPORTED_PROTOCOL_VERSIONS: string[];
+/** get_request waits at most this long per call; assistants time tool calls out after about a minute */
+export declare const MAX_WAIT_SECONDS = 50;
+/** a pairing as the cli saves it in ~/.clanker-wallet/pairings/<family>.json */
+export interface SavedPairing {
+    pubkey: string;
+    relay: string;
+    wallet: string | null;
+    mode: 'encrypted' | 'managed' | null;
+    chain_family?: string;
+    chain_network?: string;
+}
+/** the families the tools request on; chia waits until the web app shows it again */
+type RequestFamily = 'evm' | 'bitcoin';
+export interface McpServerOptions {
+    /** the package version, reported in initialize */
+    version: string;
+    identity: {
+        agent_id: string;
+        fingerprint: string;
+    };
+    /** the saved pairing for a family, or null when that family isn't paired */
+    loadPairing: (family: RequestFamily) => SavedPairing | null;
+    /** a new ClankerWallet with the agent identity, paired from `pairing` */
+    wallet: (pairing: SavedPairing) => ClankerWallet;
+    /** how long a request waits for the human (default 1 h, the relay's buffer) */
+    requestTtlMs?: number;
+    /** how long a request waits for the relay to confirm the join before failing unsent (default 20 s) */
+    joinTimeoutMs?: number;
+}
+export declare const MCP_TOOLS: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            reason: {
+                type: string;
+                description: string;
+            };
+            urgency: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            expected_outcome: {
+                type: string;
+                description: string;
+            };
+            chain_id: {
+                type: string;
+                description: string;
+            };
+            to: {
+                type: string;
+                description: string;
+            };
+            value: {
+                type: string;
+                description: string;
+            };
+            data: {
+                type: string;
+                description: string;
+            };
+            request_id?: undefined;
+            wait_seconds?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            reason: {
+                type: string;
+                description: string;
+            };
+            urgency: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            expected_outcome: {
+                type: string;
+                description: string;
+            };
+            family: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            network: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            to: {
+                type: string;
+                description: string;
+            };
+            amount: {
+                type: string;
+                description: string;
+            };
+            request_id?: undefined;
+            wait_seconds?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            request_id: {
+                type: string;
+                description: string;
+            };
+            wait_seconds: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            request_id?: undefined;
+            wait_seconds?: undefined;
+        };
+        required?: undefined;
+    };
+})[];
+/** what get_request reports, in the order the docs list them */
+export declare const REQUEST_STATUSES: readonly ["pending", "approved", "rejected", "failed", "unknown", "expired"];
+export declare function createMcpServer(options: McpServerOptions): {
+    handleLine: (line: string) => Promise<string | null>;
+};
+export {};