clanker-wallet 0.3.0 → 0.4.1

package/README.md

@@ -17,12 +17,14 @@ bunx clanker-wallet
 ## Quick Start
 
 ```bash
-# 1. Human goes to https://clanker-wallet.xyz, connects wallet, copies pairing JSON
-# 2. Pair (one-time)
+# 1. Human goes to https://clanker-wallet.xyz, connects wallet, clicks "copy prompt for agent",
+#    pastes the prompt to you. The prompt contains a JSON pairing code.
+# 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
@@ -41,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`
 
@@ -80,11 +85,11 @@ clanker-wallet status
 
 ### `whoami`
 
-Show agent identity.
+Show agent identity. `fingerprint` (first 16 hex chars of the public key) is what the web app shows for this agent; the human compares it before trusting the agent.
 
 ```bash
 clanker-wallet whoami
-# → {"agent_id":"agent_abc123","public_key":"ab12cd..."}
+# → {"agent_id":"agent_abc123","public_key":"ab12cd34ef567890...","fingerprint":"ab12 cd34 ef56 7890"}
 ```
 
 ## Exit Codes
@@ -96,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
 
@@ -118,6 +123,7 @@ Identity and pairing are persisted in `~/.clanker-wallet/`:
 | Base | 8453 |
 | Optimism | 10 |
 | Sepolia (testnet) | 11155111 |
+| Base Sepolia (testnet) | 84532 |
 
 ---
 
@@ -135,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
 ```
@@ -157,21 +168,21 @@ 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"),
 ))
 ```
 
 ## How It Works
 
-1. Human opens [clanker-wallet.xyz](https://clanker-wallet.xyz), connects wallet, gets a pairing code
-2. Agent runs `clanker-wallet pair` — establishes E2E encrypted channel
+1. Human opens [clanker-wallet.xyz](https://clanker-wallet.xyz), connects wallet, clicks "copy prompt for agent" — gets a paste-ready prompt that bundles intent, the setup guide URL, and the pairing JSON
+2. Human pastes the prompt to their AI agent. Agent extracts the JSON and runs `clanker-wallet pair` — establishes E2E encrypted channel
 3. Agent runs `clanker-wallet tx` — encrypts tx with nacl.box, sends via WebSocket relay
-4. Human reviews tx details, simulation, risk flags in the web app
+4. Human reviews tx details, simulation, risk flags in the web app. A new agent shows up as unverified with its fingerprint; auto-approve rules only apply after the human trusts it. Contract rules (address + methods) don't limit token amounts or recipients
 5. Human approves → wallet signs + broadcasts → agent gets the tx hash
 
-All messages are encrypted end-to-end. The relay server never sees plaintext.
+Request and response payloads are encrypted end-to-end; the relay only forwards them. Exception: when paired in managed mode, the agent also sends the transaction fields (from, to, value, data, chainId) to the relay for simulation.
 
 ## License
 

package/SKILL.md

@@ -18,22 +18,35 @@ Or use without installing: `npx clanker-wallet` / `bunx clanker-wallet`
 
 ## Pairing (one-time)
 
-Before you can send transactions, you must pair with the human. Ask them:
+Before you can send transactions, check if you're already paired:
 
-> "I need to send blockchain transactions on your behalf. Please go to https://clanker-wallet.xyz, connect your wallet, and give me the pairing JSON."
-
-The human will give you a JSON string like:
-```json
-{"version":1,"pubkey":"ab12cd...","relay":"wss://clanker-wallet-relay-625052130878.us-east1.run.app/ws","wallet":"0x..."}
+```bash
+clanker-wallet status
 ```
 
-Pair with it:
+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
+>
+> then pair using this code:
+> `{"version":1,"pubkey":"ab12cd...","relay":"wss://...","wallet":"0x..."}`
+
+Extract the JSON object (the line starting with `{`) and pair:
+
 ```bash
 clanker-wallet pair '{"version":1,"pubkey":"ab12...","relay":"wss://...","wallet":"0x..."}'
 ```
 
+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.
 
+### Trust (first request)
+
+The web app lists a new agent as unverified and shows its fingerprint (e.g. `ab12 cd34 ef56 7890`). Until the human compares it with the `fingerprint` from `clanker-wallet whoami` and clicks "trust this agent", none of their auto-approve rules apply: every tx waits for manual approval. Contract rules (contract address + allowed methods) do not limit token amounts or recipients: a rule allowing `transfer` on a token auto-approves any amount to any recipient. If asked, run `clanker-wallet whoami` and share the fingerprint.
+
 ### Transaction notifications
 
 After pairing, ask the human:
@@ -48,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)
 
@@ -56,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
 
@@ -98,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
@@ -136,11 +157,12 @@ clanker-wallet status
 
 # Show agent identity
 clanker-wallet whoami
-# → {"agent_id":"agent_abc123","public_key":"ab12cd..."}
+# → {"agent_id":"agent_abc123","public_key":"ab12cd34ef567890...","fingerprint":"ab12 cd34 ef56 7890"}
 ```
 
 ## 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,6 +1,6 @@
 #!/usr/bin/env node
-import { ClankerWallet } from '../dist/index.js'
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs'
+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,10 +10,15 @@ 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('')
 const fromHexStr = (h) => new Uint8Array(h.match(/.{2}/g).map(b => parseInt(b, 16)))
+/** short id the human compares in the web app: first 16 hex (64 bits) of the x25519 pubkey, "ab12 cd34 ef56 7890" */
+const fingerprint = (pubkeyHex) => pubkeyHex.slice(0, 16).toLowerCase().match(/.{1,4}/g).join(' ')
 
 function die(msg, code) {
   process.stderr.write(msg + '\n')
@@ -24,19 +29,25 @@ function out(obj) {
   process.stdout.write(JSON.stringify(obj) + '\n')
 }
 
+// owner-only; an existing dir from an older version is tightened too
 function ensureDir() {
-  if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true })
+  if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true, mode: 0o700 })
+  else chmodSync(STATE_DIR, 0o700)
 }
 
