clanker-wallet 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clanker Wallet Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# @clanker-wallet/sdk
+
+TypeScript SDK for AI agents to request human-approved Ethereum transactions over an E2E encrypted relay.
+
+## Install
+
+```bash
+npm install @clanker-wallet/sdk
+```
+
+## Quickstart
+
+```typescript
+import { ClankerWallet } from '@clanker-wallet/sdk'
+
+const wallet = new ClankerWallet({ agentName: 'my-trading-bot' })
+
+// Pair with human's web app (scan QR code to get pairing JSON)
+wallet.pair(pairingJson)
+
+// 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' },
+})
+
+console.log('tx hash:', txHash)
+```
+
+## How It Works
+
+- **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).
+
+## API
+
+### `new ClankerWallet(options?)`
+
+| 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. |
+
+### Properties
+
+| 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 |
+
+### `wallet.pair(qrData: string): PairingData`
+
+Parse pairing JSON (from the web app's QR code) and store the human's public key and relay URL. Returns the parsed `PairingData`.
+
+### `wallet.requestTx(options): Promise<string>`
+
+Send a transaction request and wait for human response. Resolves with the transaction hash on approval. Throws on rejection, timeout, or connection error.
+
+| 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) |
+
+## Persisting Agent Identity
+
+Save `wallet.secretKey` between sessions to keep the same agent identity:
+
+```typescript
+import { writeFileSync, readFileSync, existsSync } from 'fs'
+
+// Restore or create
+const secretKey = existsSync('.agent-key')
+  ? new Uint8Array(readFileSync('.agent-key'))
+  : undefined
+
+const wallet = new ClankerWallet({ secretKey })
+
+// Save for next time
+if (!secretKey) writeFileSync('.agent-key', wallet.secretKey)
+```
+
+## Web App
+
+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.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,31 @@
+import { TypedEmitter } from './events.js';
+import type { PairingData, RequestTxOptions } from './types.js';
+export interface ClankerWalletOptions {
+    /** agent display name (informational) */
+    agentName?: string;
+    /** 32-byte secret key to restore identity. if omitted, generates a new keypair. */
+    secretKey?: Uint8Array;
+}
+export declare class ClankerWallet extends TypedEmitter {
+    readonly publicKey: Uint8Array;
+    readonly secretKey: Uint8Array;
+    readonly agentId: string;
+    /** Ed25519 public key for signing TxRequests */
+    readonly signingPublicKey: Uint8Array;
+    private readonly signingSecretKey;
+    private humanPubkey;
+    private humanPubkeyHex;
+    private relayUrl;
+    private humanWallet;
+    constructor(options?: ClankerWalletOptions);
+    /** whether this agent has been paired with a human */
+    get paired(): boolean;
+    /** parse QR/pairing data and store the human's pubkey + relay url */
+    pair(qrData: string): PairingData;
+    /**
+     * send a transaction request to the paired human and wait for their response.
+     * resolves with tx hash on approval.
+     * throws on rejection, timeout, or connection error.
+     */
+    requestTx(options: RequestTxOptions): Promise<string>;
+}

package/dist/client.js

