clanker-wallet 0.7.0 → 0.9.0

package/README.md

@@ -88,6 +88,8 @@ clanker-wallet send --xch testnet11 --to txch1qqqsyqcyq5rqwzqfpg9scrgwpugpzysnzs
 # approved → {"tx_hash":"<bitcoin txid or chia transaction id>","status":"approved"}
 ```
 
+A chia approval may have no `tx_hash` (`{"status":"approved"}`): the Sage wallet sends without reporting a transaction id, so check the recipient's balance.
+
 | Flag | Required | Default | Description |
 |------|----------|---------|-------------|
 | `--btc <network>` | one of `--btc`/`--xch` | — | `mainnet`, `testnet` or `signet` |
@@ -177,11 +179,11 @@ Claude Desktop (`claude_desktop_config.json`), Cursor (`~/.cursor/mcp.json`), an
 | Tool | Arguments | Returns |
 |------|-----------|---------|
 | `request_evm_tx` | `chain_id`, `to`, `value` (wei, integer string), `data` (default `0x`), `reason`, optional `urgency` / `expected_outcome` / `from` (the paired wallet to send from, needed when several wallets of the same family are paired) | `{"request_id":"req_...","status":"pending","expires_at":"..."}` |
-| `request_transfer` | `family` (`bitcoin`), `network` (`mainnet`, `testnet`, `signet`), `to`, `amount` (sats, integer string), `reason`, optional `urgency` / `expected_outcome` / `from` (the paired wallet to send from, needed when several wallets of the same family are paired) | as above |
-| `get_request` | `request_id`, optional `wait_seconds` (at most 50) | `status`: `pending`, `approved` (with `tx_hash`), `rejected`, `failed` (with `error`), `unknown` (with `error`) or `expired` |
-| `list_pairings` | none | `agent_id`, `fingerprint`, and the paired families (`evm`, `bitcoin`) with network, wallet and mode |
+| `request_transfer` | `family` (`bitcoin` or `chia`), `network` (bitcoin: `mainnet`, `testnet`, `signet`; chia: `mainnet`, `testnet11`), `to`, `amount` (sats, integer string) or mojos for chia, `reason`, optional `fee` (chia only: mojos, default `"0"`) / `urgency` / `expected_outcome` / `from` (the paired wallet to send from, needed when several wallets of the same family are paired) | as above |
+| `get_request` | `request_id`, optional `wait_seconds` (at most 50) | `status`: `pending`, `approved` (with `tx_hash`; a chia send may have none), `rejected`, `failed` (with `error`), `unknown` (with `error`) or `expired` |
+| `list_pairings` | none | `agent_id`, `fingerprint`, and the paired families (`evm`, `bitcoin`, `chia`) with network, wallet and mode |
 
-Requests are asynchronous: a request tool returns once the relay has the request, then the assistant calls `get_request` (with `wait_seconds` to wait for an answer) until the status is no longer `pending`. Invalid input or a missing pairing is a tool error, and nothing is sent. Pending requests live in the server process: after 1 h the server stops waiting and reports `expired`, and a restarted server no longer knows them (`get_request` then reports an unknown `request_id`). In both cases the human may still approve the request in their wallet, so ask them before sending it again. `unknown` means the request was delivered but the server lost its relay connection: the human may still approve it, so ask them before sending it again. Chia is not offered over MCP yet.
+Requests are asynchronous: a request tool returns once the relay has the request, then the assistant calls `get_request` (with `wait_seconds` to wait for an answer) until the status is no longer `pending`. Invalid input or a missing pairing is a tool error, and nothing is sent. Pending requests live in the server process: after 1 h the server stops waiting and reports `expired`, and a restarted server no longer knows them (`get_request` then reports an unknown `request_id`). In both cases the human may still approve the request in their wallet, so ask them before sending it again. `unknown` means the request was delivered but the server lost its relay connection: the human may still approve it, so ask them before sending it again. A chia approval may have no `tx_hash`: the Sage wallet sends without reporting a transaction id, so check the recipient's balance.
 
 ---
 
@@ -220,7 +222,7 @@ const txId = await wallet.requestTransfer({
 })
 ```
 