+// identity.json holds the agent secret key: owner-only, tightened if an older version left it readable
 function loadIdentity() {
   if (!existsSync(IDENTITY_FILE)) return null
+  ensureDir()
+  chmodSync(IDENTITY_FILE, 0o600)
   try { return JSON.parse(readFileSync(IDENTITY_FILE, 'utf8')) }
   catch { return null }
 }
 
 function saveIdentity(data) {
   ensureDir()
-  writeFileSync(IDENTITY_FILE, JSON.stringify(data, null, 2) + '\n')
+  writeFileSync(IDENTITY_FILE, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 })
+  chmodSync(IDENTITY_FILE, 0o600)
 }
 
 function loadPairing() {
@@ -127,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
@@ -145,13 +164,14 @@ async function cmdTx(flags) {
     pubkey: pairing.pubkey,
     relay: pairing.relay,
     wallet: pairing.wallet,
+    mode: pairing.mode || undefined,
   })
   wallet.pair(pairingJson)
 
   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,
     })
@@ -189,9 +209,15 @@ function cmdWhoami() {
   out({
     agent_id: wallet.agentId,
     public_key: hex(wallet.publicKey),
+    fingerprint: fingerprint(hex(wallet.publicKey)),
   })
 }
 
+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
 
@@ -202,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
@@ -221,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
 `)
 }
@@ -246,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;
@@ -43,6 +44,7 @@ export class ClankerWallet extends TypedEmitter {
             humanPubkeyHex: data.pubkey,
             relayUrl: data.relay,
             humanWallet: data.wallet || null,
+            mode: data.mode || 'encrypted',
         };
         this.emit('paired', { relay: data.relay, wallet: data.wallet || '' });
         return data;
@@ -56,15 +58,17 @@ export class ClankerWallet extends TypedEmitter {
         if (!this.pairing) {
             throw new Error('not paired — call pair() first');
         }
-        const { humanPubkey, humanPubkeyHex, relayUrl } = this.pairing;
+        // reject malformed requests before anything reaches the relay
+        const { chain_id, transaction } = validateTx(options.chain_id, options.transaction);
+        const { humanPubkey, humanPubkeyHex, relayUrl, humanWallet, mode } = this.pairing;
         const timeoutMs = options.timeout_ms ?? DEFAULT_TIMEOUT_MS;
         const requestId = `req_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
         const txRequest = {
             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
         };
@@ -130,18 +134,32 @@ export class ClankerWallet extends TypedEmitter {
                         ciphertext,
                         signing_pubkey: this.signingPubkeyHex,
                     };
