clanker-wallet 0.8.0 → 0.10.0

package/README.md

@@ -178,12 +178,25 @@ 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_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_...","review_url":"https://clanker-wallet.xyz/?request=req_...","status":"pending","expires_at":"..."}` |
+| `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 |
+| `request_token_transfer` | `chain_id`, `to`, `amount` (positive human decimal string), `reason`, optional `token` (listed symbol or contract address; omitted/native symbol = native coin), `from`, `urgency`, `expected_outcome` | `request_id`, `review_url`, pending status and expiry; existing EVM request, no signing here |
+| `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` |
+| `get_balance` | `family`, `address` (any recipient), EVM `chain_id`, bitcoin/chia `network`, optional EVM `token` (listed symbol or address) | exact `raw_balance`, human `balance`, `asset`, `decimals`; bitcoin also confirmed/mempool deltas; chia recipient puzzle-hash unspent coins only |
+| `get_tx_status` | `family` (evm/bitcoin), `tx_hash`, EVM `chain_id` or bitcoin `network` | receipt `status` and `confirmations`; missing EVM receipt is `pending_or_unknown`, missing bitcoin hash is `unknown` |
+| `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.
+`request_token_transfer` uses the browser-safe `clanker-wallet/tokens` list (chain id, symbol, address, decimals). Unlisted symbols are refused: pass the contract address; never search by symbol. Unlisted contracts must answer both `decimals()` and `symbol()` via RPC. Excess fraction digits are refused, never rounded. The review card reads unlisted token metadata independently and warns with the full contract address; a reported symbol matching a listed token at another address is a danger flag, not an identity check.
+
+`get_balance` needs no pairing and can check any recipient: EVM native/ERC-20 through RPC; bitcoin via `mempool.space` on mainnet/testnet/signet (includes mempool deltas, which can be negative); chia via keyless `api.coinset.org` / `testnet11.api.coinset.org` coin records on mainnet/testnet11. Chia addresses are decoded with the package's bech32 implementation; only unspent coins at that puzzle hash are summed, not every address in a wallet, not mempool or guaranteed spendability. Coin uint64 values stay exact; older runtimes without JSON source context refuse unsafe numeric amounts rather than round. Providers may lag or be unavailable. After a chia approval without a hash, call `get_balance` on the recipient; compare against a prior balance where possible, since a balance alone cannot prove which payment arrived.
+
+`get_tx_status` reports EVM receipt success/failure plus confirmations, or bitcoin confirmations. No receipt is `pending_or_unknown`, not proof of submission; bitcoin can be `pending`, `confirmed` or `unknown`. Reads never sign or send transactions. Chain response bodies are stream-limited to 1 MiB (1,048,576 bytes); Chia replies also allow at most 10,000 coin records. Oversized responses are canceled and refused explicitly, never truncated into a partial balance. Addresses with larger coin histories must be checked using a provider/wallet with appropriate limits; this tool does not paginate or return a partial sum. These bounds supplement provider limits and the request timeout, not a guarantee of provider availability. The hosted connector shares a 60-per-minute per-grant chain-read budget across both read tools and token preparation; local servers use the provider's limits. Full multi-chain transaction history remains out of scope: it would need indexed transfer/transaction providers (typically keyed EVM APIs), pagination/backfills and wallet/address indexing; no keyed API is introduced here.
+
+Chain RPC URLs are keyless public defaults for Ethereum, Base, Arbitrum, Optimism, Polygon and their configured testnets. Override per chain with the `rpcUrls` option or `CLANKER_WALLET_RPC_URLS` (JSON object of chain id to HTTP(S) URL); the hosted connector uses `RPC_URLS` in the same format. Keep keyed URLs in private deployment configuration. RPC services see queried contracts; token metadata is untrusted.
+
+Show the user the `review_url` returned by request tools (also present on pending `get_request` results). It opens `https://clanker-wallet.xyz/?request=<request_id>` and highlights the card after the wallet loads its waiting requests; unknown ids are silently ignored. The link contains only the request id, not pairing secrets. Local MCP servers can override the origin with `webOrigin` or `CLANKER_WALLET_WEB_ORIGIN`.
+
+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.
 
 ---
 

package/SKILL.md

