clanker-wallet 0.4.0 → 0.4.1

package/README.md

@@ -22,8 +22,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
@@ -42,33 +43,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.
 
 ```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 +101,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 +123,7 @@ Identity and pairing are persisted in `~/.clanker-wallet/`:
 | Base | 8453 |
 | Optimism | 10 |
 | Sepolia (testnet) | 11155111 |
+| Base Sepolia (testnet) | 84532 |
 
 ---
 
@@ -136,17 +141,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 +168,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

@@ -18,6 +18,14 @@ Or use without installing: `npx clanker-wallet` / `bunx clanker-wallet`
 
 ## 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
@@ -53,7 +61,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 +69,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). 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 +115,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,6 +162,7 @@ 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.

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,14 +228,14 @@ 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
@@ -231,11 +247,11 @@ exit codes:
 
 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 +272,10 @@ switch (cmd) {
   case 'whoami':
     cmdWhoami()
     break
+  case '--version':
+  case '-v':
+    cmdVersion()
+    break
   case 'help':
   case '--help':
   case '-h':

package/dist/client.js

@@ -1,5 +1,6 @@
 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
 export class ClankerWallet extends TypedEmitter {
     publicKey;
@@ -57,6 +58,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 +67,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
         };
@@ -140,10 +143,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.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",