-It throws `InvalidTxError` before sending for an evm pairing, an unknown network, a recipient from another network, a non-integer amount, or a bitcoin `fee` (the wallet sets bitcoin fees). Chia `fee` defaults to `"0"`.
+It throws `InvalidTxError` before sending for an evm pairing, an unknown network, a recipient from another network, a non-integer amount, or a bitcoin `fee` (the wallet sets bitcoin fees). Chia `fee` defaults to `"0"`. It returns `undefined` for a chia send the wallet reported no id for (Sage); check the recipient's balance.
 
 See full API: [`src/`](./src/)
 

package/SKILL.md

@@ -132,7 +132,7 @@ clanker-wallet send --xch testnet11 --to txch1qqqsyqcyq5rqwzqfpg9scrgwpugpzysnzs
 - **bitcoin recipients are segwit addresses only** (`bc1q...`, `bc1p...`, `tb1...`); legacy `1...`/`3...` addresses are refused.
 - **amounts are whole base units**: `--sats` (1 BTC = `100000000`), `--mojos` (1 XCH = `1000000000000`). No decimals.
 - **fees:** bitcoin fees are set in the human's wallet. Chia takes `--fee-mojos` (default `0`), which the human sees before approving.
-- `--reason`, `--urgency`, `--expected-outcome` and `--timeout` work as for `tx`, and so do the output and exit codes. On approval `tx_hash` is the bitcoin txid or the chia transaction id. Exit code 4 means that chain family isn't paired.
+- `--reason`, `--urgency`, `--expected-outcome` and `--timeout` work as for `tx`, and so do the output and exit codes. On approval `tx_hash` is the bitcoin txid or the chia transaction id. A chia approval may have no `tx_hash` (`{"status":"approved"}`): the Sage wallet sends without reporting a transaction id, so check the recipient's balance. Exit code 4 means that chain family isn't paired.
 
 ## Common Chain IDs
 
@@ -216,11 +216,11 @@ Claude Desktop (`claude_desktop_config.json`), Cursor (`~/.cursor/mcp.json`), an
 | Tool | Arguments | Returns |
 |------|-----------|---------|
 | `request_evm_tx` | `chain_id`, `to`, `value` (wei, integer string), `data` (default `0x`), `reason`, optional `urgency` / `expected_outcome` / `from` (the paired wallet to send from, needed when several wallets of the same family are paired) | `{"request_id":"req_...","status":"pending","expires_at":"..."}` |
-| `request_transfer` | `family` (`bitcoin`), `network` (`mainnet`, `testnet`, `signet`), `to`, `amount` (sats, integer string), `reason`, optional `urgency` / `expected_outcome` / `from` (the paired wallet to send from, needed when several wallets of the same family are paired) | as above |
-| `get_request` | `request_id`, optional `wait_seconds` (at most 50) | `status`: `pending`, `approved` (with `tx_hash`), `rejected`, `failed` (with `error`), `unknown` (with `error`) or `expired` |
-| `list_pairings` | none | `agent_id`, `fingerprint`, and the paired families (`evm`, `bitcoin`) with network, wallet and mode |
+| `request_transfer` | `family` (`bitcoin` or `chia`), `network` (bitcoin: `mainnet`, `testnet`, `signet`; chia: `mainnet`, `testnet11`), `to`, `amount` (sats, integer string) or mojos for chia, `reason`, optional `fee` (chia only: mojos, default `"0"`) / `urgency` / `expected_outcome` / `from` (the paired wallet to send from, needed when several wallets of the same family are paired) | as above |
+| `get_request` | `request_id`, optional `wait_seconds` (at most 50) | `status`: `pending`, `approved` (with `tx_hash`; a chia send may have none), `rejected`, `failed` (with `error`), `unknown` (with `error`) or `expired` |
+| `list_pairings` | none | `agent_id`, `fingerprint`, and the paired families (`evm`, `bitcoin`, `chia`) with network, wallet and mode |
 