@@ -215,12 +215,25 @@ 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_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_...","review_url":"https://clanker-wallet.xyz/?request=req_...","status":"pending","expires_at":"..."}` |
+| `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 |
+| `request_token_transfer` | `chain_id`, `to`, `amount` (positive human decimal string), `reason`, optional `token` (listed symbol or contract address; omitted/native symbol = native coin), `from`, `urgency`, `expected_outcome` | `request_id`, `review_url`, pending status and expiry; existing EVM request, no signing here |
+| `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` |
+| `get_balance` | `family`, `address` (any recipient), EVM `chain_id`, bitcoin/chia `network`, optional EVM `token` (listed symbol or address) | exact `raw_balance`, human `balance`, `asset`, `decimals`; bitcoin also confirmed/mempool deltas; chia recipient puzzle-hash unspent coins only |
+| `get_tx_status` | `family` (evm/bitcoin), `tx_hash`, EVM `chain_id` or bitcoin `network` | receipt `status` and `confirmations`; missing EVM receipt is `pending_or_unknown`, missing bitcoin hash is `unknown` |
+| `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.
+`request_token_transfer` uses the browser-safe `clanker-wallet/tokens` list (chain id, symbol, address, decimals). Unlisted symbols are refused: pass the contract address; never search by symbol. Unlisted contracts must answer both `decimals()` and `symbol()` via RPC. Excess fraction digits are refused, never rounded. The review card reads unlisted token metadata independently and warns with the full contract address; a reported symbol matching a listed token at another address is a danger flag, not an identity check.
+
+`get_balance` needs no pairing and can check any recipient: EVM native/ERC-20 through RPC; bitcoin via `mempool.space` on mainnet/testnet/signet (includes mempool deltas, which can be negative); chia via keyless `api.coinset.org` / `testnet11.api.coinset.org` coin records on mainnet/testnet11. Chia addresses are decoded with the package's bech32 implementation; only unspent coins at that puzzle hash are summed, not every address in a wallet, not mempool or guaranteed spendability. Coin uint64 values stay exact; older runtimes without JSON source context refuse unsafe numeric amounts rather than round. Providers may lag or be unavailable. After a chia approval without a hash, call `get_balance` on the recipient; compare against a prior balance where possible, since a balance alone cannot prove which payment arrived.
+
+`get_tx_status` reports EVM receipt success/failure plus confirmations, or bitcoin confirmations. No receipt is `pending_or_unknown`, not proof of submission; bitcoin can be `pending`, `confirmed` or `unknown`. Reads never sign or send transactions. Chain response bodies are stream-limited to 1 MiB (1,048,576 bytes); Chia replies also allow at most 10,000 coin records. Oversized responses are canceled and refused explicitly, never truncated into a partial balance. Addresses with larger coin histories must be checked using a provider/wallet with appropriate limits; this tool does not paginate or return a partial sum. These bounds supplement provider limits and the request timeout, not a guarantee of provider availability. The hosted connector shares a 60-per-minute per-grant chain-read budget across both read tools and token preparation; local servers use the provider's limits. Full multi-chain transaction history remains out of scope: it would need indexed transfer/transaction providers (typically keyed EVM APIs), pagination/backfills and wallet/address indexing; no keyed API is introduced here.
+
+Chain RPC URLs are keyless public defaults for Ethereum, Base, Arbitrum, Optimism, Polygon and their configured testnets. Override per chain with the `rpcUrls` option or `CLANKER_WALLET_RPC_URLS` (JSON object of chain id to HTTP(S) URL); the hosted connector uses `RPC_URLS` in the same format. Keep keyed URLs in private deployment configuration. RPC services see queried contracts; token metadata is untrusted.
+
+Show the user the `review_url` returned by request tools (also present on pending `get_request` results). It opens `https://clanker-wallet.xyz/?request=<request_id>` and highlights the card after the wallet loads its waiting requests; unknown ids are silently ignored. The link contains only the request id, not pairing secrets. Local MCP servers can override the origin with `webOrigin` or `CLANKER_WALLET_WEB_ORIGIN`.
+
+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/chain-data.d.ts

@@ -0,0 +1,31 @@
+/** Keyless public defaults; operators can supply keyed URLs without exposing them in tool results. */
+export declare const DEFAULT_RPC_URLS: Readonly<Record<number, string>>;
+export interface ChainDataOptions {
+    rpcUrls?: Readonly<Record<number, string>>;
+    fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+}
+export declare class ChainDataError extends Error {
+}
+/** Bound decoded chain-response buffering by bytes actually read, not an untrusted Content-Length. */
+export declare function readChainResponse(response: Response): Promise<string>;
+export declare function rpcUrlsFromJson(value: string | undefined): Record<number, string> | undefined;
+export declare function evmRpc(chainId: number, method: string, params: unknown[], options?: ChainDataOptions): Promise<unknown>;
+export interface TokenMetadata {
+    address: string;
+    symbol: string;
+    decimals: number;
+}
+export declare function nativeSymbol(chainId: number): string;
+/** Read both fields for unlisted contracts. Never search a symbol or guess its precision. */
+export declare function resolveToken(chainId: number, token: unknown, options?: ChainDataOptions): Promise<TokenMetadata | null>;
+export declare function abiUint(value: unknown): bigint;
+export declare function decimalUnits(amount: unknown, decimals: number): string;
+export declare function buildTokenTransfer(args: {
+    chain_id: unknown;
+    to: unknown;
+    token?: unknown;
+    amount: unknown;
+}, options?: ChainDataOptions): Promise<{
+    chain_id: number;
+    transaction: import("./types.js").Transaction;
+}>;

package/dist/chain-data.js

