clanker-wallet 0.2.0 → 0.3.0

package/README.md

@@ -1,93 +1,177 @@
 # clanker-wallet
 
-TypeScript SDK for AI agents to request human-approved Ethereum transactions over an E2E encrypted relay.
+Human-approved blockchain transactions for AI agents. Agent proposes a tx, human reviews and signs it from the [web app](https://clanker-wallet.xyz). All communication is end-to-end encrypted.
 
 ## Install
 
 ```bash
-npm install clanker-wallet
+npm install -g clanker-wallet
 ```
 
-## Quickstart
+Or run without installing:
+```bash
+npx clanker-wallet
+bunx clanker-wallet
+```
 
-```typescript
-import { ClankerWallet } from 'clanker-wallet'
+## Quick Start
 
-const wallet = new ClankerWallet({ agentName: 'my-trading-bot' })
+```bash
+# 1. Human goes to https://clanker-wallet.xyz, connects wallet, copies pairing JSON
+# 2. Pair (one-time)
+clanker-wallet pair '{"version":1,"pubkey":"ab12...","relay":"wss://...","wallet":"0x..."}'
 
-// Pair with human's web app (scan QR code to get pairing JSON)
-wallet.pair(pairingJson)
+# 3. Send a transaction (blocks until human approves or rejects)
+clanker-wallet tx --chain 1 --to 0xRecipient --value 1000000000000000000 --reason "swap ETH for USDC"
 
-// Request a transaction — blocks until human approves or rejects
-const txHash = await wallet.requestTx({
-  chain_id: 1,
-  transaction: { to: '0x...', value: '1000000000000000000', data: '0x' },
-  context: { reason: 'Buy tokens', urgency: 'medium' },
-})
+# 4. Check status anytime
+clanker-wallet status
+```
+
+## Commands
 
-console.log('tx hash:', txHash)
+### `pair`
+
+Pair with a human's web app. Run once — identity and pairing are saved to `~/.clanker-wallet/`.
+
+```bash
+clanker-wallet pair '<pairing JSON from web app>'
+# → {"agent_id":"agent_abc123","status":"paired","wallet":"0x...","relay":"wss://..."}
 ```
 
-## How It Works
+### `tx`
 
-- **E2E encrypted** — agent and human derive an X25519 shared secret. The relay only sees ciphertext.
-- **Relay transport** — lightweight WebSocket relay forwards encrypted messages between agent and human. No private keys touch the server.
-- **Human approval** — the human reviews transaction details in the Clanker Wallet web app and signs with their own wallet (MetaMask, WalletConnect, etc).
+Send a transaction request. Blocks until the human approves or rejects.
 
-## API
+```bash
+clanker-wallet tx \
+  --chain 1 \
+  --to 0xRecipient \
+  --value 1000000000000000000 \
+  --data 0x \
+  --reason "swap ETH for USDC" \
+  --urgency medium \
+  --timeout 120000
+# approved → {"tx_hash":"0x...","status":"approved"}
+# rejected → {"status":"rejected","error":"..."} (exit code 1)
+# timeout  → {"status":"timeout","error":"..."}  (exit code 2)
+```
 
-### `new ClankerWallet(options?)`
+**Flags:**
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--chain <id>` | yes | — | Chain ID (1=Ethereum, 137=Polygon, 8453=Base) |
+| `--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 |
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `agentName` | `string` | Display name shown to human (optional) |
-| `secretKey` | `Uint8Array` | 32-byte secret key to restore identity. Omit to generate new keypair. |
+### `status`
 
-### Properties
+Check current pairing status.
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `publicKey` | `Uint8Array` | Agent's X25519 public key |
-| `secretKey` | `Uint8Array` | Agent's X25519 secret key (save this to persist identity) |
-| `agentId` | `string` | Derived agent identifier (`agent_<pubkey_prefix>`) |
-| `paired` | `boolean` | Whether `pair()` has been called |
+```bash
+clanker-wallet status
+# → {"agent_id":"agent_abc123","paired":true,"wallet":"0x...","relay":"wss://..."}
+```
+
+### `whoami`
 
-### `wallet.pair(qrData: string): PairingData`
+Show agent identity.
 
-Parse pairing JSON (from the web app's QR code) and store the human's public key and relay URL. Returns the parsed `PairingData`.
+```bash
+clanker-wallet whoami
+# → {"agent_id":"agent_abc123","public_key":"ab12cd..."}
+```
 
-### `wallet.requestTx(options): Promise<string>`
+## Exit Codes
 
-Send a transaction request and wait for human response. Resolves with the transaction hash on approval. Throws on rejection, timeout, or connection error.
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Rejected by human |
+| 2 | Timeout |
+| 3 | Connection/relay error |
+| 4 | Not paired |
+| 5 | Invalid arguments |
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `chain_id` | `number` | Target chain (1 = mainnet, 137 = polygon, etc) |
-| `transaction` | `{ to, value, data }` | Transaction parameters (`value` in wei) |
-| `context` | `{ reason?, urgency?, expected_outcome? }` | Optional context shown to human |
-| `timeout_ms` | `number` | Timeout in ms (default: 1 hour) |
+## State
 
-## Persisting Agent Identity
+Identity and pairing are persisted in `~/.clanker-wallet/`:
 
-Save `wallet.secretKey` between sessions to keep the same agent identity:
+```
+~/.clanker-wallet/
+  identity.json    # agent keypair (auto-generated on first use)
+  pairing.json     # human's public key + relay URL
+```
+
+## Common Chain IDs
+
+| Chain | ID |
+|-------|----|
+| Ethereum | 1 |
+| Polygon | 137 |
+| Arbitrum | 42161 |
+| Base | 8453 |
+| Optimism | 10 |
+| Sepolia (testnet) | 11155111 |
+
+---
+
+## Library Usage (Advanced)
+
+The CLI wraps a TypeScript library. For programmatic use:
+
+```bash
+npm install clanker-wallet
+```
 
 ```typescript
-import { writeFileSync, readFileSync, existsSync } from 'fs'
+import { ClankerWallet } from 'clanker-wallet'
+
+const wallet = new ClankerWallet({ agentName: 'my-bot' })
+wallet.pair(pairingJson)
+
+const txHash = await wallet.requestTx({
+  chain_id: 1,
+  transaction: { to: '0x...', value: '1000000000000000000', data: '0x' },
+  context: { reason: 'Buy tokens', urgency: 'medium' },
+})
+```
 
-// Restore or create
-const secretKey = existsSync('.agent-key')
-  ? new Uint8Array(readFileSync('.agent-key'))
-  : undefined
+See full API: [`src/`](./src/)
 
-const wallet = new ClankerWallet({ secretKey })
+## Python SDK
 
-// Save for next time
-if (!secretKey) writeFileSync('.agent-key', wallet.secretKey)
+```bash
+pip install clanker-wallet
 ```
 
-## Web App
+```python
+from clanker_wallet import ClankerWallet, Transaction, RequestTxOptions, TxContext
+
+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"),
+))
+```
+
+## 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
+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
+5. Human approves → wallet signs + broadcasts → agent gets the tx hash
 
-The human-facing web app is at [clanker-wallet.vercel.app](https://clanker-wallet.vercel.app). Connect a wallet, scan the QR code from your agent, and approve transactions.
+All messages are encrypted end-to-end. The relay server never sees plaintext.
 
 ## License
 

package/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: clanker-wallet
+description: "Send blockchain transactions through a human-approved wallet. You propose tx, human reviews and signs. No private keys needed."
+homepage: https://clanker-wallet.xyz
+---
+
+# Clanker Wallet — Human-Approved Transactions
+
+You are an AI agent that needs to send blockchain transactions. You do NOT have a private key. Instead, you propose transactions and a human approves them from their own wallet.
+
+## Setup
+
+```bash
+npm install -g clanker-wallet
+```
+
+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:
+
+> "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..."}
+```
+
+Pair with it:
+```bash
+clanker-wallet pair '{"version":1,"pubkey":"ab12...","relay":"wss://...","wallet":"0x..."}'
+```
+
+This saves identity and pairing to `~/.clanker-wallet/`. You only need to do this once.
+
+### Transaction notifications
+
+After pairing, ask the human:
+
+> "Would you like me to notify you here when I need a transaction approved? I'll send you a message with a direct link to approve it."
+
+If they agree, **every time you send a `tx` command**, immediately send a message through your current communication channel with:
+
+1. A short description of what the tx does (from the `--reason`)
+2. A direct link to the web app: **https://clanker-wallet.xyz**
+3. The urgency level
+
+Example notification:
+> Transaction awaiting your approval
+> I'm requesting to send 0.001 ETH on Sepolia to a test address.
+> Urgency: normal
+> [Approve or reject here](https://clanker-wallet.xyz)
+
+## Sending a Transaction
+
+```bash
+clanker-wallet tx \
+  --chain 1 \
+  --to 0xRecipientAddress \
+  --value 1000000000000000 \
+  --reason "Send 0.001 ETH to recipient" \
+  --urgency medium \
+  --timeout 120000
+```
+
+The command **blocks until the human approves or rejects**. 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)
+
+## 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.
+- **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) |
+| `--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 |
+
+## Common Chain IDs
+
+| Chain | ID |
+|-------|----|
+| Ethereum | 1 |
+| Polygon | 137 |
+| Arbitrum | 42161 |
+| Base | 8453 |
+| Optimism | 10 |
+| Sepolia (testnet) | 11155111 |
+
+## Common Patterns
+
+### Simple ETH transfer
+```bash
+clanker-wallet tx --chain 1 --to 0xRecipientAddress --value 1000000000000000 --reason "Send 0.001 ETH"
+```
+
+### ERC-20 token transfer
+```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"
+```
+
+### 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"
+```
+
+## Other Commands
+
+```bash
+# Check pairing status
+clanker-wallet status
+# → {"agent_id":"agent_abc123","paired":true,"wallet":"0x...","relay":"wss://..."}
+
+# Show agent identity
+clanker-wallet whoami
+# → {"agent_id":"agent_abc123","public_key":"ab12cd..."}
+```
+
+## Troubleshooting
+
+- **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