-Flow: call `list_pairings` to see which chains you can use, call `request_evm_tx` or `request_transfer` (same rules as `tx` / `send`: wei and sats as integer strings, real addresses), tell the human a request is waiting (see "Transaction notifications"), then call `get_request` with `wait_seconds` until the status is no longer `pending`. Invalid input or a missing pairing comes back as a tool error and nothing is sent. After 1 h the server stops waiting and reports `expired`, and a restarted server no longer knows its earlier requests (`get_request` then reports an unknown `request_id`). In both cases the human may still approve the request in their wallet, so ask them before sending it again. `unknown` means the request was delivered but the server lost its relay connection: the human may still approve it, so ask them before sending it again. Chia is not offered over MCP yet.
+Flow: call `list_pairings` to see which chains you can use, call `request_evm_tx` or `request_transfer` (same rules as `tx` / `send`: wei, sats and mojos as integer strings, real addresses), tell the human a request is waiting (see "Transaction notifications"), then call `get_request` with `wait_seconds` until the status is no longer `pending`. Invalid input or a missing pairing comes back as a tool error and nothing is sent. After 1 h the server stops waiting and reports `expired`, and a restarted server no longer knows its earlier requests (`get_request` then reports an unknown `request_id`). In both cases the human may still approve the request in their wallet, so ask them before sending it again. `unknown` means the request was delivered but the server lost its relay connection: the human may still approve it, so ask them before sending it again. A chia approval may have no `tx_hash`: the Sage wallet sends without reporting a transaction id, so check the recipient's balance.
 
 ## Troubleshooting
 

package/dist/client.d.ts

@@ -34,10 +34,11 @@ export declare class ClankerWallet extends TypedEmitter {
     /**
      * 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.
+     * the send. resolves with the txid on approval, or with undefined for a chia send the wallet
+     * reported no id for (Sage's chia_send): it was sent, and the recipient's balance shows it.
      * throws InvalidTxError (before anything is sent), or on rejection, timeout, or connection error.
      */
-    requestTransfer(options: RequestTransferOptions): Promise<string>;
+    requestTransfer(options: RequestTransferOptions): Promise<string | undefined>;
     /** encrypt a signed request to the paired human, send it through the relay, and wait for the answer */
     private send;
 }

package/dist/client.js

@@ -99,12 +99,17 @@ export class ClankerWallet extends TypedEmitter {
         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);