@@ -0,0 +1,174 @@
+import { TOKENS } from './tokens.js';
+import { validateTx } from './validate.js';
+/** Keyless public defaults; operators can supply keyed URLs without exposing them in tool results. */
+export const DEFAULT_RPC_URLS = {
+    1: 'https://ethereum-rpc.publicnode.com',
+    11155111: 'https://ethereum-sepolia-rpc.publicnode.com',
+    8453: 'https://mainnet.base.org',
+    84532: 'https://sepolia.base.org',
+    42161: 'https://arb1.arbitrum.io/rpc',
+    421614: 'https://sepolia-rollup.arbitrum.io/rpc',
+    10: 'https://mainnet.optimism.io',
+    11155420: 'https://sepolia.optimism.io',
+    137: 'https://polygon-bor-rpc.publicnode.com',
+    80002: 'https://polygon-amoy-bor-rpc.publicnode.com',
+};
+export class ChainDataError extends Error {
+}
+const MAX_CHAIN_RESPONSE_BYTES = 1024 * 1024;
+/** Bound decoded chain-response buffering by bytes actually read, not an untrusted Content-Length. */
+export async function readChainResponse(response) {
+    const reader = response.body?.getReader();
+    if (!reader)
+        return '';
+    const decoder = new TextDecoder();
+    let bytes = 0;
+    let text = '';
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                return text + decoder.decode();
+            bytes += chunk.value.byteLength;
+            if (bytes > MAX_CHAIN_RESPONSE_BYTES)
+                throw new ChainDataError('chain response too large: limit 1048576 bytes; no partial result returned');
+            text += decoder.decode(chunk.value, { stream: true });
+        }
+    }
+    catch (err) {
+        try {
+            await reader.cancel();
+        }
+        catch { /* an already-errored body may refuse cancellation; retain the original sanitized failure */ }
+        if (err instanceof ChainDataError)
+            throw err;
+        throw new ChainDataError('chain response body read failed');
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+export function rpcUrlsFromJson(value) {
+    if (!value)
+        return undefined;
+    try {
+        const urls = JSON.parse(value);
+        if (!urls || typeof urls !== 'object' || Array.isArray(urls))
+            throw new Error();
+        for (const [chain, url] of Object.entries(urls)) {
+            if (!/^[1-9][0-9]*$/.test(chain) || typeof url !== 'string' || !/^https?:$/.test(new URL(url).protocol))
+                throw new Error();
+        }
+        return urls;
+    }
+    catch {
+        throw new ChainDataError('invalid RPC URL map: expected JSON mapping chain ids to http(s) URLs');
+    }
+}
+export async function evmRpc(chainId, method, params, options = {}) {
+    const url = options.rpcUrls?.[chainId] ?? DEFAULT_RPC_URLS[chainId];
+    if (!url)
+        throw new ChainDataError(`no RPC configured for chain ${chainId}`);
+    try {
+        if (!/^https?:$/.test(new URL(url).protocol))
+            throw new Error();
+        const response = await (options.fetch ?? globalThis.fetch)(url, {
+            method: 'POST', headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }), signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new Error();
+        }
+        const body = JSON.parse(await readChainResponse(response));
+        if (body.error || !Object.hasOwn(body, 'result'))
+            throw new Error();
+        return body.result;
+    }
+    catch (err) {
+        if (err instanceof ChainDataError)
+            throw err;
+        throw new ChainDataError(`chain ${chainId} RPC read failed (${method})`);
+    }
+}
+export function nativeSymbol(chainId) {
+    return chainId === 137 || chainId === 80002 ? 'POL' : 'ETH';
+}
+/** Read both fields for unlisted contracts. Never search a symbol or guess its precision. */
+export async function resolveToken(chainId, token, options = {}) {
+    validateTx(chainId, { to: '0x' + '0'.repeat(40), value: '0' });
+    if (token === undefined || (typeof token === 'string' && token.toUpperCase() === nativeSymbol(chainId)))
+        return null;
+    if (typeof token !== 'string' || !token)
+        throw new ChainDataError('invalid token: use a listed symbol or pass the contract address');
+    const listed = TOKENS.find(t => t.chain_id === chainId && (t.address === token.toLowerCase() || t.symbol.toUpperCase() === token.toUpperCase()));
+    if (listed)
+        return listed;
+    if (!/^0x[0-9a-fA-F]{40}$/.test(token))
+        throw new ChainDataError('unlisted symbol: pass the contract address; never search by symbol');
+    const { transaction } = validateTx(chainId, { to: token, value: '0' });
+    try {
+        const call = (data) => evmRpc(chainId, 'eth_call', [{ to: transaction.to, data }, 'latest'], options);
+        const [rawDecimals, rawSymbol] = await Promise.all([call('0x313ce567'), call('0x95d89b41')]);
+        const decimals = Number(abiUint(rawDecimals));
+        if (decimals > 255)
+            throw new Error();
+        const symbol = abiSymbol(rawSymbol);
+        return { address: transaction.to, decimals, symbol };
+    }
+    catch (err) {
+        const detail = err instanceof ChainDataError ? ` (${err.message})` : '';
+        throw new ChainDataError(`token metadata unavailable${detail}: decimals() and symbol() must both answer; nothing was sent`);
+    }
+}
+export function abiUint(value) {
+    if (typeof value !== 'string' || !/^0x[0-9a-fA-F]{64}$/.test(value))
+        throw new ChainDataError('invalid uint256 RPC result');
+    return BigInt(value);
+}
+function abiSymbol(value) {
+    if (typeof value !== 'string' || !/^0x(?:[0-9a-fA-F]{2})+$/.test(value) || value.length > 1026)
+        throw new Error();
+    const hex = value.slice(2);
+    let bytes;
+    if (hex.length === 64)
+        bytes = hex.replace(/(?:00)+$/, ''); // legacy bytes32 symbol
+    else {
+        if (BigInt('0x' + hex.slice(0, 64)) !== 32n)
+            throw new Error();
+        const size = Number(BigInt('0x' + hex.slice(64, 128)));
+        if (size < 1 || size > 128 || hex.length < 128 + Math.ceil(size / 32) * 64)
+            throw new Error();
+        bytes = hex.slice(128, 128 + size * 2);
+    }
+    const symbol = new TextDecoder('utf-8', { fatal: true }).decode(Uint8Array.from(bytes.match(/../g) ?? [], b => parseInt(b, 16)));
+    if (!symbol.trim() || /[\u0000-\u001f\u007f-\u009f]/.test(symbol))
+        throw new Error();
+    return symbol;
+}
+function decimalParts(amount) {
+    if (typeof amount !== 'string' || amount.length > 400 || !/^(0|[1-9][0-9]*)(\.[0-9]+)?$/.test(amount))
+        throw new ChainDataError('invalid amount: use a positive human decimal string, not exponent notation');
+    const [whole, fraction = ''] = amount.split('.');
+    if (BigInt(whole + fraction) === 0n)
+        throw new ChainDataError('amount must be positive');
+    return [whole, fraction];
+}
+export function decimalUnits(amount, decimals) {
+    const [whole, fraction] = decimalParts(amount);
+    if (fraction.length > decimals)
+        throw new ChainDataError(`amount has more fraction digits than ${decimals}; refusing to round`);
+    const raw = BigInt(whole + fraction.padEnd(decimals, '0'));
+    if (raw <= 0n || raw >= 2n ** 256n)
+        throw new ChainDataError('amount must be positive and fit uint256');
+    return raw.toString();
+}
+export async function buildTokenTransfer(args, options = {}) {
+    const { chain_id, transaction } = validateTx(args.chain_id, { to: args.to, value: '0' });
+    decimalParts(args.amount); // refuse invalid/zero amounts before metadata I/O
+    const token = await resolveToken(chain_id, args.token, options);
+    const amount = decimalUnits(args.amount, token?.decimals ?? 18);
+    return validateTx(chain_id, token ? {
+        to: token.address, value: '0', data: '0xa9059cbb' + transaction.to.slice(2).toLowerCase().padStart(64, '0') + BigInt(amount).toString(16).padStart(64, '0'),
+    } : { to: transaction.to, value: amount, data: '0x' });
+}

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+export { getBalance, getTxStatus } from './reads.js';
+export { buildTokenTransfer, resolveToken, rpcUrlsFromJson, evmRpc, ChainDataError, DEFAULT_RPC_URLS } from './chain-data.js';
+export type { ChainDataOptions, TokenMetadata } from './chain-data.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';

