MetaMask · sirtimid · Mar 17, 2026 · Feb 17, 2026 · Feb 17, 2026 · Feb 17, 2026
@@ -150,6 +150,7 @@ jobs:
             '@metamask/kernel-node-runtime',
             '@ocap/extension',
             '@ocap/omnium-gatherum',
+            '@ocap/evm-wallet-experiment',
           ]
         include:
           - package: '@metamask/kernel-node-runtime'
@@ -158,6 +159,8 @@ jobs:
             directory: extension
           - package: '@ocap/omnium-gatherum'
             directory: omnium-gatherum
+          - package: '@ocap/evm-wallet-experiment'
+            directory: evm-wallet-experiment
     steps:
       - name: Checkout and setup environment
         uses: MetaMask/action-checkout-and-setup@v3

@@ -128,7 +128,9 @@
       "@metamask/kernel-cli>@metamask/kernel-node-runtime>@metamask/kernel-store>better-sqlite3": false,
       "@metamask/kernel-cli>@metamask/kernel-node-runtime>@metamask/streams": false,
       "@metamask/kernel-cli>@metamask/kernel-shims>@libp2p/webrtc>@ipshipyard/node-datachannel": false,
-      "@metamask/kernel-cli>@metamask/kernel-utils": false
+      "@metamask/kernel-cli>@metamask/kernel-utils": false,
+      "vitest>jsdom>ws>bufferutil": false,
+      "vitest>jsdom>ws>utf-8-validate": false
     }
   },
   "resolutions": {

@@ -0,0 +1,200 @@
+/**
+ * Daemon communication layer for the OpenClaw wallet plugin.
+ *
+ * Spawns `ocap daemon exec` commands and decodes Endo CapData responses.
+ */
+import { spawn } from 'node:child_process';
+
+type ExecResult = { stdout: string; stderr: string; code: number | null };
+type CapDataLike = { body: string; slots: unknown[] };
+
+export type WalletCallOptions = {
+  cliPath: string;
+  walletKref: string;
+  method: string;
+  args: unknown[];
+  timeoutMs: number;
+};
+
+/**
+ * Bound wallet caller — pre-configured with CLI path, kref, and timeout.
+ */
+export type WalletCaller = (
+  method: string,
+  args: unknown[],
+  timeoutMs?: number,
+) => Promise<unknown>;
+
+/**
+ * Create a bound wallet caller from plugin config.
+ *
+ * @param options - Wallet connection options.
+ * @param options.cliPath - Path to the ocap CLI.
+ * @param options.walletKref - Kernel reference for the wallet coordinator.
+ * @param options.timeoutMs - Default timeout in ms.
+ * @returns A bound caller function.
+ */
+export function makeWalletCaller(options: {
+  cliPath: string;
+  walletKref: string;
+  timeoutMs: number;
+}): WalletCaller {
+  const { cliPath, walletKref, timeoutMs } = options;
+  return async (method, args, overrideTimeout) =>
+    callWallet({
+      cliPath,
+      walletKref,
+      method,
+      args,
+      timeoutMs: overrideTimeout ?? timeoutMs,
+    });
+}
+
+/**
+ * Check if a value looks like Endo CapData.
+ *
+ * @param value - The parsed JSON value.
+ * @returns True when value has CapData shape.
+ */
+function isCapDataLike(value: unknown): value is CapDataLike {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  if (!('body' in value) || !('slots' in value)) {
+    return false;
+  }
+  const { body } = value as { body?: unknown };
+  const { slots } = value as { slots?: unknown };
+  return typeof body === 'string' && Array.isArray(slots);
+}
+
+/**
+ * Decode daemon JSON output, unwrapping Endo CapData.
+ *
+ * @param raw - Raw stdout from `ocap daemon exec`.
+ * @param method - Wallet method name (for better errors).
+ * @returns The decoded value.
+ */
+function decodeCapData(raw: string, method: string): unknown {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`Wallet ${method} returned non-JSON output`);
+  }
+
+  if (!isCapDataLike(parsed)) {
+    return parsed;
+  }
+
+  if (!parsed.body.startsWith('#')) {
+    throw new Error(`Wallet ${method} returned invalid CapData body`);
+  }
+
+  const bodyContent = parsed.body.slice(1);
+
+  // Handle error bodies from vat exceptions (e.g. "#error:message")
+  if (bodyContent.startsWith('error:')) {
+    throw new Error(`Wallet ${method} vat error: ${bodyContent.slice(6)}`);
+  }
+
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(bodyContent);
+  } catch {
+    throw new Error(`Wallet ${method} returned undecodable CapData body`);
+  }
+
+  // Handle Endo CapData error encoding: #{"#error": "message", ...}
+  if (decoded !== null && typeof decoded === 'object' && '#error' in decoded) {
+    const errorMsg = (decoded as Record<string, unknown>)['#error'];
+    throw new Error(
+      `Wallet ${method} failed: ${typeof errorMsg === 'string' ? errorMsg : JSON.stringify(errorMsg)}`,
+    );
+  }
+
+  return decoded;
+}
+
+/**
+ * Run an `ocap daemon exec` command and return its output.
+ *
+ * @param options - Execution options.
+ * @param options.cliPath - Path to the ocap CLI.
+ * @param options.method - The daemon RPC method.
+ * @param options.params - The method parameters.
+ * @param options.timeoutMs - Timeout in ms.
+ * @returns The command result.
+ */
+async function runDaemonExec(options: {
+  cliPath: string;
+  method: string;
+  params: unknown;
+  timeoutMs: number;
+}): Promise<ExecResult> {
+  const { cliPath, method, params, timeoutMs } = options;
+  const daemonArgs = ['daemon', 'exec', method, JSON.stringify(params)];
+
+  // If cliPath points to a .mjs file, invoke it via node.
+  const command = cliPath.endsWith('.mjs') ? 'node' : cliPath;
+  const args = cliPath.endsWith('.mjs') ? [cliPath, ...daemonArgs] : daemonArgs;
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout?.setEncoding('utf8');
+    child.stderr?.setEncoding('utf8');
+    child.stdout?.on('data', (chunk: string) => {
+      stdout += chunk;
+    });
+    child.stderr?.on('data', (chunk: string) => {
+      stderr += chunk;
+    });
+
+    const timer = setTimeout(() => {
+      try {
+        child.kill('SIGKILL');
+      } finally {
+        reject(new Error(`ocap daemon exec timed out after ${timeoutMs}ms`));
+      }
+    }, timeoutMs);
+
+    child.once('error', (error: Error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+
+    child.once('exit', (code) => {
+      clearTimeout(timer);
+      resolve({ stdout, stderr, code: code ?? null });
+    });
+  });
+}
+
+/**
+ * Call a wallet coordinator method via the OCAP daemon.
+ *
+ * @param options - Call options.
+ * @returns The decoded response value.
+ */
+async function callWallet(options: WalletCallOptions): Promise<unknown> {
+  const { cliPath, walletKref, method, args, timeoutMs } = options;
+  const result = await runDaemonExec({
+    cliPath,
+    method: 'queueMessage',
+    params: [walletKref, method, args],
+    timeoutMs,
+  });
+
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || result.stdout.trim();
+    throw new Error(`Wallet ${method} failed (exit ${result.code}): ${detail}`);
+  }
+
+  return decodeCapData(result.stdout.trim(), method);
+}
@@ -0,0 +1,55 @@
+/**
+ * OpenClaw wallet plugin: registers tools that forward to the OCAP daemon.
+ *
+ * The OCAP daemon runs the evm-wallet subcluster. This plugin sends JSON-RPC
+ * messages to the daemon over its Unix socket, routing wallet operations
+ * through the kernel's capability system. The AI agent never touches keys.
+ *
+ * Enable tools via agents.list[].tools.allow: ["wallet_balance", "wallet_send"]
+ * or allow all with ["wallet"].
+ *
+ * Config (optional, in openclaw plugin settings):
+ *   ocapCliPath  - Absolute path to the `ocap` CLI (auto-detected from monorepo)
+ *   walletKref   - The kernel reference for the wallet coordinator (default: "ko4")
+ */
+import { resolve as resolvePath, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { makeWalletCaller } from './daemon.ts';
+import { registerEthTools } from './tools/eth.ts';
+import { registerMiscTools } from './tools/misc.ts';
+import { registerSwapTools } from './tools/swap.ts';
+import { registerTokenTools } from './tools/token.ts';
+import type { OpenClawPluginApi } from './types.ts';
+
+const pluginDir = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_CLI = resolvePath(pluginDir, '../../kernel-cli/dist/app.mjs');
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+/**
+ * Register the wallet plugin tools.
+ *
+ * @param api - The OpenClaw plugin API.
+ */
+export default function register(api: OpenClawPluginApi): void {
+  const { pluginConfig } = api;
+  const cliPath =
+    typeof pluginConfig?.ocapCliPath === 'string'
+      ? pluginConfig.ocapCliPath.trim()
+      : DEFAULT_CLI;
+  const walletKref =
+    typeof pluginConfig?.walletKref === 'string'
+      ? pluginConfig.walletKref.trim()
+      : 'ko4';
+  const timeoutMs =
+    typeof pluginConfig?.timeoutMs === 'number'
+      ? pluginConfig.timeoutMs
+      : DEFAULT_TIMEOUT_MS;
+
+  const wallet = makeWalletCaller({ cliPath, walletKref, timeoutMs });
+
+  registerEthTools(api, wallet);
+  registerTokenTools(api, wallet);
+  registerSwapTools(api, wallet);
+  registerMiscTools(api, wallet);
+}
@@ -0,0 +1,36 @@
+{
+  "id": "wallet",
+  "name": "Wallet (OCAP)",
+  "description": "Ethereum wallet tools backed by the OCAP kernel daemon. The AI agent can check balances (ETH and ERC-20 tokens), send transactions (native and token transfers), resolve token symbols to addresses, and sign messages without accessing private keys.",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "ocapCliPath": {
+        "type": "string",
+        "description": "Absolute path to the ocap CLI entry point (.mjs file or binary). Default: 'ocap' from PATH."
+      },
+      "walletKref": {
+        "type": "string",
+        "description": "Kernel reference of the wallet coordinator (e.g. 'ko4'). Found via `ocap daemon exec getStatus`."
+      },
+      "timeoutMs": {
+        "type": "number",
+        "description": "Timeout for daemon calls in ms (default: 60000)"
+      }
+    }
+  },
+  "uiHints": {
+    "walletKref": {
+      "label": "Wallet Coordinator KRef",
+      "placeholder": "ko4"
+    },
+    "ocapCliPath": {
+      "label": "OCAP CLI Path",
+      "placeholder": "~/ocap-kernel/packages/kernel-cli/dist/app.mjs"
+    },
+    "timeoutMs": {
+      "label": "Timeout (ms)",
+      "placeholder": "60000"
+    }
+  }
+}
@@ -0,0 +1,14 @@
+{
+  "name": "@openclaw/wallet",
+  "version": "0.0.1",
+  "description": "Wallet plugin: tools that call the away kernel CLI (balance, send, sign).",
+  "type": "module",
+  "devDependencies": {
+    "openclaw": "workspace:*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}
@@ -0,0 +1,54 @@
+---
+name: wallet
+description: Use the wallet tools for all balance, send, and sign operations. Supports both ETH and ERC-20 tokens. The away wallet operates autonomously after setup — the home device does not need to be online.
+metadata: { 'openclaw': { 'emoji': '👛', 'requires': { 'bins': ['wallet'] } } }
+---
+
+# Wallet (ocap)
+
+Use the **wallet tools** for any Ethereum balance, send, or sign request. Do not use exec or other CLIs for wallet operations.
+
+## Tools
+
+- **wallet_accounts** — List wallet accounts. Returns cached home accounts if the home device is offline.
+- **wallet_balance** — Get ETH balance for an address. Use `wallet_accounts` first to find the right address.
+- **wallet_send** — Send ETH to an address. Fully autonomous — uses delegation redemption via the bundler, no home device needed.
+- **wallet_token_resolve** — Resolve a token symbol or name (e.g. "USDC") to its contract address on the current chain. Not available for testnets.
+- **wallet_token_balance** — Get ERC-20 token balance. Accepts a contract address or symbol (e.g. "USDC"). Returns human-readable amount with symbol.
+- **wallet_token_send** — Send ERC-20 tokens to an address. Accepts a contract address or symbol. Automatically converts decimal amounts using the token's decimals.
+- **wallet_token_info** — Get ERC-20 token metadata (name, symbol, decimals). Accepts a contract address or symbol.
+- **wallet_swap_quote** — Get a token swap quote without executing. Shows expected output amount, aggregator, and gas estimate. Accepts contract addresses or token symbols.
+- **wallet_swap** — Execute a token swap. Handles ERC-20 approval and swap in sequence. Accepts contract addresses or token symbols.
+- **wallet_sign** — Sign a message or typed data with the local key. The signature is valid for EIP-1271 verification against the smart account address.
+- **wallet_capabilities** — Check what the wallet can do (local keys, peer wallet, delegations, bundler, cached accounts, autonomy level).
+
+## Autonomy
+
+After setup, the away wallet is **fully autonomous** for sending ETH, sending ERC-20 tokens, and signing messages. The home device only needs to be online for signing as the home EOA address specifically (which is rarely needed). Check `wallet_capabilities` — if `autonomy` contains "offline-capable", the wallet works independently.
+
+## ERC-20 Token Operations
+
+All token tools accept either a **contract address** (0x...) or a **token symbol** (e.g. "USDC", "DAI"). When a symbol is given, the tool resolves it to the contract address on the current chain via the MetaMask Token API. This works on mainnet and major L2s but **not on testnets** — for testnets, provide the contract address directly.
+
+To send tokens, use `wallet_token_send` with the token (address or symbol), recipient, and amount in human-readable decimals (e.g., "100.5" for 100.5 USDC). The tool automatically queries the token's decimals and converts to raw units.
+
+To check a token balance, use `wallet_token_balance` with the token (address or symbol).
+
+If you need to discover a token's address, use `wallet_token_resolve` to search by name or symbol. If you need to check which token a contract is, use `wallet_token_info` to get its name, symbol, and decimals.
+
+## Token Swaps
+
+Use `wallet_swap_quote` to preview a swap before executing, and `wallet_swap` to execute. Both accept token symbols (e.g. "ETH", "USDC") or contract addresses. The swap uses MetaSwap (MetaMask's aggregator) to find the best rate across multiple DEXs.
+
+- Default slippage is 1%. Adjust with the `slippage` parameter (0.1–50%).
+- For ERC-20 source tokens, approval is handled automatically if needed.
+- When a smart account is configured, the approve and swap are batched atomically in a single UserOp — no separate approval transaction.
+- Native ETH is represented as "ETH" or the zero address.
+- Swaps are not available on all testnets — MetaSwap may not support them.
+
+## Rules
+
+- Use only the wallet tools for wallet operations.
+- Do not use exec to run cast, ethers, or other scripts for sending ETH/tokens or signing.
+- If a send or sign returns pending or waiting for approval, tell the user and do not retry with a different method.
+- Never prompt the user to type "yes" or "allow" in chat for approval; approval happens in the user's wallet or home UI.