clanker-wallet 0.4.0 → 0.4.2

package/README.md

@@ -14,6 +14,8 @@ npx clanker-wallet
 bunx clanker-wallet
 ```
 
+Running in a sandbox (e.g. Claude Code)? Allow a WebSocket to the relay, `wss://relay.clanker-wallet.xyz/ws` (the `relay` URL in the pairing JSON), or `tx` fails with exit code 3. If the sandbox only lets traffic out through `HTTPS_PROXY`, run the CLI as `NODE_USE_ENV_PROXY=1 clanker-wallet ...` (Node 24+); Node ignores the proxy otherwise. `pair` writes `~/.clanker-wallet/` and the other commands write there too, so allow writes (see [State](#state)).
+
 ## Quick Start
 
 ```bash
@@ -22,8 +24,9 @@ bunx clanker-wallet
 # 2. Pair (one-time) — extract the JSON from the prompt
 clanker-wallet pair '{"version":1,"pubkey":"ab12...","relay":"wss://...","wallet":"0x..."}'
 
-# 3. Send a transaction (blocks until human approves or rejects)
-clanker-wallet tx --chain 1 --to 0xRecipient --value 1000000000000000000 --reason "swap ETH for USDC"
+# 3. Send a transaction (blocks until human approves or rejects; 1 h by default)
+#    0.001 ETH on Base Sepolia (84532) to the burn address. --value is in wei.
+clanker-wallet tx --chain 84532 --to 0x000000000000000000000000000000000000dEaD --value 1000000000000000 --reason "send 0.001 ETH on base sepolia"
 
 # 4. Check status anytime
 clanker-wallet status
@@ -33,7 +36,9 @@ clanker-wallet status
 
 ### `pair`
 
-Pair with a human's web app. Run once — identity and pairing are saved to `~/.clanker-wallet/`.
+Pair with a human's web app. Run once — `pair` writes identity and pairing to `~/.clanker-wallet/`.
+
+If the pairing JSON contains `"mode":"managed"`, the relay simulates each transaction for the human's review screen, so `tx` also sends the plain transaction fields to it. Otherwise the relay only sees ciphertext. Pair with the JSON as given.
 
 ```bash
 clanker-wallet pair '<pairing JSON from web app>'
@@ -42,33 +47,36 @@ clanker-wallet pair '<pairing JSON from web app>'
 
 ### `tx`
 
-Send a transaction request. Blocks until the human approves or rejects.
+Send a transaction request. Blocks until the human approves or rejects, for up to 1 hour by default; `--timeout <ms>` changes that. If your shell tool kills long commands, run `tx` in the background and read its output when it exits.
 
 ```bash
 clanker-wallet tx \
-  --chain 1 \
-  --to 0xRecipient \
-  --value 1000000000000000000 \
+  --chain 84532 \
+  --to 0x000000000000000000000000000000000000dEaD \
+  --value 1000000000000000 \
   --data 0x \
-  --reason "swap ETH for USDC" \
+  --reason "send 0.001 ETH on base sepolia" \
   --urgency medium \
-  --timeout 120000
+  --timeout 600000
 # approved → {"tx_hash":"0x...","status":"approved"}
 # rejected → {"status":"rejected","error":"..."} (exit code 1)
 # timeout  → {"status":"timeout","error":"..."}  (exit code 2)
+# bad flag → "invalid --to: ..." on stderr, nothing sent (exit code 5)
 ```
 
+`--to` must be `0x` + 40 hex characters (mixed case must pass the EIP-55 checksum), `--value` a whole number of wei, `--data` even-length hex. See [SKILL.md](./SKILL.md) for ERC-20 examples.
+
 **Flags:**
 | Flag | Required | Default | Description |
 |------|----------|---------|-------------|
-| `--chain <id>` | yes | — | Chain ID (1=Ethereum, 137=Polygon, 8453=Base) |
+| `--chain <id>` | yes | — | Chain ID (1=Ethereum, 8453=Base, 84532=Base Sepolia) |
 | `--to <address>` | yes | — | Recipient address |
 | `--value <wei>` | no | `0` | Value in wei (1 ETH = `1000000000000000000`) |
 | `--data <hex>` | no | `0x` | Calldata hex |
 | `--reason <text>` | no | — | Shown to human |
 | `--urgency <level>` | no | — | `low`, `medium`, or `high` |
 | `--expected-outcome <text>` | no | — | What will happen |