package/dist/index.js

@@ -1,3 +1,5 @@
+export { getBalance, getTxStatus } from './reads.js';
+export { buildTokenTransfer, resolveToken, rpcUrlsFromJson, evmRpc, ChainDataError, DEFAULT_RPC_URLS } from './chain-data.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';

package/dist/mcp.d.ts

@@ -1,3 +1,4 @@
+import { type ChainDataOptions } from './chain-data.js';
 import { type ClankerWallet } from './client.js';
 /**
  * MCP server for `clanker-wallet mcp`: newline-delimited JSON-RPC 2.0 over stdio, hand-written so
@@ -17,11 +18,13 @@ 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';
-export interface McpServerOptions {
+/** the families the tools request on */
+type RequestFamily = 'evm' | 'bitcoin' | 'chia';
+export interface McpServerOptions extends ChainDataOptions {
     /** the package version, reported in initialize */
     version: string;
+    /** review app origin (or CLANKER_WALLET_WEB_ORIGIN; default https://clanker-wallet.xyz) */
+    webOrigin?: string;
     identity: {
         agent_id: string;
         fingerprint: string;
@@ -76,6 +79,11 @@ export declare const MCP_TOOLS: ({
             };
             request_id?: undefined;
             wait_seconds?: undefined;
+            family?: undefined;
+            network?: undefined;
+            address?: undefined;
+            token?: undefined;
+            tx_hash?: undefined;
         };
         required: string[];
     };
@@ -126,8 +134,70 @@ export declare const MCP_TOOLS: ({
                 type: string;
                 description: string;
             };
+            fee: {
+                type: string;
+                description: string;
+            };
+            request_id?: undefined;
+            wait_seconds?: undefined;
+            chain_id?: undefined;
+            address?: undefined;
+            token?: undefined;
+            tx_hash?: undefined;
+        };
+        required: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            from: {
+                type: string;
+                description: string;
+            };
+            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;
+            };
+            token: {
+                type: string;
+                description: string;
+            };
+            amount: {
+                type: string;
+                description: string;
+            };
             request_id?: undefined;
             wait_seconds?: undefined;
+            family?: undefined;
+            network?: undefined;
+            address?: undefined;
+            tx_hash?: undefined;
         };
         required: string[];
     };
@@ -153,6 +223,12 @@ export declare const MCP_TOOLS: ({
                 maximum: number;
                 description: string;
             };
+            family?: undefined;
+            chain_id?: undefined;
+            network?: undefined;
+            address?: undefined;
+            token?: undefined;
+            tx_hash?: undefined;
         };
         required: string[];
     };