@@ -0,0 +1,192 @@
+import { encryptMessage, decryptMessage, toHex, fromHex, generateKeypair, keypairFromSecret, signingKeypairFromSeed, signMessage } from './crypto.js';
+import { TypedEmitter } from './events.js';
+const DEFAULT_TIMEOUT_MS = 3_600_000; // 1 hour
+export class ClankerWallet extends TypedEmitter {
+    publicKey;
+    secretKey;
+    agentId;
+    /** Ed25519 public key for signing TxRequests */
+    signingPublicKey;
+    signingSecretKey;
+    humanPubkey = null;
+    humanPubkeyHex = null;
+    relayUrl = null;
+    humanWallet = null;
+    constructor(options = {}) {
+        super();
+        const kp = options.secretKey
+            ? keypairFromSecret(options.secretKey)
+            : generateKeypair();
+        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)
+        const signingKp = signingKeypairFromSeed(kp.secretKey);
+        this.signingPublicKey = signingKp.publicKey;
+        this.signingSecretKey = signingKp.secretKey;
+    }
+    /** whether this agent has been paired with a human */
+    get paired() {
+        return this.humanPubkey !== null;
+    }
+    /** parse QR/pairing data and store the human's pubkey + relay url */
+    pair(qrData) {
+        const data = JSON.parse(qrData);
+        if (data.version !== 1) {
+            throw new Error(`unsupported pairing version: ${data.version}`);
+        }
+        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.emit('paired', { relay: data.relay, wallet: data.wallet || '' });
+        return data;
+    }
+    /**
+     * send a transaction request to the paired human and wait for their response.
+     * resolves with tx hash on approval.
+     * throws on rejection, timeout, or connection error.
+     */
+    async requestTx(options) {
+        if (!this.humanPubkey || !this.humanPubkeyHex || !this.relayUrl) {
+            throw new Error('not paired — call pair() first');
+        }
+        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,
+            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);
+        return new Promise((resolve, reject) => {
+            let ws;
+            let timer;
+            let settled = false;
+            const cleanup = () => {
+                settled = true;
+                clearTimeout(timer);
+                if (ws && ws.readyState <= WebSocket.OPEN) {
+                    ws.close();
+                }
+            };
+            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`));
+                }
+            }, timeoutMs);
+            this.emit('connecting', { relay: relayUrl });
+            try {
+                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}`));
+                return;
+            }
+            ws.addEventListener('error', () => {
+                if (!settled) {
+                    cleanup();
+                    this.emit('error', { message: 'relay connection error' });
+                    reject(new Error('relay connection error'));
+                }
+            });
+            ws.addEventListener('close', () => {
+                this.emit('disconnected', {});
+                if (!settled) {
+                    cleanup();
+                    reject(new Error('relay connection closed unexpectedly'));
+                }
+            });
+            ws.addEventListener('open', () => {
+                // join the human's room
+                ws.send(JSON.stringify({ type: 'join', room: humanPubkeyHex }));
+            });
+            ws.addEventListener('message', (event) => {
+                if (settled)
+                    return;
+                let msg;
+                try {
+                    msg = JSON.parse(event.data);
+                }
+                catch {
+                    return; // ignore non-JSON
+                }
+                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 envelope = {
+                        sender_pubkey: agentPubkeyHex,
+                        ciphertext,
+                        signing_pubkey: signingPubkeyHex,
+                    };
+                    ws.send(JSON.stringify({
+                        type: 'message',
+                        room: humanPubkeyHex,
+                        payload: JSON.stringify(envelope),
+                    }));
+                    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);
+                        if (!plaintext)
+                            return; // not for us or decryption failed
+                        const response = JSON.parse(plaintext);
+                        if (response.request_id !== requestId)
+                            return; // not our response
+                        this.emit('response', {
+                            request_id: response.request_id,
+                            status: response.status,
+                            tx_hash: response.tx_hash,
+                        });
+                        cleanup();
+                        if (response.status === 'approved' && response.tx_hash) {
+                            resolve(response.tx_hash);
+                        }
+                        else if (response.status === 'rejected') {
+                            reject(new Error(`request ${requestId} rejected by human`));
+                        }
+                        else if (response.error) {
+                            reject(new Error(`request ${requestId} failed: ${response.error}`));
+                        }
+                        else {
+                            reject(new Error(`request ${requestId}: unexpected response status "${response.status}"`));
+                        }
+                    }
+                    catch {
+                        // ignore messages that aren't valid envelopes
+                    }
+                }
+                if (msg.type === 'error') {
+                    cleanup();
+                    this.emit('error', { message: `relay error: ${msg.message}` });
+                    reject(new Error(`relay error: ${msg.message}`));
+                }
+            });
+        });
+    }
+}

package/dist/crypto.d.ts

@@ -0,0 +1,20 @@
+import nacl from 'tweetnacl';
+/** generate a random x25519 keypair for the agent's identity */
+export declare function generateKeypair(): nacl.BoxKeyPair;
+/** restore keypair from a 32-byte secret key */
+export declare function keypairFromSecret(secretKey: Uint8Array): nacl.BoxKeyPair;
+/** encrypt a message using nacl.box. returns base64(nonce + ciphertext). */
+export declare function encryptMessage(message: string, recipientPublicKey: Uint8Array, senderSecretKey: Uint8Array): string;
+/** decrypt a nacl.box message. payload = base64(nonce + ciphertext). */
+export declare function decryptMessage(base64Payload: string, senderPublicKey: Uint8Array, recipientSecretKey: Uint8Array): string | null;
+/** hex-encode bytes (no 0x prefix) */
+export declare function toHex(bytes: Uint8Array): string;
+/** hex string → Uint8Array (strips 0x prefix if present) */
+export declare function fromHex(hex: string): Uint8Array;
+/** derive an Ed25519 signing keypair from a 32-byte seed */
+export declare function signingKeypairFromSeed(seed: Uint8Array): nacl.SignKeyPair;
+/** sign a message string with an Ed25519 secret key. returns base64(signature). */
+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;
+export declare function bytesToBase64(bytes: Uint8Array): string;

package/dist/crypto.js