-| `--timeout <ms>` | no | `3600000` | How long to wait |
+| `--timeout <ms>` | no | `3600000` (1 h) | How long `tx` blocks waiting for the human |
 
 ### `status`
 
@@ -97,7 +105,7 @@ clanker-wallet whoami
 | 2 | Timeout |
 | 3 | Connection/relay error |
 | 4 | Not paired |
-| 5 | Invalid arguments |
+| 5 | Invalid arguments (bad or missing flag; nothing sent) |
 
 ## State
 
@@ -119,6 +127,7 @@ Identity and pairing are persisted in `~/.clanker-wallet/`:
 | Base | 8453 |
 | Optimism | 10 |
 | Sepolia (testnet) | 11155111 |
+| Base Sepolia (testnet) | 84532 |
 
 ---
 
@@ -136,17 +145,22 @@ import { ClankerWallet } from 'clanker-wallet'
 const wallet = new ClankerWallet({ agentName: 'my-bot' })
 wallet.pair(pairingJson)
 
+// 0.001 ETH on Base Sepolia; value is wei (string or bigint)
 const txHash = await wallet.requestTx({
-  chain_id: 1,
-  transaction: { to: '0x...', value: '1000000000000000000', data: '0x' },
-  context: { reason: 'Buy tokens', urgency: 'medium' },
+  chain_id: 84532,
+  transaction: { to: '0x000000000000000000000000000000000000dEaD', value: '1000000000000000', data: '0x' },
+  context: { reason: 'send 0.001 ETH on base sepolia', urgency: 'medium' },
 })
 ```
 
+`requestTx` throws `InvalidTxError` (with `field` and `reason`) before anything is sent if `chain_id`, `to`, `value` or `data` is malformed.
+
 See full API: [`src/`](./src/)
 
 ## Python SDK
 
+Requires Python 3.10+.
+
 ```bash
 pip install clanker-wallet
 ```
@@ -158,9 +172,9 @@ agent = ClankerWallet()
 agent.pair(pairing_json)
 
 tx_hash = await agent.request_tx(RequestTxOptions(
-    chain_id=1,
-    transaction=Transaction(to="0x...", value="1000000000000000000", data="0x"),
-    context=TxContext(reason="Buy tokens"),
+    chain_id=84532,  # base sepolia
+    transaction=Transaction(to="0x000000000000000000000000000000000000dEaD", value="1000000000000000", data="0x"),
+    context=TxContext(reason="send 0.001 ETH on base sepolia"),
 ))
 ```
 

package/SKILL.md

@@ -16,8 +16,26 @@ npm install -g clanker-wallet
 
 Or use without installing: `npx clanker-wallet` / `bunx clanker-wallet`
 
+### Running in a sandbox
+
+If your commands run in a sandbox (e.g. Claude Code), the CLI needs:
+
+- **network:** a WebSocket to the relay, `wss://relay.clanker-wallet.xyz/ws` (the `relay` URL in the pairing JSON). Without it `tx` fails with exit code 3.
+- **the sandbox proxy:** if the sandbox only lets traffic out through `HTTPS_PROXY` (Claude Code does), Node ignores it unless you run the CLI as `NODE_USE_ENV_PROXY=1 clanker-wallet ...` (Node 24+). The exit-3 error says so when this applies.
+- **files:** `pair` writes your identity and the pairing to `~/.clanker-wallet/`, and the other commands write there too (they fix file permissions and create the identity if it is missing). Allow writes, not just reads.
+
+Ask the human to allow the host and the directory before you pair.
+
 ## Pairing (one-time)
 
+Before you can send transactions, check if you're already paired:
+
+```bash
+clanker-wallet status
+```
+
+If `paired: true`, skip pairing.
+
 The human will paste a prompt block from https://clanker-wallet.xyz that looks like this:
 
 > read the setup guide first: https://clanker-wallet.xyz/llms.txt
@@ -33,7 +51,9 @@ clanker-wallet pair '{"version":1,"pubkey":"ab12...","relay":"wss://...","wallet
 
 If the human only pastes raw JSON (no prompt prose), pair with it directly. If they only paste the URL, ask them to click "copy prompt for agent" on the pairing screen.
 