@@ -160,6 +236,79 @@ export declare const MCP_TOOLS: ({
         readOnlyHint: boolean;
         openWorldHint: boolean;
     };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            family: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            chain_id: {
+                type: string;
+                description: string;
+            };
+            network: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            address: {
+                type: string;
+                description: string;
+            };
+            token: {
+                type: string;
+                description: string;
+            };
+            request_id?: undefined;
+            wait_seconds?: undefined;
+            tx_hash?: undefined;
+        };
+        required: string[];
+    };
+    annotations: {
+        openWorldHint: boolean;
+        readOnlyHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            family: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            chain_id: {
+                type: string;
+                description: string;
+            };
+            network: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            tx_hash: {
+                type: string;
+                description: string;
+            };
+            request_id?: undefined;
+            wait_seconds?: undefined;
+            address?: undefined;
+            token?: undefined;
+        };
+        required: string[];
+    };
+    annotations: {
+        openWorldHint: boolean;
+        readOnlyHint: boolean;
+    };
 } | {
     name: string;
     description: string;
@@ -168,6 +317,12 @@ export declare const MCP_TOOLS: ({
         properties: {
             request_id?: undefined;
             wait_seconds?: undefined;
+            family?: undefined;
+            chain_id?: undefined;
+            network?: undefined;
+            address?: undefined;
+            token?: undefined;
+            tx_hash?: undefined;
         };
         required?: undefined;
     };

package/dist/mcp.js

@@ -1,3 +1,5 @@
+import { getBalance, getTxStatus } from './reads.js';
+import { buildTokenTransfer, ChainDataError, rpcUrlsFromJson } from './chain-data.js';
 import { RelayError } from './client.js';
 import { InvalidTxError, validateTransfer, validateTx } from './validate.js';
 /**
@@ -13,7 +15,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 +24,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.
@@ -36,7 +38,7 @@ 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. ' +
+            'Returns { request_id, review_url } once delivered; show review_url to the user, then call get_request for the outcome. ' +
             'value is an integer string in wei (1 ETH = "1000000000000000000"), no decimals.',
         inputSchema: {
             type: 'object',
@@ -54,17 +56,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.',
+            'Returns { request_id, review_url } once delivered; show review_url to the user, then call get_request for the outcome. ' +
+            '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,
             },
@@ -72,9 +80,29 @@ export const MCP_TOOLS = [
         },
         annotations: REQUEST_HINTS,
     },
+    {
+        name: 'request_token_transfer',
+        description: 'Ask the human to send an EVM token or native coin from their own wallet. ' +
+            'The human approves every request on their own device. amount is a human decimal string; never rounded. ' +
+            'Use a listed symbol for that chain or pass the contract address; unlisted symbols are refused, never searched. ' +
+            'Omit token (or use the native symbol) for native coin. Returns { request_id, review_url }; show review_url to the user, then call get_request.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                chain_id: { type: 'integer', description: 'EVM chain id' },
+                to: { type: 'string', description: 'recipient EVM address' },
+                token: { type: 'string', description: 'listed symbol on this chain or token contract address; omitted or native symbol sends native coin' },
+                amount: { type: 'string', description: 'positive human decimal string, e.g. 1.25; excess fraction digits are refused' },
+                ...CONTEXT_PROPERTIES,
+                ...FROM_PROPERTY,
+            },
+            required: ['chain_id', 'to', 'amount', 'reason'],
+        },
+        annotations: REQUEST_HINTS,
+    },
     {
         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. ' +
@@ -82,13 +110,44 @@ export const MCP_TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
-                request_id: { type: 'string', description: 'from request_evm_tx or request_transfer' },
+                request_id: { type: 'string', description: 'from request_evm_tx, request_transfer or request_token_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'],
         },
         annotations: READ_HINTS,
     },
+    {
+        name: 'get_balance',
+        description: 'Read the balance of any address, including a recipient not paired here. EVM native or ERC-20 (listed symbol or contract address), bitcoin confirmed/mempool, or chia unspent coins at the recipient puzzle hash (not the whole wallet; excludes mempool). After a chia send approved without a hash, check the recipient balance; a balance alone does not prove which payment arrived.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                family: { type: 'string', enum: ['evm', 'bitcoin', 'chia'], description: 'chain family' },
+                chain_id: { type: 'integer', description: 'required for EVM' },
+                network: { type: 'string', enum: ['mainnet', 'testnet', 'signet', 'testnet11'], description: 'required for bitcoin or chia; EVM uses chain_id' },
+                address: { type: 'string', description: 'any address on that network, including a recipient' },
+                token: { type: 'string', description: 'EVM only: listed symbol or contract address; omitted/native symbol = native coin' },
+            },
+            required: ['family', 'address'],
+        },
+        annotations: { ...READ_HINTS, openWorldHint: true },
+    },
+    {
+        name: 'get_tx_status',
+        description: 'Read an EVM transaction receipt status and confirmations, or bitcoin confirmations. An EVM missing receipt means pending_or_unknown, not proof of submission. After a chia approval without a hash, use get_balance on the recipient instead.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                family: { type: 'string', enum: ['evm', 'bitcoin'], description: 'chain family' },
+                chain_id: { type: 'integer', description: 'required for EVM' },
+                network: { type: 'string', enum: ['mainnet', 'testnet', 'signet'], description: 'required for bitcoin' },
+                tx_hash: { type: 'string', description: 'EVM 0x + 64 hex digits; bitcoin 64 hex digits' },
+            },
+            required: ['family', 'tx_hash'],
+        },
+        annotations: { ...READ_HINTS, openWorldHint: true },
+    },
     {
         name: 'list_pairings',
         description: 'List the wallets you can request on (chain family, network, wallet address, mode) and your agent fingerprint, ' +
@@ -98,7 +157,7 @@ export const MCP_TOOLS = [
     },
 ];
 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, ' +
+    'you never hold keys. Call list_pairings to see which chains you can use, request_evm_tx, request_transfer or request_token_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'];
@@ -160,10 +219,14 @@ 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 webOrigin = new URL(options.webOrigin ?? process.env.CLANKER_WALLET_WEB_ORIGIN ?? 'https://clanker-wallet.xyz').origin;
+    const reviewUrl = (id) => `${webOrigin}/?request=${encodeURIComponent(id)}`;
     const ttl = options.requestTtlMs ?? DEFAULT_REQUEST_TTL_MS;
     const joinTimeout = options.joinTimeoutMs ?? DEFAULT_JOIN_TIMEOUT_MS;
+    const chainOptions = { ...options, rpcUrls: options.rpcUrls ?? rpcUrlsFromJson(process.env.CLANKER_WALLET_RPC_URLS) };
     const records = new Map();
     /** tools/call requests still being answered, by JSON-RPC id, for notifications/cancelled */
     const inFlight = new Map();
@@ -173,6 +236,8 @@ export function createMcpServer(options) {
      * join timeout, cancelled)
      */
     function submit(family, from, cancelled, send) {
+        if (cancelled.aborted)
+            return Promise.resolve(toolError('request cancelled before sending; nothing was sent'));
         const pairing = options.loadPairing(family);
         if (!pairing)
             return Promise.resolve(toolError(NOT_PAIRED[family]));
@@ -196,7 +261,7 @@ export function createMcpServer(options) {
                 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() }));
+                resolve(toolResult({ request_id, review_url: reviewUrl(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) => {
@@ -225,14 +290,22 @@ export function createMcpServer(options) {
         const { chain_id, transaction } = validateTx(args.chain_id, { to: args.to, value: args.value, data: args.data ?? '0x' });
         return submit('evm', from, cancelled, (wallet, limits) => wallet.requestTx({ chain_id, transaction, context, ...limits }));
     }
+    async function requestTokenTransfer(args, cancelled) {
+        const context = contextFrom(args);
+        const from = fromArg(args);
+        const { chain_id, transaction } = await buildTokenTransfer({ chain_id: args.chain_id, to: args.to, token: args.token, amount: args.amount }, chainOptions);
+        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 +314,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 });
             }
@@ -280,7 +353,7 @@ export function createMcpServer(options) {
             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, review_url: reviewUrl(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() {
@@ -293,7 +366,10 @@ export function createMcpServer(options) {
     const TOOL_HANDLERS = {
         request_evm_tx: requestEvmTx,
         request_transfer: requestTransfer,
+        request_token_transfer: requestTokenTransfer,
         get_request: getRequest,
+        get_balance: async (args) => toolResult(await getBalance(args, chainOptions)),
+        get_tx_status: async (args) => toolResult(await getTxStatus(args, chainOptions)),
         list_pairings: listPairings,
     };
     async function callTool(params, cancelled) {
@@ -309,7 +385,7 @@ export function createMcpServer(options) {
             return await handler(args, cancelled);
         }
         catch (err) {
-            if (err instanceof ToolInputError || err instanceof InvalidTxError)
+            if (err instanceof ToolInputError || err instanceof InvalidTxError || err instanceof ChainDataError)
                 return toolError(err.message);
             throw err;
         }

package/dist/reads.d.ts

@@ -0,0 +1,51 @@
+import { type ChainDataOptions } from './chain-data.js';
+export declare function getBalance(args: Record<string, unknown>, options?: ChainDataOptions): Promise<{
+    decimals: number;
+    raw_balance: string;
+    balance: string;
+    token_address?: string | undefined;
+    family: string;
+    chain_id: number;
+    address: string;
+    asset: string;
+    network?: undefined;
+    confirmed_balance?: undefined;
+    unconfirmed_balance?: undefined;
+    scope?: undefined;
+} | {
+    family: string;
+    network: string;
+    address: string;
+    asset: string;
+    decimals: number;
+    raw_balance: string;
+    balance: string;
+    confirmed_balance: string;
+    unconfirmed_balance: string;
+    scope?: undefined;
+} | {
+    family: string;
+    network: string;
+    address: unknown;
+    asset: string;
+    decimals: number;
+    raw_balance: string;
+    balance: string;
+    scope: string;
+    confirmed_balance?: undefined;
+    unconfirmed_balance?: undefined;
+}>;
+export declare function getTxStatus(args: Record<string, unknown>, options?: ChainDataOptions): Promise<{
+    family: string;
+    chain_id: number;
+    tx_hash: string;
+    status: string;
+    confirmations: number;
+} | {
+    status: string;
+    confirmations: number;
+    family: string;
+    network: string;
+    tx_hash: string;
+    chain_id?: undefined;
+}>;

package/dist/reads.js

@@ -0,0 +1,210 @@
+import { decodeChiaAddress, decodeSegwitAddress } from './bech32.js';
+import { abiUint, ChainDataError, evmRpc, nativeSymbol, readChainResponse, resolveToken } from './chain-data.js';
+import { validateTx } from './validate.js';
+const BITCOIN_API = {
+    mainnet: 'https://mempool.space/api', testnet: 'https://mempool.space/testnet/api', signet: 'https://mempool.space/signet/api',
+};
+const MAX_CHIA_COIN_RECORDS = 10_000;
+const CHIA_API = { mainnet: 'https://api.coinset.org', testnet11: 'https://testnet11.api.coinset.org' };
+const object = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new ChainDataError('malformed chain response');
+    return value;
+};
+const nonnegativeInteger = (value) => {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
+        throw new ChainDataError('invalid chain integer');
+    return value;
+};
+function quantity(value) {
+    if (typeof value !== 'string' || !/^0x(?:0|[1-9a-fA-F][0-9a-fA-F]*)$/.test(value) || value.length > 66)
+        throw new ChainDataError('invalid RPC quantity');
+    return BigInt(value);
+}
+function formatUnits(raw, decimals) {
+    const negative = raw < 0n;
+    const digits = (negative ? -raw : raw).toString().padStart(decimals + 1, '0');
+    const fraction = decimals ? digits.slice(-decimals).replace(/0+$/, '') : '';
+    return (negative ? '-' : '') + (decimals ? digits.slice(0, -decimals) : digits) + (fraction ? '.' + fraction : '');
+}
+function network(args, endpoints) {
+    if (typeof args.network !== 'string' || !Object.hasOwn(endpoints, args.network))
+        throw new ChainDataError(`invalid network: must be ${Object.keys(endpoints).join(', ')}`);
+    if (args.chain_id !== undefined || args.token !== undefined)
+        throw new ChainDataError('chain_id and token are EVM-only');
+    return args.network;
+}
+async function http(url, options, init, allowMissing = false) {
+    try {
+        const result = await (options.fetch ?? globalThis.fetch)(url, { ...init, signal: AbortSignal.timeout(10_000) });
+        if (!result.ok) {
+            await result.body?.cancel();
+            if (!(allowMissing && result.status === 404))
+                throw new Error();
+        }
+        return result;
+    }
+    catch {
+        throw new ChainDataError('public chain API read failed; retry later');
+    }
+}
+async function json(response) {
+    const text = await readChainResponse(response);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new ChainDataError('malformed chain JSON response');
+    }
+}
+/** Validate legacy Base58Check as well as segwit recipients; no URL/path comes from the caller. */
+async function bitcoinAddress(address, chainNetwork) {
+    if (typeof address !== 'string' || address.length > 90)
+        throw new ChainDataError('invalid bitcoin address');
+    if (decodeSegwitAddress(chainNetwork === 'mainnet' ? 'bc' : 'tb', address))
+        return address.toLowerCase();
+    const alphabet = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+    if (address.length < 26 || address.length > 35 || [...address].some(c => !alphabet.includes(c)))
+        throw new ChainDataError('invalid bitcoin address for network');
+    let value = 0n;
+    for (const c of address)
+        value = value * 58n + BigInt(alphabet.indexOf(c));
+    let hex = value.toString(16);
+    if (hex.length % 2)
+        hex = '0' + hex;
+    const bytes = Uint8Array.from([...Array(address.match(/^1*/)?.[0].length ?? 0).fill(0), ...hex.match(/../g).map(b => parseInt(b, 16))]);
+    const versions = chainNetwork === 'mainnet' ? [0, 5] : [111, 196];
+    if (bytes.length !== 25 || !versions.includes(bytes[0]))
+        throw new ChainDataError('invalid bitcoin address for network');
+    const first = await crypto.subtle.digest('SHA-256', bytes.slice(0, 21));
+    const checksum = new Uint8Array(await crypto.subtle.digest('SHA-256', first));
+    if (!bytes.slice(21).every((b, i) => b === checksum[i]))
+        throw new ChainDataError('invalid bitcoin address checksum');
+    return address;
+}
+/** Preserve uint64 coin amounts using native JSON source context; older runtimes refuse unsafe numbers. */
+function coinJson(text) {
+    try {
+        return object(JSON.parse(text, (_key, value, context) => {
+            if (typeof value !== 'number')
+                return value;
+            if (context?.source)
+                return context.source;
+            if (Number.isSafeInteger(value))
+                return String(value);
+            throw new Error('unsafe coin amount');
+        }));
+    }
+    catch {
+        throw new ChainDataError('malformed or imprecise coin-record response');
+    }
+}
+export async function getBalance(args, options = {}) {
+    if (args.family === 'evm') {
+        if (args.network !== undefined)
+            throw new ChainDataError('EVM reads use chain_id, not network');
+        const { chain_id, transaction } = validateTx(args.chain_id, { to: args.address, value: '0' });
+        const token = await resolveToken(chain_id, args.token, options);
+        const result = token
+            ? await evmRpc(chain_id, 'eth_call', [{ to: token.address, data: '0x70a08231' + transaction.to.slice(2).toLowerCase().padStart(64, '0') }, 'latest'], options)
+            : await evmRpc(chain_id, 'eth_getBalance', [transaction.to, 'latest'], options);
+        const raw = token ? abiUint(result) : quantity(result);
+        const decimals = token?.decimals ?? 18;
+        return { family: 'evm', chain_id, address: transaction.to, asset: token?.symbol ?? nativeSymbol(chain_id), ...(token && { token_address: token.address }), decimals, raw_balance: raw.toString(), balance: formatUnits(raw, decimals) };
+    }
+    if (args.family === 'bitcoin') {
+        const chainNetwork = network(args, BITCOIN_API);
+        const address = await bitcoinAddress(args.address, chainNetwork);
+        const body = object(await json(await http(`${BITCOIN_API[chainNetwork]}/address/${encodeURIComponent(address)}`, options)));
+        const stats = (field) => {
+            const row = object(body[field]);
+            return BigInt(nonnegativeInteger(row.funded_txo_sum)) - BigInt(nonnegativeInteger(row.spent_txo_sum));
+        };
+        const confirmed = stats('chain_stats');
+        const pending = stats('mempool_stats');
+        if (confirmed < 0n || confirmed + pending < 0n)
+            throw new ChainDataError('invalid bitcoin balance response');
+        return { family: 'bitcoin', network: chainNetwork, address, asset: 'BTC', decimals: 8, raw_balance: String(confirmed + pending), balance: formatUnits(confirmed + pending, 8), confirmed_balance: formatUnits(confirmed, 8), unconfirmed_balance: formatUnits(pending, 8) };
+    }
+    if (args.family === 'chia') {
+        const chainNetwork = network(args, CHIA_API);
+        const puzzle = typeof args.address === 'string' && decodeChiaAddress(chainNetwork === 'mainnet' ? 'xch' : 'txch', args.address);
+        if (!puzzle)
+            throw new ChainDataError('invalid chia address for network');
+        const puzzleHash = '0x' + puzzle.map(b => b.toString(16).padStart(2, '0')).join('');
+        const response = await http(`${CHIA_API[chainNetwork]}/get_coin_records_by_puzzle_hash`, options, {
+            method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ puzzle_hash: puzzleHash, include_spent_coins: false }),
+        });
+        const body = coinJson(await readChainResponse(response));
+        if (body.success !== true || !Array.isArray(body.coin_records))
+            throw new ChainDataError('coin-record API did not return a successful balance');
+        if (body.coin_records.length > MAX_CHIA_COIN_RECORDS)
+            throw new ChainDataError('too many coin records: limit 10000; no partial balance returned');
+        let raw = 0n;
+        const seen = new Set();
+        for (const item of body.coin_records) {
+            const record = object(item);
+            if (record.spent === true)
+                continue;
+            if (record.spent !== false)
+                throw new ChainDataError('invalid coin-record spent flag');
+            const coin = object(record.coin);
+            if (coin.puzzle_hash !== puzzleHash || typeof coin.parent_coin_info !== 'string' || !/^0x[0-9a-fA-F]{64}$/.test(coin.parent_coin_info) || typeof coin.amount !== 'string' || !/^(0|[1-9][0-9]*)$/.test(coin.amount) || coin.amount.length > 20)
+                throw new ChainDataError('invalid coin-record identity or amount');
+            const amount = BigInt(coin.amount);
+            if (amount >= 2n ** 64n)
+                throw new ChainDataError('coin amount exceeds uint64');
+            const id = coin.parent_coin_info.toLowerCase() + ':' + coin.amount;
+            if (seen.has(id))
+                throw new ChainDataError('duplicate coin record');
+            seen.add(id);
+            raw += amount;
+        }
+        return { family: 'chia', network: chainNetwork, address: args.address, asset: 'XCH', decimals: 12, raw_balance: raw.toString(), balance: formatUnits(raw, 12), scope: 'unspent coins at this puzzle hash; not the whole wallet; excludes mempool' };
+    }
+    throw new ChainDataError('invalid family: must be evm, bitcoin or chia');
+}
+export async function getTxStatus(args, options = {}) {
+    if (args.family === 'evm') {
+        if (args.network !== undefined)
+            throw new ChainDataError('EVM reads use chain_id, not network');
+        const { chain_id } = validateTx(args.chain_id, { to: '0x' + '0'.repeat(40), value: '0' });
+        if (typeof args.tx_hash !== 'string' || !/^0x[0-9a-fA-F]{64}$/.test(args.tx_hash))
+            throw new ChainDataError('invalid EVM tx_hash');
+        const receipt = await evmRpc(chain_id, 'eth_getTransactionReceipt', [args.tx_hash], options);
+        if (receipt === null)
+            return { family: 'evm', chain_id, tx_hash: args.tx_hash, status: 'pending_or_unknown', confirmations: 0 };
+        const row = object(receipt);
+        if (row.status !== '0x0' && row.status !== '0x1')
+            throw new ChainDataError('invalid receipt status');
+        const height = quantity(row.blockNumber);
+        const tip = quantity(await evmRpc(chain_id, 'eth_blockNumber', [], options));
+        if (tip < height || tip - height >= BigInt(Number.MAX_SAFE_INTEGER))
+            throw new ChainDataError('inconsistent receipt/block height; retry after chain reorganization');
+        return { family: 'evm', chain_id, tx_hash: args.tx_hash, status: row.status === '0x1' ? 'confirmed' : 'failed', confirmations: Number(tip - height + 1n) };
+    }
+    if (args.family === 'bitcoin') {
+        const chainNetwork = network(args, BITCOIN_API);
+        if (typeof args.tx_hash !== 'string' || !/^[0-9a-fA-F]{64}$/.test(args.tx_hash))
+            throw new ChainDataError('invalid bitcoin tx_hash');
+        const base = BITCOIN_API[chainNetwork];
+        const response = await http(`${base}/tx/${args.tx_hash}/status`, options, undefined, true);
+        const common = { family: 'bitcoin', network: chainNetwork, tx_hash: args.tx_hash };
+        if (response.status === 404)
+            return { ...common, status: 'unknown', confirmations: 0 };
+        const row = object(await json(response));
+        if (row.confirmed === false)
+            return { ...common, status: 'pending', confirmations: 0 };
+        if (row.confirmed !== true)
+            throw new ChainDataError('invalid bitcoin transaction status');
+        const height = nonnegativeInteger(row.block_height);
+        const tipText = await readChainResponse(await http(`${base}/blocks/tip/height`, options));
+        if (!/^(0|[1-9][0-9]*)$/.test(tipText))
+            throw new ChainDataError('invalid bitcoin tip height');
+        const tip = nonnegativeInteger(Number(tipText));
+        if (tip < height)
+            throw new ChainDataError('inconsistent bitcoin block height; retry');
+        return { ...common, status: 'confirmed', confirmations: tip - height + 1 };
+    }
+    throw new ChainDataError('transaction status supports evm or bitcoin; after a chia send without a hash, use get_balance on the recipient');
+}

package/dist/tokens.d.ts

@@ -0,0 +1,9 @@
+/** Browser-safe, data-only token list. Addresses, not symbols, identify assets. */
+export interface ListedToken {
+    readonly chain_id: number;
+    readonly address: string;
+    readonly symbol: string;
+    readonly decimals: number;
+    readonly label: string;
+}
+export declare const TOKENS: readonly ListedToken[];

package/dist/tokens.js

@@ -0,0 +1,142 @@
+export const TOKENS = [
+    {
+        "chain_id": 1,
+        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
+        "symbol": "USDC",
+        "decimals": 6,
+        "label": "USDC"
+    },
+    {
+        "chain_id": 1,
+        "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
+        "symbol": "USDT",
+        "decimals": 6,
+        "label": "USDT"
+    },
+    {
+        "chain_id": 1,
+        "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
+        "symbol": "DAI",
+        "decimals": 18,
+        "label": "DAI"
+    },
+    {
+        "chain_id": 1,
+        "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
+        "symbol": "WETH",
+        "decimals": 18,
+        "label": "WETH"
+    },
+    {
+        "chain_id": 1,
+        "address": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599",
+        "symbol": "WBTC",
+        "decimals": 8,
+        "label": "WBTC"
+    },
+    {
+        "chain_id": 1,
+        "address": "0x514910771af9ca656af840dff83e8264ecf986ca",
+        "symbol": "LINK",
+        "decimals": 18,
+        "label": "LINK"
+    },
+    {
+        "chain_id": 1,
+        "address": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
+        "symbol": "UNI",
+        "decimals": 18,
+        "label": "UNI"
+    },
+    {
+        "chain_id": 1,
+        "address": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
+        "symbol": "AAVE",
+        "decimals": 18,
+        "label": "AAVE"
+    },
+    {
+        "chain_id": 8453,
+        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+        "symbol": "USDC",
+        "decimals": 6,
+        "label": "USDC (Base)"
+    },
+    {
+        "chain_id": 8453,
+        "address": "0x4200000000000000000000000000000000000006",
+        "symbol": "WETH",
+        "decimals": 18,
+        "label": "WETH (Base)"
+    },
+    {
+        "chain_id": 84532,
+        "address": "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
+        "symbol": "USDC",
+        "decimals": 6,
+        "label": "USDC (Base Sepolia)"
+    },
+    {
+        "chain_id": 84532,
+        "address": "0x4200000000000000000000000000000000000006",
+        "symbol": "WETH",
+        "decimals": 18,
+        "label": "WETH (Base Sepolia)"
+    },
+    {
+        "chain_id": 42161,
+        "address": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
+        "symbol": "USDC",
+        "decimals": 6,
+        "label": "USDC (Arbitrum)"
+    },
+    {
+        "chain_id": 42161,
+        "address": "0x82af49447d8a07e3bd95bd0d56f35241523fbab1",
+        "symbol": "WETH",
+        "decimals": 18,
+        "label": "WETH (Arbitrum)"
+    },
+    {
+        "chain_id": 137,
+        "address": "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
+        "symbol": "USDC",
+        "decimals": 6,
+        "label": "USDC (Polygon)"
+    },
+    {
+        "chain_id": 137,
+        "address": "0x0d500b1d8e8ef31e21c99d1db9a6444d3adf1270",
+        "symbol": "WMATIC",
+        "decimals": 18,
+        "label": "WMATIC"
+    },
+    {
+        "chain_id": 10,
+        "address": "0x0b2c639c533813f4aa9d7837caf62653d097ff85",
+        "symbol": "USDC",
+        "decimals": 6,
+        "label": "USDC (Optimism)"
+    },
+    {
+        "chain_id": 10,
+        "address": "0x4200000000000000000000000000000000000006",
+        "symbol": "WETH",
+        "decimals": 18,
+        "label": "WETH (Optimism)"
+    },
+    {
+        "chain_id": 1,
+        "address": "0x7f39c581f595b53c5cb19bd0b3f8da6c935e2ca0",
+        "symbol": "wstETH",
+        "decimals": 18,
+        "label": "Lido wstETH"
+    },
+    {
+        "chain_id": 1,
+        "address": "0xae7ab96520de3a18e5e111b5eaab095312d7fe84",
+        "symbol": "stETH",
+        "decimals": 18,
+        "label": "Lido stETH"
+    }
+];

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "clanker-wallet",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
+    "./tokens": {
+      "types": "./dist/tokens.d.ts",
+      "import": "./dist/tokens.js"
+    },
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"