+        const txHash = await this.send(txRequest, options, simulate);
+        // unreachable: send() lets only a chia approval through without a hash
+        if (txHash === undefined)
+            throw new Error(`request ${txRequest.request_id}: approved without a tx hash`);
+        return txHash;
     }
     /**
      * 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.
+     * the send. resolves with the txid on approval, or with undefined for a chia send the wallet
+     * reported no id for (Sage's chia_send): it was sent, and the recipient's balance shows it.
      * throws InvalidTxError (before anything is sent), or on rejection, timeout, or connection error.
      */
     async requestTransfer(options) {
@@ -137,6 +142,8 @@ export class ClankerWallet extends TypedEmitter {
         const requestId = request.request_id;
         const timeoutMs = options.timeout_ms ?? DEFAULT_TIMEOUT_MS;
         const { join_timeout_ms: joinTimeoutMs, signal } = options;
+        // a chia wallet can send without reporting an id (Sage's chia_send answers {}); every other approval carries one
+        const hashOptional = 'chain_family' in request && request.chain_family === 'chia';
         return new Promise((resolve, reject) => {
             let ws;
             let timer;
@@ -249,8 +256,8 @@ export class ClankerWallet extends TypedEmitter {
                             tx_hash: response.tx_hash,
                         });
                         cleanup();
-                        if (response.status === 'approved' && response.tx_hash) {
-                            resolve(response.tx_hash);
+                        if (response.status === 'approved' && (response.tx_hash || hashOptional)) {
+                            resolve(response.tx_hash || undefined);
                         }
                         else if (response.status === 'rejected') {
                             reject(new Error(`request ${requestId} rejected by human`));

package/dist/mcp.d.ts

@@ -17,8 +17,8 @@ export interface SavedPairing {
     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';
+/** the families the tools request on */
+type RequestFamily = 'evm' | 'bitcoin' | 'chia';
 export interface McpServerOptions {
     /** the package version, reported in initialize */
     version: string;
@@ -126,6 +126,10 @@ export declare const MCP_TOOLS: ({
                 type: string;
                 description: string;
             };
+            fee: {
+                type: string;
+                description: string;
+            };
             request_id?: undefined;
             wait_seconds?: undefined;
         };

package/dist/mcp.js

@@ -13,7 +13,7 @@ export const MAX_WAIT_SECONDS = 50;
 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 REQUEST_FAMILIES = ['evm', 'bitcoin', 'chia'];
 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' },
@@ -22,7 +22,7 @@ const CONTEXT_PROPERTIES = {
 };
 /** the same on both request tools; the hosted connector copies these definitions verbatim */
 const FROM_PROPERTY = {
-    from: { type: 'string', description: 'the paired wallet address to send from, as list_pairings shows it; needed only when several wallets of the same family (evm or bitcoin) are paired' },
+    from: { type: 'string', description: 'the paired wallet address to send from, as list_pairings shows it; needed only when several wallets of the same family (evm, bitcoin or chia) are paired' },
 };
 /**
  * MCP tool annotations: assistants (ChatGPT, dots, Claude) may skip their confirmation prompt for read-only tools.
@@ -54,17 +54,23 @@ export const MCP_TOOLS = [
     },
     {
         name: 'request_transfer',
-        description: 'Ask the human to send bitcoin from their own wallet, which builds, signs and broadcasts it. ' +
+        description: 'Ask the human to send bitcoin or chia (XCH) 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.',
+            'amount is an integer string, no decimals: sats for bitcoin (1 BTC = "100000000"), where the wallet sets the fee; ' +
+            'mojos for chia (1 XCH = "1000000000000"), with an optional fee in mojos (default "0").',
         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' },
+                family: { type: 'string', enum: ['bitcoin', 'chia'], description: 'chain family' },
+                network: {
+                    type: 'string',
+                    enum: ['mainnet', 'testnet', 'signet', 'testnet11'],
+                    description: 'bitcoin: mainnet, testnet or signet; chia: mainnet or testnet11. must match the paired wallet (see list_pairings)',
+                },
+                to: { type: 'string', description: 'address on that network: bitcoin segwit bc1... (mainnet) or tb1... (testnet, signet); chia xch1... (mainnet) or txch1... (testnet11)' },
+                amount: { type: 'string', description: 'integer string in sats (bitcoin) or mojos (chia)' },
+                fee: { type: 'string', description: 'chia only: integer string in mojos, default "0"; bitcoin takes none (the wallet sets it)' },
                 ...CONTEXT_PROPERTIES,
                 ...FROM_PROPERTY,
             },
@@ -74,7 +80,7 @@ export const MCP_TOOLS = [
     },
     {
         name: 'get_request',
-        description: 'Get the outcome of a request: pending, approved (with tx_hash), rejected, failed (with error), unknown (with error) or expired. ' +
+        description: 'Get the outcome of a request: pending, approved (with tx_hash; a chia send may have none, so check the recipient\'s balance), 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. ' +
@@ -160,6 +166,7 @@ function fromMismatch(family, from, pairing) {
 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>\'',
+    chia: 'not paired with a chia wallet: ask the human to open the XCH 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;
@@ -226,13 +233,15 @@ export function createMcpServer(options) {
         return submit('evm', from, 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 family = args.family;
+        if (family !== 'bitcoin' && family !== 'chia')
+            throw new ToolInputError(`invalid family: must be "bitcoin" or "chia", got ${JSON.stringify(family)}`);
         const context = contextFrom(args);
         const from = fromArg(args);
         let request;
         try {
-            request = validateTransfer('bitcoin', args.network, { asset: 'btc', to: args.to, amount: args.amount });
+            const asset = family === 'bitcoin' ? 'btc' : 'xch';
+            request = validateTransfer(family, args.network, { asset, to: args.to, amount: args.amount, ...(args.fee !== undefined && { fee: args.fee }) });
         }
         catch (err) {
             // the tool calls the network field `network`
@@ -241,7 +250,7 @@ export function createMcpServer(options) {
             throw err;
         }
         const { chain_network, transfer } = request;
-        return submit('bitcoin', from, cancelled, async (wallet, limits) => {
+        return submit(family, from, cancelled, async (wallet, limits) => {
             try {
                 return await wallet.requestTransfer({ chain_network, transfer, context, ...limits });
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clanker-wallet",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",