-This saves identity and pairing to `~/.clanker-wallet/`. You only need to do this once.
+`pair` writes your identity and the pairing to `~/.clanker-wallet/`. You only need to do this once.
+
+If the JSON contains `"mode":"managed"`, the human chose managed mode: the relay simulates each transaction for the review screen, so `tx` also sends the plain transaction fields (from, to, value, data, chainId) to the relay, which shares them with its simulation provider. Without it (or with `"mode":"encrypted"`) the relay only sees ciphertext. Pair with the JSON exactly as given either way.
 
 ### Trust (first request)
 
@@ -53,7 +73,7 @@ If they agree, **every time you send a `tx` command**, immediately send a messag
 
 Example notification:
 > Transaction awaiting your approval
-> I'm requesting to send 0.001 ETH on Sepolia to a test address.
+> I'm requesting to send 0.001 ETH on Base Sepolia to a test address.
 > Urgency: normal
 > [Approve or reject here](https://clanker-wallet.xyz)
 
@@ -61,37 +81,41 @@ Example notification:
 
 ```bash
 clanker-wallet tx \
-  --chain 1 \
-  --to 0xRecipientAddress \
+  --chain 84532 \
+  --to 0x000000000000000000000000000000000000dEaD \
   --value 1000000000000000 \
-  --reason "Send 0.001 ETH to recipient" \
+  --reason "Send 0.001 ETH on Base Sepolia to a test address" \
   --urgency medium \
-  --timeout 120000
+  --timeout 600000
 ```
 
-The command **blocks until the human approves or rejects**. Output is JSON:
+This sends 0.001 ETH (`1000000000000000` wei) on Base Sepolia (chain `84532`) to the burn address `0x000000000000000000000000000000000000dEaD`.
+
+The command **blocks until the human approves or rejects**, for up to 1 hour by default. Pass `--timeout <ms>` to wait a different time (`600000` = 10 minutes). If your shell tool kills commands after a few minutes, run `tx` in the background and read its output when it exits. Output is JSON:
 - Approved: `{"tx_hash":"0x...","status":"approved"}` (exit code 0)
 - Rejected: `{"status":"rejected","error":"..."}` (exit code 1)
 - Timeout: `{"status":"timeout","error":"..."}` (exit code 2)
+- Invalid `--chain`, `--to`, `--value`, `--data` or `--timeout`: a one-line `invalid --<flag>: ...` message on stderr and nothing is sent (exit code 5)
 
 ## Critical Details
 
-- **value is in WEI, not ETH.** 1 ETH = `1000000000000000000`. Use string, not number.
-- **data is hex-encoded calldata.** Use `0x` for simple ETH transfers. For contract calls, encode the function call.
+- **value is in WEI, not ETH.** 1 ETH = `1000000000000000000`. A whole number: no decimals, no `1e18`.
+- **data is hex-encoded calldata.** Use `0x` for simple ETH transfers. For contract calls, encode the function call (see ERC-20 transfer below). Never put placeholder text inside the hex.
+- **to must be a real address**: `0x` + 40 hex characters. Mixed-case addresses must carry a valid EIP-55 checksum.
 - **The human must be online to approve.** Set a reasonable `--timeout`. Always notify the human through your communication channel when you send a request (if they opted in).
 
 ## tx Flags
 
 | Flag | Required | Default | Description |
 |------|----------|---------|-------------|
-| `--chain <id>` | yes | — | Chain ID (1=Ethereum, 137=Polygon, 8453=Base) |
+| `--chain <id>` | yes | — | Chain ID (1=Ethereum, 8453=Base, 84532=Base Sepolia) |
 | `--to <address>` | yes | — | Recipient address |
 | `--value <wei>` | no | `0` | Value in wei |
 | `--data <hex>` | no | `0x` | Calldata hex |
 | `--reason <text>` | no | — | Shown to human |
 | `--urgency <level>` | no | — | `low`, `medium`, or `high` |
 | `--expected-outcome <text>` | no | — | What will happen |
-| `--timeout <ms>` | no | `3600000` | How long to wait |
+| `--timeout <ms>` | no | `3600000` (1 h) | How long `tx` blocks waiting for the human |
 
 ## Common Chain IDs
 
@@ -103,33 +127,37 @@ The command **blocks until the human approves or rejects**. Output is JSON:
 | Base | 8453 |
 | Optimism | 10 |
 | Sepolia (testnet) | 11155111 |
+| Base Sepolia (testnet) | 84532 |
 
 ## Common Patterns
 
 ### Simple ETH transfer
 ```bash
-clanker-wallet tx --chain 1 --to 0xRecipientAddress --value 1000000000000000 --reason "Send 0.001 ETH"
+clanker-wallet tx --chain 84532 --to 0x000000000000000000000000000000000000dEaD --value 1000000000000000 --reason "Send 0.001 ETH"
 ```
 
 ### ERC-20 token transfer
+Calldata is the 4-byte selector followed by each argument as a 32-byte word: the address left-padded with zeros, the amount as big-endian hex in the token's smallest unit. This sends 0.001 WETH (`1000000000000000` = `0x38d7ea4c68000`, 18 decimals) on Base Sepolia, where WETH is `0x4200000000000000000000000000000000000006`:
+
 ```bash
 # transfer(address to, uint256 amount) — selector 0xa9059cbb
-# encode to + amount as 32-byte padded hex
 clanker-wallet tx \
-  --chain 1 \
-  --to 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
-  --data 0xa9059cbb000000000000000000000000RecipientAddr00000000000000000000000000000000000000000000000000000000000f4240 \
-  --reason "Transfer 1 USDC"
+  --chain 84532 \
+  --to 0x4200000000000000000000000000000000000006 \
+  --data 0xa9059cbb000000000000000000000000000000000000000000000000000000000000dead00000000000000000000000000000000000000000000000000038d7ea4c68000 \
+  --reason "Transfer 0.001 WETH to a test address"
 ```
 
+Encode it with a library rather than by hand, e.g. `cast calldata "transfer(address,uint256)" 0x000000000000000000000000000000000000dEaD 1000000000000000` (foundry) or viem `encodeFunctionData({ abi: erc20Abi, functionName: 'transfer', args: [to, amount] })`.
+
 ### ERC-20 approval
 ```bash
 # approve(address spender, uint256 amount) — selector 0x095ea7b3
 clanker-wallet tx \
-  --chain 1 \
-  --to 0xTokenContractAddress \
-  --data 0x095ea7b3000000000000000000000000SpenderAddr0000000000000000000000000000000000000000000000000000000000000f4240 \
-  --reason "Approve 1 USDC spend for DeFi protocol"
+  --chain 84532 \
+  --to 0x4200000000000000000000000000000000000006 \
+  --data 0x095ea7b3000000000000000000000000000000000000000000000000000000000000dead00000000000000000000000000000000000000000000000000038d7ea4c68000 \
+  --reason "Approve a test address to spend 0.001 WETH"
 ```
 
 ## Other Commands
@@ -146,7 +174,8 @@ clanker-wallet whoami
 
 ## Troubleshooting
 
+- **exit code 5 / "invalid --flag: ..."** — fix the named flag; nothing was sent. Usually a placeholder `--to`, a `--value` in ETH instead of wei, or `--data` that isn't even-length hex
 - **exit code 4 / "not paired"** — run `clanker-wallet pair '<JSON>'` first
 - **exit code 2 / timeout** — human didn't respond in time, increase `--timeout` or ask them to check the web app
 - **exit code 1 / "rejected"** — human clicked reject. Explain why the tx is needed and try again if appropriate.
-- **exit code 3 / connection error** — relay may be down, try again in a few seconds
+- **exit code 3 / "relay connection error: could not reach wss://..."** — if you run in a sandbox or behind a firewall, allow that host (`relay.clanker-wallet.xyz` by default) and, if the error mentions it, rerun with `NODE_USE_ENV_PROXY=1` (see "Running in a sandbox"); otherwise the relay may be down or rate limiting, try again in a few seconds

package/bin/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { ClankerWallet } from '../dist/index.js'
+import { ClankerWallet, InvalidTxError, validateTx } from '../dist/index.js'
 import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from 'fs'
 import { join } from 'path'
 import { homedir } from 'os'
@@ -10,6 +10,9 @@ const IDENTITY_FILE = join(STATE_DIR, 'identity.json')
 const PAIRING_FILE = join(STATE_DIR, 'pairing.json')
 
 const EXIT = { OK: 0, REJECTED: 1, TIMEOUT: 2, CONNECTION: 3, NOT_PAIRED: 4, BAD_ARGS: 5 }
+const DEFAULT_TIMEOUT_MS = 3_600_000
+/** validateTx field -> the tx flag that sets it */
+const FIELD_FLAGS = { chain_id: '--chain', to: '--to', value: '--value', data: '--data' }
 
 // ── helpers ──────────────────────────────────────────────────────────
 const hex = (bytes) => Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('')
@@ -135,12 +138,20 @@ async function cmdTx(flags) {
   if (!chain) die('missing --chain', EXIT.BAD_ARGS)
   if (!to) die('missing --to', EXIT.BAD_ARGS)
 
-  const chainId = parseInt(chain, 10)
-  if (isNaN(chainId)) die('--chain must be a number', EXIT.BAD_ARGS)
+  if (!/^[0-9]+$/.test(chain)) die(`invalid --chain: must be a positive integer chain id, got ${JSON.stringify(chain)}`, EXIT.BAD_ARGS)
+  if (flags.timeout !== undefined && !/^[1-9][0-9]*$/.test(flags.timeout)) {
+    die(`invalid --timeout: must be a positive number of milliseconds, got ${JSON.stringify(flags.timeout)}`, EXIT.BAD_ARGS)
+  }
+  const timeout = flags.timeout ? Number(flags.timeout) : DEFAULT_TIMEOUT_MS
 
-  const value = flags.value || '0'
-  const data = flags.data || '0x'
-  const timeout = flags.timeout ? parseInt(flags.timeout, 10) : 3_600_000
+  // same checks requestTx runs, done here so a bad flag exits 5 instead of surfacing as a connection error
+  let request
+  try {
+    request = validateTx(Number(chain), { to, value: flags.value ?? '0', data: flags.data ?? '0x' })
+  } catch (err) {
+    if (!(err instanceof InvalidTxError)) throw err
+    die(`invalid ${FIELD_FLAGS[err.field]}: ${err.reason}`, EXIT.BAD_ARGS)
+  }
 
   const context = {}
   if (flags.reason) context.reason = flags.reason
@@ -159,8 +170,8 @@ async function cmdTx(flags) {
 
   try {
     const txHash = await wallet.requestTx({
-      chain_id: chainId,
-      transaction: { to, value, data },
+      chain_id: request.chain_id,
+      transaction: request.transaction,
       context: Object.keys(context).length > 0 ? context : undefined,
       timeout_ms: timeout,
     })
@@ -202,6 +213,11 @@ function cmdWhoami() {
   })
 }
 
+function cmdVersion() {
+  const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+  process.stdout.write(version + '\n')
+}
+
 function showHelp() {
   process.stderr.write(`clanker-wallet — human-approved transactions for AI agents
 
@@ -212,30 +228,31 @@ commands:
   whoami          show agent identity
 
 tx flags:
-  --chain <id>              chain ID (required) — 1, 137, 8453, etc.
-  --to <address>            recipient (required)
-  --value <wei>             value in wei (default: 0)
-  --data <hex>              calldata (default: 0x)
-  --reason <text>           shown to human
-  --urgency <low|med|high>  priority hint
-  --expected-outcome <text> what will happen
-  --timeout <ms>            wait time (default: 3600000)
+  --chain <id>                 chain ID (required) — 1, 8453, 84532 (base sepolia), etc.
+  --to <address>               recipient (required)
+  --value <wei>                value in wei, not ETH (default: 0; 1 ETH = 1000000000000000000)
+  --data <hex>                 calldata (default: 0x)
+  --reason <text>              shown to human
+  --urgency <low|medium|high>  priority hint
+  --expected-outcome <text>    what will happen
+  --timeout <ms>               how long tx blocks waiting for the human (default: 3600000 = 1 h)
 
 exit codes:
   0  success
   1  rejected by human
   2  timeout
-  3  connection error
+  3  connection error (in a sandbox or behind a firewall, allow the relay host, wss://relay.clanker-wallet.xyz/ws by default;
+     behind HTTPS_PROXY run with NODE_USE_ENV_PROXY=1)
   4  not paired
   5  invalid arguments
 
 examples:
   clanker-wallet pair '{"version":1,"pubkey":"ab12...","relay":"wss://...","wallet":"0x..."}'
-  clanker-wallet tx --chain 1 --to 0xRecipient --value 1000000000000000000 --reason "swap ETH"
+  clanker-wallet tx --chain 84532 --to 0x000000000000000000000000000000000000dEaD --value 1000000000000000 --reason "send 0.001 ETH on base sepolia"
   clanker-wallet status
   clanker-wallet whoami
 
-docs: https://github.com/almogdepaz/clanker-wallet
+docs: https://clanker-wallet.xyz/SKILL.md
 web:  https://clanker-wallet.xyz
 `)
 }
@@ -256,6 +273,10 @@ switch (cmd) {
   case 'whoami':
     cmdWhoami()
     break
+  case '--version':
+  case '-v':
+    cmdVersion()
+    break
   case 'help':
   case '--help':
   case '-h':

package/dist/client.js

@@ -1,6 +1,17 @@
 import { decryptMessage, encryptMessage, fromHex, generateKeypair, keypairFromSecret, signMessage, signingKeypairFromSeed, toHex } from './crypto.js';
 import { TypedEmitter } from './events.js';
+import { 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 */
+function proxyHint() {
+    const env = globalThis.process?.env;
+    if (!env || env.NODE_USE_ENV_PROXY)
+        return '';
+    return env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy
+        ? '; HTTPS_PROXY is set but node ignores it, rerun with NODE_USE_ENV_PROXY=1 (node 24+)'
+        : '';
+}
 export class ClankerWallet extends TypedEmitter {
     publicKey;
     secretKey;
@@ -57,6 +68,8 @@ export class ClankerWallet extends TypedEmitter {
         if (!this.pairing) {
             throw new Error('not paired — call pair() first');
         }
+        // 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)}`;
@@ -64,8 +77,8 @@ export class ClankerWallet extends TypedEmitter {
             request_id: requestId,
             agent_id: this.agentId,
             timestamp: new Date().toISOString(),
-            chain_id: options.chain_id,
-            transaction: options.transaction,
+            chain_id,
+            transaction,
             context: options.context,
             signature: '', // set below after signing
         };
@@ -100,8 +113,9 @@ export class ClankerWallet extends TypedEmitter {
                 return;
             }
             ws.addEventListener('error', () => {
+                // node's WebSocket error event carries no cause, so name the url: a sandbox or firewall blocking it looks the same as an outage
                 if (!settled)
-                    fail('relay connection error');
+                    fail(`relay connection error: could not reach ${relayUrl} (${UNREACHABLE_HINT}${proxyHint()})`);
             });
             ws.addEventListener('close', () => {
                 this.emit('disconnected', {});
@@ -140,10 +154,10 @@ export class ClankerWallet extends TypedEmitter {
                     if (mode === 'managed') {
                         wsMsg.simulate = {
                             from: humanWallet || '',
-                            to: options.transaction.to,
-                            value: options.transaction.value,
-                            data: options.transaction.data,
-                            chainId: options.chain_id,
+                            to: transaction.to,
+                            value: transaction.value,
+                            data: transaction.data,
+                            chainId: chain_id,
                         };
                     }
                     ws.send(JSON.stringify(wsMsg));

package/dist/index.d.ts

@@ -3,4 +3,6 @@ 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 type { AgentEnvelope, PairingData, RequestTxOptions, Transaction, TxContext, TxRequest, TxResponse, } from './types.js';
+export { InvalidTxError, isChecksumAddress, validateTx } from './validate.js';
+export type { TxField } from './validate.js';
+export type { AgentEnvelope, PairingData, RequestTxOptions, Transaction, TxContext, TxInput, TxRequest, TxResponse, } from './types.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export { ClankerWallet } 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';

package/dist/keccak.d.ts

@@ -0,0 +1,5 @@
+/**
+ * keccak-256 (the pre-NIST padding ethereum uses; NIST sha3-256 differs), only for
+ * EIP-55 address checksums. inputs are a few dozen bytes, so lanes are plain bigints.
+ */
+export declare function keccak256(input: Uint8Array): Uint8Array;

package/dist/keccak.js

@@ -0,0 +1,82 @@
+/**
+ * keccak-256 (the pre-NIST padding ethereum uses; NIST sha3-256 differs), only for
+ * EIP-55 address checksums. inputs are a few dozen bytes, so lanes are plain bigints.
+ */
+const MASK64 = (1n << 64n) - 1n;
+const RATE_BYTES = 136;
+const rotl = (x, n) => n === 0 ? x : ((x << BigInt(n)) | (x >> BigInt(64 - n))) & MASK64;
+// round constants from the degree-8 LFSR in the keccak reference
+const ROUND_CONSTANTS = (() => {
+    const out = [];
+    let r = 1;
+    for (let round = 0; round < 24; round++) {
+        let rc = 0n;
+        for (let j = 0; j < 7; j++) {
+            if (r & 1)
+                rc |= 1n << BigInt((1 << j) - 1);
+            r = r & 0x80 ? ((r << 1) ^ 0x71) & 0xff : (r << 1) & 0xff;
+        }
+        out.push(rc);
+    }
+    return out;
+})();
+// rho offsets, indexed by x + 5y
+const ROTATIONS = (() => {
+    const out = new Array(25).fill(0);
+    let x = 1;
+    let y = 0;
+    for (let t = 0; t < 24; t++) {
+        out[x + 5 * y] = (((t + 1) * (t + 2)) / 2) % 64;
+        [x, y] = [y, (2 * x + 3 * y) % 5];
+    }
+    return out;
+})();
+function keccakF(a) {
+    const b = new Array(25);
+    const c = new Array(5);
+    for (let round = 0; round < 24; round++) {
+        // theta
+        for (let x = 0; x < 5; x++)
+            c[x] = a[x] ^ a[x + 5] ^ a[x + 10] ^ a[x + 15] ^ a[x + 20];
+        for (let x = 0; x < 5; x++) {
+            const d = c[(x + 4) % 5] ^ rotl(c[(x + 1) % 5], 1);
+            for (let y = 0; y < 25; y += 5)
+                a[x + y] ^= d;
+        }
+        // rho + pi
+        for (let x = 0; x < 5; x++) {
+            for (let y = 0; y < 5; y++) {
+                b[y + 5 * ((2 * x + 3 * y) % 5)] = rotl(a[x + 5 * y], ROTATIONS[x + 5 * y]);
+            }
+        }
+        // chi
+        for (let y = 0; y < 25; y += 5) {
+            for (let x = 0; x < 5; x++) {
+                a[x + y] = b[x + y] ^ (~b[((x + 1) % 5) + y] & MASK64 & b[((x + 2) % 5) + y]);
+            }
+        }
+        // iota
+        a[0] ^= ROUND_CONSTANTS[round];
+    }
+}
+export function keccak256(input) {
+    // pad10*1 with keccak's 0x01 domain byte
+    const padded = new Uint8Array(Math.floor(input.length / RATE_BYTES + 1) * RATE_BYTES);
+    padded.set(input);
+    padded[input.length] ^= 0x01;
+    padded[padded.length - 1] ^= 0x80;
+    const state = new Array(25).fill(0n);
+    for (let off = 0; off < padded.length; off += RATE_BYTES) {
+        for (let i = 0; i < RATE_BYTES / 8; i++) {
+            let lane = 0n;
+            for (let k = 7; k >= 0; k--)
+                lane = (lane << 8n) | BigInt(padded[off + i * 8 + k]);
+            state[i] ^= lane;
+        }
+        keccakF(state);
+    }
+    const out = new Uint8Array(32);
+    for (let i = 0; i < 32; i++)
+        out[i] = Number((state[i >> 3] >> BigInt(8 * (i & 7))) & 0xffn);
+    return out;
+}

package/dist/types.d.ts

@@ -4,6 +4,12 @@ export interface Transaction {
     value: string;
     data: string;
 }
+/** transaction as passed to requestTx: value in wei, data defaults to "0x" */
+export interface TxInput {
+    to: string;
+    value: string | bigint;
+    data?: string;
+}
 /** optional context about the transaction */
 export interface TxContext {
     reason?: string;
@@ -46,7 +52,8 @@ export interface PairingData {
 /** options for requestTx */
 export interface RequestTxOptions {
     chain_id: number;
-    transaction: Transaction;
+    /** checked before sending; an invalid field throws InvalidTxError */
+    transaction: TxInput;
     context?: TxContext;
     /** timeout in ms (default: 3_600_000 = 1hr) */
     timeout_ms?: number;

package/dist/validate.d.ts

@@ -0,0 +1,19 @@
+import type { Transaction, TxInput } from './types.js';
+export type TxField = 'chain_id' | 'to' | 'value' | 'data';
+/** a tx request field failed validation; nothing was sent */
+export declare class InvalidTxError extends Error {
+    readonly field: TxField;
+    readonly reason: string;
+    constructor(field: TxField, reason: string);
+}
+/** EIP-55: a mixed-case address must carry the checksum; single-case addresses are unchecksummed */
+export declare function isChecksumAddress(address: string): boolean;
+/**
+ * check a tx request before anything is signed or sent, and normalize it to the wire
+ * format (value as a decimal wei string, data defaulting to "0x").
+ * throws InvalidTxError naming the first bad field.
+ */
+export declare function validateTx(chainId: unknown, tx: TxInput | Record<string, unknown>): {
+    chain_id: number;
+    transaction: Transaction;
+};

package/dist/validate.js

@@ -0,0 +1,65 @@
+import { keccak256 } from './keccak.js';
+/** a tx request field failed validation; nothing was sent */
+export class InvalidTxError extends Error {
+    field;
+    reason;
+    constructor(field, reason) {
+        super(`invalid ${field}: ${reason}`);
+        this.field = field;
+        this.reason = reason;
+        this.name = 'InvalidTxError';
+    }
+}
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+const DECIMAL_RE = /^[0-9]+$/;
+const CALLDATA_RE = /^0x(?:[0-9a-fA-F]{2})*$/;
+/** short, quoted rendering of a rejected input for error messages */
+function shown(v) {
+    const s = typeof v === 'bigint' ? `${v}n` : JSON.stringify(v) ?? String(v);
+    return s.length > 70 ? `${s.slice(0, 67)}...` : s;
+}
+/** EIP-55: a mixed-case address must carry the checksum; single-case addresses are unchecksummed */
+export function isChecksumAddress(address) {
+    if (!ADDRESS_RE.test(address))
+        return false;
+    const body = address.slice(2);
+    if (body === body.toLowerCase() || body === body.toUpperCase())
+        return true;
+    const lower = body.toLowerCase();
+    const hash = keccak256(new TextEncoder().encode(lower));
+    for (let i = 0; i < 40; i++) {
+        const nibble = (hash[i >> 1] >> (i % 2 === 0 ? 4 : 0)) & 0xf;
+        const expected = nibble >= 8 ? lower[i].toUpperCase() : lower[i];
+        if (body[i] !== expected)
+            return false;
+    }
+    return true;
+}
+/**
+ * check a tx request before anything is signed or sent, and normalize it to the wire
+ * format (value as a decimal wei string, data defaulting to "0x").
+ * throws InvalidTxError naming the first bad field.
+ */
+export function validateTx(chainId, tx) {
+    if (typeof chainId !== 'number' || !Number.isSafeInteger(chainId) || chainId <= 0) {
+        throw new InvalidTxError('chain_id', `must be a positive integer, got ${shown(chainId)}`);
+    }
+    const { to, value, data = '0x' } = tx;
+    if (typeof to !== 'string' || !ADDRESS_RE.test(to)) {
+        throw new InvalidTxError('to', `must be 0x followed by 40 hex characters, got ${shown(to)}`);
+    }
+    if (!isChecksumAddress(to)) {
+        throw new InvalidTxError('to', `mixed-case address fails its EIP-55 checksum, got ${shown(to)}`);
+    }
+    let wei;
+    if (typeof value === 'bigint' && value >= 0n)
+        wei = value.toString();
+    else if (typeof value === 'string' && DECIMAL_RE.test(value))
+        wei = value;
+    else
+        throw new InvalidTxError('value', `must be a non-negative integer amount of wei (decimal string or bigint), got ${shown(value)}`);
+    if (typeof data !== 'string' || !CALLDATA_RE.test(data)) {
+        throw new InvalidTxError('data', `must be 0x followed by an even number of hex characters, got ${shown(data)}`);
+    }
+    return { chain_id: chainId, transaction: { to, value: wei, data } };
+}

package/package.json

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