-                    ws.send(JSON.stringify({
+                    const wsMsg = {
                         type: 'message',
                         room: humanPubkeyHex,
                         payload: JSON.stringify(envelope),
-                    }));
+                    };
+                    // managed mode: relay gets plaintext tx params so it can simulate
+                    if (mode === 'managed') {
+                        wsMsg.simulate = {
+                            from: humanWallet || '',
+                            to: transaction.to,
+                            value: transaction.value,
+                            data: transaction.data,
+                            chainId: chain_id,
+                        };
+                    }
+                    ws.send(JSON.stringify(wsMsg));
                     this.emit('request_sent', { request_id: requestId });
                     return;
                 }
                 if (msg.type === 'message') {
                     try {
                         const envelope = JSON.parse(msg.payload);
-                        const plaintext = decryptMessage(envelope.ciphertext, fromHex(envelope.sender_pubkey), this.secretKey);
+                        // only the paired human may answer
+                        if (envelope.sender_pubkey?.toLowerCase() !== humanPubkeyHex.toLowerCase())
+                            return;
+                        const plaintext = decryptMessage(envelope.ciphertext, humanPubkey, this.secretKey);
                         if (!plaintext)
                             return;
                         const response = JSON.parse(plaintext);

package/dist/crypto.js

@@ -20,7 +20,13 @@ export function encryptMessage(message, recipientPublicKey, senderSecretKey) {
 }
 /** decrypt a nacl.box message. payload = base64(nonce + ciphertext). */
 export function decryptMessage(base64Payload, senderPublicKey, recipientSecretKey) {
-    const raw = base64ToBytes(base64Payload);
+    let raw;
+    try {
+        raw = base64ToBytes(base64Payload);
+    }
+    catch {
+        return null;
+    }
     if (raw.length <= nacl.box.nonceLength)
         return null;
     const nonce = raw.slice(0, nacl.box.nonceLength);
@@ -38,7 +44,13 @@ export function toHex(bytes) {
 }
 /** hex string → Uint8Array (strips 0x prefix if present) */
 export function fromHex(hex) {
-    const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+    const clean = hex.startsWith('0x') || hex.startsWith('0X') ? hex.slice(2) : hex;
+    if (clean.length % 2 !== 0) {
+        throw new Error('invalid hex string: length must be even');
+    }
+    if (!/^[0-9a-fA-F]*$/.test(clean)) {
+        throw new Error('invalid hex string: contains non-hex characters');
+    }
     const bytes = new Uint8Array(clean.length / 2);
     for (let i = 0; i < bytes.length; i++) {
         bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
@@ -47,7 +59,11 @@ export function fromHex(hex) {
 }
 /** derive an Ed25519 signing keypair from a 32-byte seed */
 export function signingKeypairFromSeed(seed) {
-    return nacl.sign.keyPair.fromSeed(seed);
+    if (seed.length !== nacl.sign.seedLength) {
+        throw new Error(`invalid seed length: expected ${nacl.sign.seedLength} bytes, got ${seed.length}`);
+    }
+    // copy to keep derivation independent of caller-owned mutable buffers
+    return nacl.sign.keyPair.fromSeed(new Uint8Array(seed));
 }
 /** sign a message string with an Ed25519 secret key. returns base64(signature). */
 export function signMessage(message, signingSecretKey) {

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;
@@ -40,11 +46,14 @@ export interface PairingData {
     pubkey: string;
     relay: string;
     wallet: string;
+    /** "encrypted" (default): relay sees only ciphertext. "managed": relay also receives tx params for simulation. */
+    mode?: 'encrypted' | 'managed';
 }
 /** 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.3.0",
+  "version": "0.4.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,7 +13,13 @@
   "bin": {
     "clanker-wallet": "bin/cli.js"
   },
-  "files": ["dist", "bin", "SKILL.md", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "bin",
+    "SKILL.md",
+    "README.md",
+    "LICENSE"
+  ],
   "license": "MIT",
   "author": "Clanker Wallet Contributors",
   "repository": {
@@ -21,7 +27,27 @@
     "url": "git+https://github.com/almogdepaz/clanker-wallet.git"
   },
   "homepage": "https://github.com/almogdepaz/clanker-wallet#readme",
-  "keywords": ["wallet", "ai-agent", "ethereum", "e2e-encrypted", "transaction-approval"],
+  "keywords": [
+    "wallet",
+    "ai-agent",
+    "ethereum",
+    "e2e-encrypted",
+    "transaction-approval",
+    "blockchain",
+    "web3",
+    "langchain",
+    "human-in-the-loop",
+    "evm",
+    "agent-wallet",
+    "llm",
+    "typescript",
+    "base",
+    "polygon",
+    "transaction",
+    "approval",
+    "defi",
+    "vercel-ai-sdk"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "dev": "tsc --watch",