package/bin/cli.js

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+import { ClankerWallet } from '../dist/index.js'
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+
+// ── constants ────────────────────────────────────────────────────────
+const STATE_DIR = join(homedir(), '.clanker-wallet')
+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 }
+
+// ── 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)))
+
+function die(msg, code) {
+  process.stderr.write(msg + '\n')
+  process.exit(code)
+}
+
+function out(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n')
+}
+
+function ensureDir() {
+  if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true })
+}
+
+function loadIdentity() {
+  if (!existsSync(IDENTITY_FILE)) return null
+  try { return JSON.parse(readFileSync(IDENTITY_FILE, 'utf8')) }
+  catch { return null }
+}
+
+function saveIdentity(data) {
+  ensureDir()
+  writeFileSync(IDENTITY_FILE, JSON.stringify(data, null, 2) + '\n')
+}
+
+function loadPairing() {
+  if (!existsSync(PAIRING_FILE)) return null
+  try { return JSON.parse(readFileSync(PAIRING_FILE, 'utf8')) }
+  catch { return null }
+}
+
+function savePairing(data) {
+  ensureDir()
+  writeFileSync(PAIRING_FILE, JSON.stringify(data, null, 2) + '\n')
+}
+
+/** restore or create a ClankerWallet with persisted identity */
+function getWallet() {
+  const identity = loadIdentity()
+  const secretKey = identity ? fromHexStr(identity.secret_key) : undefined
+  const wallet = new ClankerWallet({ secretKey })
+  if (!identity) {
+    saveIdentity({ secret_key: hex(wallet.secretKey), agent_id: wallet.agentId })
+  }
+  return wallet
+}
+
+// ── arg parsing ──────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const args = argv.slice(2)
+  const cmd = args[0]
+  const positional = []
+  const flags = {}
+
+  for (let i = 1; i < args.length; i++) {
+    const a = args[i]
+    if (a.startsWith('--')) {
+      const key = a.slice(2)
+      const next = args[i + 1]
+      if (next && !next.startsWith('--')) {
+        flags[key] = next
+        i++
+      } else {
+        flags[key] = true
+      }
+    } else {
+      positional.push(a)
+    }
+  }
+
+  return { cmd, positional, flags }
+}
+
+// ── commands ─────────────────────────────────────────────────────────
+function cmdPair(positional) {
+  const jsonStr = positional[0]
+  if (!jsonStr) {
+    die('usage: clanker-wallet pair \'<pairing JSON from web app>\'', EXIT.BAD_ARGS)
+  }
+
+  const wallet = getWallet()
+
+  let pairingData
+  try {
+    pairingData = wallet.pair(jsonStr)
+  } catch (err) {
+    die(`pair failed: ${err.message}`, EXIT.BAD_ARGS)
+  }
+
+  savePairing({
+    pubkey: pairingData.pubkey,
+    relay: pairingData.relay,
+    wallet: pairingData.wallet || null,
+    mode: pairingData.mode || null,
+  })
+
+  out({
+    agent_id: wallet.agentId,
+    status: 'paired',
+    wallet: pairingData.wallet || null,
+    relay: pairingData.relay,
+  })
+}
+
+async function cmdTx(flags) {
+  const pairing = loadPairing()
+  if (!pairing) die('not paired — run: clanker-wallet pair \'<JSON>\'', EXIT.NOT_PAIRED)
+
+  const chain = flags.chain
+  const to = flags.to
+  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)
+
+  const value = flags.value || '0'
+  const data = flags.data || '0x'
+  const timeout = flags.timeout ? parseInt(flags.timeout, 10) : 3_600_000
+
+  const context = {}
+  if (flags.reason) context.reason = flags.reason
+  if (flags.urgency) context.urgency = flags.urgency
+  if (flags['expected-outcome']) context.expected_outcome = flags['expected-outcome']
+
+  const wallet = getWallet()
+  const pairingJson = JSON.stringify({
+    version: 1,
+    pubkey: pairing.pubkey,
+    relay: pairing.relay,
+    wallet: pairing.wallet,
+  })
+  wallet.pair(pairingJson)
+
+  try {
+    const txHash = await wallet.requestTx({
+      chain_id: chainId,
+      transaction: { to, value, data },
+      context: Object.keys(context).length > 0 ? context : undefined,
+      timeout_ms: timeout,
+    })
+    out({ tx_hash: txHash, status: 'approved' })
+    process.exit(EXIT.OK)
+  } catch (err) {
+    const msg = err.message || String(err)
+    if (msg.includes('rejected')) {
+      out({ status: 'rejected', error: msg })
+      process.exit(EXIT.REJECTED)
+    } else if (msg.includes('timed out')) {
+      out({ status: 'timeout', error: msg })
+      process.exit(EXIT.TIMEOUT)
+    } else {
+      out({ status: 'error', error: msg })
+      process.exit(EXIT.CONNECTION)
+    }
+  }
+}
+
+function cmdStatus() {
+  const identity = loadIdentity()
+  const pairing = loadPairing()
+
+  out({
+    agent_id: identity?.agent_id || null,
+    paired: !!pairing,
+    wallet: pairing?.wallet || null,
+    relay: pairing?.relay || null,
+  })
+}
+
+function cmdWhoami() {
+  const wallet = getWallet()
+  out({
+    agent_id: wallet.agentId,
+    public_key: hex(wallet.publicKey),
+  })
+}
+
+function showHelp() {
+  process.stderr.write(`clanker-wallet — human-approved transactions for AI agents
+
+commands:
+  pair '<JSON>'   pair with human's web app (one-time setup)
+  tx              send a transaction (blocks until approved/rejected)
+  status          check pairing status
+  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)
+
+exit codes:
+  0  success
+  1  rejected by human
+  2  timeout
+  3  connection error
+  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 status
+  clanker-wallet whoami
+
+docs: https://github.com/almogdepaz/clanker-wallet
+web:  https://clanker-wallet.xyz
+`)
+}
+
+// ── main ─────────────────────────────────────────────────────────────
+const { cmd, positional, flags } = parseArgs(process.argv)
+
+switch (cmd) {
+  case 'pair':
+    cmdPair(positional)
+    break
+  case 'tx':
+    await cmdTx(flags)
+    break
+  case 'status':
+    cmdStatus()
+    break
+  case 'whoami':
+    cmdWhoami()
+    break
+  case 'help':
+  case '--help':
+  case '-h':
+    showHelp()
+    break
+  default:
+    showHelp()
+    break
+}