@@ -0,0 +1,77 @@
+import nacl from 'tweetnacl';
+/** generate a random x25519 keypair for the agent's identity */
+export function generateKeypair() {
+    return nacl.box.keyPair();
+}
+/** restore keypair from a 32-byte secret key */
+export function keypairFromSecret(secretKey) {
+    return nacl.box.keyPair.fromSecretKey(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 combined = new Uint8Array(nonce.length + ciphertext.length);
+    combined.set(nonce);
+    combined.set(ciphertext, nonce.length);
+    return bytesToBase64(combined);
+}
+/** decrypt a nacl.box message. payload = base64(nonce + ciphertext). */
+export function decryptMessage(base64Payload, senderPublicKey, recipientSecretKey) {
+    const raw = base64ToBytes(base64Payload);
+    if (raw.length <= nacl.box.nonceLength)
+        return null;
+    const nonce = raw.slice(0, nacl.box.nonceLength);
+    const ciphertext = raw.slice(nacl.box.nonceLength);
+    const plaintext = nacl.box.open(ciphertext, nonce, senderPublicKey, recipientSecretKey);
+    if (!plaintext)
+        return null;
+    return new TextDecoder().decode(plaintext);
+}
+/** hex-encode bytes (no 0x prefix) */
+export function toHex(bytes) {
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+/** hex string → Uint8Array (strips 0x prefix if present) */
+export function fromHex(hex) {
+    const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+    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);
+    }
+    return bytes;
+}
+/** derive an Ed25519 signing keypair from a 32-byte seed */
+export function signingKeypairFromSeed(seed) {
+    return nacl.sign.keyPair.fromSeed(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);
+    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);
+}
+function base64ToBytes(b64) {
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+export function bytesToBase64(bytes) {
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}

package/dist/events.d.ts

@@ -0,0 +1,32 @@
+export type EventMap = {
+    paired: {
+        relay: string;
+        wallet: string;
+    };
+    connecting: {
+        relay: string;
+    };
+    connected: {
+        room: string;
+    };
+    request_sent: {
+        request_id: string;
+    };
+    response: {
+        request_id: string;
+        status: 'approved' | 'rejected';
+        tx_hash?: string;
+    };
+    error: {
+        message: string;
+    };
+    disconnected: {};
+};
+type Handler<T> = (data: T) => void;
+export declare class TypedEmitter {
+    private _listeners;
+    on<K extends keyof EventMap>(event: K, handler: Handler<EventMap[K]>): this;
+    off<K extends keyof EventMap>(event: K, handler: Handler<EventMap[K]>): this;
+    protected emit<K extends keyof EventMap>(event: K, data: EventMap[K]): void;
+}
+export {};

package/dist/events.js

@@ -0,0 +1,19 @@
+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);
+        }
+        set.add(handler);
+        return this;
+    }
+    off(event, handler) {
+        this._listeners.get(event)?.delete(handler);
+        return this;
+    }
+    emit(event, data) {
+        this._listeners.get(event)?.forEach((h) => h(data));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { ClankerWallet } from './client.js';
+export type { ClankerWalletOptions } from './client.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';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { ClankerWallet } from './client.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

@@ -0,0 +1,51 @@
+/** transaction to send */
+export interface Transaction {
+    to: string;
+    value: string;
+    data: string;
+}
+/** optional context about the transaction */
+export interface TxContext {
+    reason?: string;
+    urgency?: string;
+    expected_outcome?: string;
+}
+/** full tx request sent to the human (matches web app TxRequest) */
+export interface TxRequest {
+    request_id: string;
+    agent_id: string;
+    timestamp: string;
+    chain_id: number;
+    transaction: Transaction;
+    context?: TxContext;
+    signature: string;
+}
+/** response from the human (decrypted) */
+export interface TxResponse {
+    request_id: string;
+    status: 'approved' | 'rejected';
+    tx_hash?: string;
+    error?: string;
+}
+/** wire format sent over relay */
+export interface AgentEnvelope {
+    sender_pubkey: string;
+    ciphertext: string;
+    /** Ed25519 public key (hex) for verifying TxRequest signatures */
+    signing_pubkey?: string;
+}
+/** pairing data from QR code */
+export interface PairingData {
+    version: number;
+    pubkey: string;
+    relay: string;
+    wallet: string;
+}
+/** options for requestTx */
+export interface RequestTxOptions {
+    chain_id: number;
+    transaction: Transaction;
+    context?: TxContext;
+    /** timeout in ms (default: 3_600_000 = 1hr) */
+    timeout_ms?: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "clanker-wallet",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "license": "MIT",
+  "author": "Clanker Wallet Contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/almogdepaz/ClankerWallet.git",
+    "directory": "sdk"
+  },
+  "homepage": "https://github.com/almogdepaz/ClankerWallet/tree/main/sdk#readme",
+  "keywords": ["wallet", "ai-agent", "ethereum", "e2e-encrypted", "transaction-approval"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "tweetnacl": "^1.0.3"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.8",
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.0"
+  }
+}