package/dist/client.d.ts

@@ -13,11 +13,9 @@ export declare class ClankerWallet extends TypedEmitter {
     /** Ed25519 public key for signing TxRequests */
     readonly signingPublicKey: Uint8Array;
     private readonly signingSecretKey;
-    private humanPubkey;
-    private humanPubkeyHex;
-    private relayUrl;
-    private humanWallet;
-    private mode;
+    private readonly agentPubkeyHex;
+    private readonly signingPubkeyHex;
+    private pairing;
     constructor(options?: ClankerWalletOptions);
     /** whether this agent has been paired with a human */
     get paired(): boolean;

package/dist/client.js

@@ -1,4 +1,4 @@
-import { encryptMessage, decryptMessage, toHex, fromHex, generateKeypair, keypairFromSecret, signingKeypairFromSeed, signMessage } from './crypto.js';
+import { decryptMessage, encryptMessage, fromHex, generateKeypair, keypairFromSecret, signMessage, signingKeypairFromSeed, toHex } from './crypto.js';
 import { TypedEmitter } from './events.js';
 const DEFAULT_TIMEOUT_MS = 3_600_000; // 1 hour
 export class ClankerWallet extends TypedEmitter {
@@ -8,11 +8,9 @@ export class ClankerWallet extends TypedEmitter {
     /** Ed25519 public key for signing TxRequests */
     signingPublicKey;
     signingSecretKey;
-    humanPubkey = null;
-    humanPubkeyHex = null;
-    relayUrl = null;
-    humanWallet = null;
-    mode = 'encrypted';
+    agentPubkeyHex;
+    signingPubkeyHex;
+    pairing = null;
     constructor(options = {}) {
         super();
         const kp = options.secretKey
@@ -21,14 +19,15 @@ export class ClankerWallet extends TypedEmitter {
         this.publicKey = kp.publicKey;
         this.secretKey = kp.secretKey;
         this.agentId = `agent_${toHex(kp.publicKey).slice(0, 12)}`;
-        // derive Ed25519 signing keypair from the x25519 secret key (first 32 bytes = seed)
+        this.agentPubkeyHex = toHex(kp.publicKey);
         const signingKp = signingKeypairFromSeed(kp.secretKey);
         this.signingPublicKey = signingKp.publicKey;
         this.signingSecretKey = signingKp.secretKey;
+        this.signingPubkeyHex = toHex(signingKp.publicKey);
     }
     /** whether this agent has been paired with a human */
     get paired() {
-        return this.humanPubkey !== null;
+        return this.pairing !== null;
     }
     /** parse QR/pairing data and store the human's pubkey + relay url */
     pair(qrData) {
@@ -39,11 +38,12 @@ export class ClankerWallet extends TypedEmitter {
         if (!data.pubkey || !data.relay) {
             throw new Error('invalid pairing data: missing pubkey or relay');
         }
-        this.humanPubkey = fromHex(data.pubkey);
-        this.humanPubkeyHex = data.pubkey;
-        this.relayUrl = data.relay;
-        this.humanWallet = data.wallet || null;
-        this.mode = data.mode || 'encrypted';
+        this.pairing = {
+            humanPubkey: fromHex(data.pubkey),
+            humanPubkeyHex: data.pubkey,
+            relayUrl: data.relay,
+            humanWallet: data.wallet || null,
+        };
         this.emit('paired', { relay: data.relay, wallet: data.wallet || '' });
         return data;
     }
@@ -53,9 +53,10 @@ export class ClankerWallet extends TypedEmitter {
      * throws on rejection, timeout, or connection error.
      */
     async requestTx(options) {
-        if (!this.humanPubkey || !this.humanPubkeyHex || !this.relayUrl) {
+        if (!this.pairing) {
             throw new Error('not paired — call pair() first');
         }
+        const { humanPubkey, humanPubkeyHex, relayUrl } = this.pairing;
         const timeoutMs = options.timeout_ms ?? DEFAULT_TIMEOUT_MS;
         const requestId = `req_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
         const txRequest = {
@@ -67,17 +68,7 @@ export class ClankerWallet extends TypedEmitter {
             context: options.context,
             signature: '', // set below after signing
         };
-        // sign the request (signature field empty during signing, then filled)
-        const sigPayload = JSON.stringify(txRequest);
-        txRequest.signature = signMessage(sigPayload, this.signingSecretKey);
-        const humanPubkey = this.humanPubkey;
-        const humanPubkeyHex = this.humanPubkeyHex;
-        const relayUrl = this.relayUrl;
-        const secretKey = this.secretKey;
-        const agentPubkeyHex = toHex(this.publicKey);
-        const signingPubkeyHex = toHex(this.signingPublicKey);
-        const mode = this.mode;
-        const humanWallet = this.humanWallet;
+        txRequest.signature = signMessage(JSON.stringify(txRequest), this.signingSecretKey);
         return new Promise((resolve, reject) => {
             let ws;
             let timer;
@@ -89,11 +80,14 @@ export class ClankerWallet extends TypedEmitter {
                     ws.close();
                 }
             };
+            const fail = (message) => {
+                cleanup();
+                this.emit('error', { message });
+                reject(new Error(message));
+            };
             timer = setTimeout(() => {
                 if (!settled) {
-                    cleanup();
-                    this.emit('error', { message: `request ${requestId} timed out after ${timeoutMs}ms` });
-                    reject(new Error(`request ${requestId} timed out after ${timeoutMs}ms`));
+                    fail(`request ${requestId} timed out after ${timeoutMs}ms`);
                 }
             }, timeoutMs);
             this.emit('connecting', { relay: relayUrl });
@@ -101,17 +95,12 @@ export class ClankerWallet extends TypedEmitter {
                 ws = new WebSocket(relayUrl);
             }
             catch (err) {
-                cleanup();
-                this.emit('error', { message: `failed to connect to relay: ${err}` });
-                reject(new Error(`failed to connect to relay: ${err}`));
+                fail(`failed to connect to relay: ${err}`);
                 return;
             }
             ws.addEventListener('error', () => {
-                if (!settled) {
-                    cleanup();
-                    this.emit('error', { message: 'relay connection error' });
-                    reject(new Error('relay connection error'));
-                }
+                if (!settled)
+                    fail('relay connection error');
             });
             ws.addEventListener('close', () => {
                 this.emit('disconnected', {});
@@ -121,7 +110,6 @@ export class ClankerWallet extends TypedEmitter {
                 }
             });
             ws.addEventListener('open', () => {
-                // join the human's room
                 ws.send(JSON.stringify({ type: 'join', room: humanPubkeyHex }));
             });
             ws.addEventListener('message', (event) => {
@@ -132,46 +120,33 @@ export class ClankerWallet extends TypedEmitter {
                     msg = JSON.parse(event.data);
                 }
                 catch {
-                    return; // ignore non-JSON
+                    return;
                 }
                 if (msg.type === 'joined') {
                     this.emit('connected', { room: humanPubkeyHex });
-                    // room joined — send the encrypted tx request
-                    const plaintext = JSON.stringify(txRequest);
-                    const ciphertext = encryptMessage(plaintext, humanPubkey, secretKey);
+                    const ciphertext = encryptMessage(JSON.stringify(txRequest), humanPubkey, this.secretKey);
                     const envelope = {
-                        sender_pubkey: agentPubkeyHex,
+                        sender_pubkey: this.agentPubkeyHex,
                         ciphertext,
-                        signing_pubkey: signingPubkeyHex,
+                        signing_pubkey: this.signingPubkeyHex,
                     };
-                    const wsMsg = {
+                    ws.send(JSON.stringify({
                         type: 'message',
                         room: humanPubkeyHex,
                         payload: JSON.stringify(envelope),
-                    };
-                    if (mode === 'managed') {
-                        wsMsg.simulate = {
-                            from: humanWallet || '',
-                            to: options.transaction.to,
-                            value: options.transaction.value,
-                            data: options.transaction.data,
-                            chainId: options.chain_id,
-                        };
-                    }
-                    ws.send(JSON.stringify(wsMsg));
+                    }));
                     this.emit('request_sent', { request_id: requestId });
                     return;
                 }
                 if (msg.type === 'message') {
-                    // try to decrypt as TxResponse
                     try {
                         const envelope = JSON.parse(msg.payload);
-                        const plaintext = decryptMessage(envelope.ciphertext, fromHex(envelope.sender_pubkey), secretKey);
+                        const plaintext = decryptMessage(envelope.ciphertext, fromHex(envelope.sender_pubkey), this.secretKey);
                         if (!plaintext)
-                            return; // not for us or decryption failed
+                            return;
                         const response = JSON.parse(plaintext);
                         if (response.request_id !== requestId)
-                            return; // not our response
+                            return;
                         this.emit('response', {
                             request_id: response.request_id,
                             status: response.status,
@@ -194,11 +169,10 @@ export class ClankerWallet extends TypedEmitter {
                     catch {
                         // ignore messages that aren't valid envelopes
                     }
+                    return;
                 }
                 if (msg.type === 'error') {
-                    cleanup();
-                    this.emit('error', { message: `relay error: ${msg.message}` });
-                    reject(new Error(`relay error: ${msg.message}`));
+                    fail(`relay error: ${msg.message}`);
                 }
             });
         });

package/dist/crypto.d.ts

@@ -17,4 +17,7 @@ export declare function signingKeypairFromSeed(seed: Uint8Array): nacl.SignKeyPa
 export declare function signMessage(message: string, signingSecretKey: Uint8Array): string;
 /** verify a detached Ed25519 signature. signature is base64-encoded. */
 export declare function verifySignature(message: string, base64Signature: string, signingPublicKey: Uint8Array): boolean;
+/** base64 string → Uint8Array */
+export declare function base64ToBytes(b64: string): Uint8Array;
+/** Uint8Array → base64 string */
 export declare function bytesToBase64(bytes: Uint8Array): string;

package/dist/crypto.js

@@ -1,4 +1,6 @@
 import nacl from 'tweetnacl';
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
 /** generate a random x25519 keypair for the agent's identity */
 export function generateKeypair() {
     return nacl.box.keyPair();
@@ -10,8 +12,7 @@ export function keypairFromSecret(secretKey) {
 /** encrypt a message using nacl.box. returns base64(nonce + ciphertext). */
 export function encryptMessage(message, recipientPublicKey, senderSecretKey) {
     const nonce = nacl.randomBytes(nacl.box.nonceLength);
-    const encoded = new TextEncoder().encode(message);
-    const ciphertext = nacl.box(encoded, nonce, recipientPublicKey, senderSecretKey);
+    const ciphertext = nacl.box(encoder.encode(message), nonce, recipientPublicKey, senderSecretKey);
     const combined = new Uint8Array(nonce.length + ciphertext.length);
     combined.set(nonce);
     combined.set(ciphertext, nonce.length);
@@ -27,7 +28,7 @@ export function decryptMessage(base64Payload, senderPublicKey, recipientSecretKe
     const plaintext = nacl.box.open(ciphertext, nonce, senderPublicKey, recipientSecretKey);
     if (!plaintext)
         return null;
-    return new TextDecoder().decode(plaintext);
+    return decoder.decode(plaintext);
 }
 /** hex-encode bytes (no 0x prefix) */
 export function toHex(bytes) {
@@ -50,17 +51,16 @@ export function signingKeypairFromSeed(seed) {
 }
 /** sign a message string with an Ed25519 secret key. returns base64(signature). */
 export function signMessage(message, signingSecretKey) {
-    const encoded = new TextEncoder().encode(message);
-    const signature = nacl.sign.detached(encoded, signingSecretKey);
+    const signature = nacl.sign.detached(encoder.encode(message), signingSecretKey);
     return bytesToBase64(signature);
 }
 /** verify a detached Ed25519 signature. signature is base64-encoded. */
 export function verifySignature(message, base64Signature, signingPublicKey) {
-    const encoded = new TextEncoder().encode(message);
     const signature = base64ToBytes(base64Signature);
-    return nacl.sign.detached.verify(encoded, signature, signingPublicKey);
+    return nacl.sign.detached.verify(encoder.encode(message), signature, signingPublicKey);
 }
-function base64ToBytes(b64) {
+/** base64 string → Uint8Array */
+export function base64ToBytes(b64) {
     const binary = atob(b64);
     const bytes = new Uint8Array(binary.length);
     for (let i = 0; i < binary.length; i++) {
@@ -68,6 +68,7 @@ function base64ToBytes(b64) {
     }
     return bytes;
 }
+/** Uint8Array → base64 string */
 export function bytesToBase64(bytes) {
     let binary = '';
     for (let i = 0; i < bytes.length; i++) {

package/dist/events.js

@@ -1,12 +1,13 @@
 export class TypedEmitter {
     _listeners = new Map();
     on(event, handler) {
-        let set = this._listeners.get(event);
-        if (!set) {
-            set = new Set();
-            this._listeners.set(event, set);
+        const existing = this._listeners.get(event);
+        if (existing) {
+            existing.add(handler);
+        }
+        else {
+            this._listeners.set(event, new Set([handler]));
         }
-        set.add(handler);
         return this;
     }
     off(event, handler) {

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { ClankerWallet } from './client.js';
 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 { generateKeypair, keypairFromSecret, encryptMessage, decryptMessage, toHex, fromHex, signingKeypairFromSeed, signMessage, verifySignature, bytesToBase64 } from './crypto.js';
-export type { Transaction, TxContext, TxRequest, TxResponse, AgentEnvelope, PairingData, RequestTxOptions, } from './types.js';
+export type { AgentEnvelope, PairingData, RequestTxOptions, Transaction, TxContext, TxRequest, TxResponse, } from './types.js';

package/dist/index.js

@@ -1,3 +1,3 @@
 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 { generateKeypair, keypairFromSecret, encryptMessage, decryptMessage, toHex, fromHex, signingKeypairFromSeed, signMessage, verifySignature, bytesToBase64 } from './crypto.js';

package/dist/types.d.ts

@@ -40,8 +40,6 @@ export interface PairingData {
     pubkey: string;
     relay: string;
     wallet: string;
-    /** 'managed' = relay simulates server-side; 'encrypted' = user provides own keys */
-    mode?: 'encrypted' | 'managed';
 }
 /** options for requestTx */
 export interface RequestTxOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clanker-wallet",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,7 +10,10 @@
       "types": "./dist/index.d.ts"
     }
   },
-  "files": ["dist", "README.md", "LICENSE"],
+  "bin": {
+    "clanker-wallet": "bin/cli.js"
+  },
+  "files": ["dist", "bin", "SKILL.md", "README.md", "LICENSE"],
   "license": "MIT",
   "author": "Clanker Wallet Contributors",
   "repository": {
@@ -31,9 +34,7 @@
   },
   "devDependencies": {
     "@types/bun": "^1.3.8",
-    "@types/ws": "^8.18.1",
     "typescript": "^5.4.0",
-    "vitest": "^2.1.0",
-    "ws": "^8.19.0"
+    "vitest": "^2.1.0"
   }
 }