@agentlayer.tech/wallet 0.1.0

package/wdk-btc-wallet/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "wdk-btc-wallet",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Separate BTC-only wallet service built on Tether WDK.",
+  "scripts": {
+    "bootstrap": "sh ./bootstrap.sh",
+    "start:local": "sh ./run-local.sh",
+    "start": "node src/server.js",
+    "check": "node --check src/server.js && node --check src/wdk_btc_wallet.js && node --check src/config.js && node --check src/json.js"
+  },
+  "dependencies": {
+    "@tetherto/wdk": "^1.0.0-beta.6",
+    "@tetherto/wdk-wallet-btc": "^1.0.0-beta.5",
+    "dotenv": "^16.4.5"
+  }
+}

package/wdk-btc-wallet/run-local.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+set -eu
+
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname "$0")" && pwd)"
+cd "$SCRIPT_DIR"
+
+if [ ! -f .env ]; then
+  cp .env.example .env
+  echo "Created .env from .env.example"
+fi
+
+if [ -z "${NPM_CONFIG_CACHE:-}" ]; then
+  export NPM_CONFIG_CACHE=/tmp/npm-cache
+fi
+
+if [ ! -d node_modules ]; then
+  echo "Installing dependencies..."
+  npm install
+fi
+
+exec npm start

package/wdk-btc-wallet/src/config.js

@@ -0,0 +1,160 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const DEFAULTS = {
+  host: "127.0.0.1",
+  port: 8080,
+  network: "bitcoin",
+  bip: 84,
+  unlockTimeoutSeconds: 0,
+};
+
+const DEFAULT_NETWORK_PROFILES = {
+  bitcoin: {
+    electrumProtocol: "tcp",
+    electrumHost: "electrum.blockstream.info",
+    electrumPort: 50001,
+  },
+  testnet: {
+    electrumProtocol: "tcp",
+    electrumHost: "blockstream.info",
+    electrumPort: 143,
+  },
+  regtest: {
+    electrumProtocol: "tcp",
+    electrumHost: "127.0.0.1",
+    electrumPort: 60401,
+  },
+};
+
+function parseInteger(value, fallback, fieldName) {
+  const normalized = String(value ?? "").trim();
+  if (!normalized) {
+    return fallback;
+  }
+  const parsed = Number.parseInt(normalized, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${fieldName} must be a positive integer.`);
+  }
+  return parsed;
+}
+
+function parseNonNegativeInteger(value, fallback, fieldName) {
+  const normalized = String(value ?? "").trim();
+  if (!normalized) {
+    return fallback;
+  }
+  const parsed = Number.parseInt(normalized, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new Error(`${fieldName} must be a non-negative integer.`);
+  }
+  return parsed;
+}
+
+function resolveOpenClawHome(env) {
+  const configured = String(env.OPENCLAW_HOME ?? "").trim();
+  if (!configured) {
+    return path.join(os.homedir(), ".openclaw");
+  }
+  if (configured === "~") {
+    return os.homedir();
+  }
+  if (configured.startsWith("~/")) {
+    return path.join(os.homedir(), configured.slice(2));
+  }
+  return configured;
+}
+
+function ensureLocalAuthToken(tokenPath, configuredToken = "") {
+  const direct = String(configuredToken ?? "").trim();
+  if (direct) {
+    return direct;
+  }
+  fs.mkdirSync(path.dirname(tokenPath), { recursive: true, mode: 0o700 });
+  try {
+    const existing = fs.readFileSync(tokenPath, "utf8").trim();
+    if (existing) {
+      fs.chmodSync(tokenPath, 0o600);
+      return existing;
+    }
+  } catch {
+    // Generate a new token below.
+  }
+
+  const generated = crypto.randomBytes(32).toString("hex");
+  fs.writeFileSync(tokenPath, `${generated}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  fs.chmodSync(tokenPath, 0o600);
+  return generated;
+}
+
+export function loadConfig(env = process.env) {
+  const host = String(env.HOST ?? DEFAULTS.host).trim() || DEFAULTS.host;
+  const network = String(env.WDK_BTC_NETWORK ?? DEFAULTS.network).trim() || DEFAULTS.network;
+  if (!["bitcoin", "testnet", "regtest"].includes(network)) {
+    throw new Error("WDK_BTC_NETWORK must be one of: bitcoin, testnet, regtest.");
+  }
+
+  const bip = parseInteger(env.WDK_BTC_BIP, DEFAULTS.bip, "WDK_BTC_BIP");
+  if (![44, 84].includes(bip)) {
+    throw new Error("WDK_BTC_BIP must be either 44 or 84.");
+  }
+  const openClawHome = resolveOpenClawHome(env);
+  const dataDir =
+    String(env.WDK_BTC_DATA_DIR ?? "").trim() ||
+    path.join(openClawHome, "wdk-btc-wallet");
+  const authTokenPath =
+    String(env.WDK_BTC_LOCAL_TOKEN_PATH ?? "").trim() ||
+    path.join(openClawHome, "wdk-btc-wallet", "local-auth-token");
+
+  const networkProfiles = Object.fromEntries(
+    Object.entries(DEFAULT_NETWORK_PROFILES).map(([name, defaults]) => {
+      const prefix = `WDK_BTC_${name.toUpperCase()}_ELECTRUM_`;
+      const electrumProtocol =
+        String(env[`${prefix}PROTOCOL`] ?? defaults.electrumProtocol).trim().toLowerCase() ||
+        defaults.electrumProtocol;
+      if (!["tcp", "tls", "ssl", "ws"].includes(electrumProtocol)) {
+        throw new Error(
+          `${prefix}PROTOCOL must be one of: tcp, tls, ssl, ws.`
+        );
+      }
+      const electrumHost =
+        String(env[`${prefix}HOST`] ?? defaults.electrumHost).trim() || defaults.electrumHost;
+      const electrumPort = parseInteger(
+        env[`${prefix}PORT`],
+        defaults.electrumPort,
+        `${prefix}PORT`
+      );
+      return [
+        name,
+        {
+          electrumProtocol,
+          electrumHost,
+          electrumPort,
+        },
+      ];
+    })
+  );
+
+  return {
+    host,
+    port: parseInteger(env.PORT, DEFAULTS.port, "PORT"),
+    network,
+    bip,
+    openClawHome,
+    dataDir,
+    authRequired: true,
+    authTokenPath,
+    authToken: ensureLocalAuthToken(authTokenPath, env.WDK_BTC_LOCAL_TOKEN),
+    unlockTimeoutSeconds: parseNonNegativeInteger(
+      env.WDK_BTC_UNLOCK_TIMEOUT_SECONDS,
+      DEFAULTS.unlockTimeoutSeconds,
+      "WDK_BTC_UNLOCK_TIMEOUT_SECONDS"
+    ),
+    networkProfiles,
+  };
+}

package/wdk-btc-wallet/src/json.js

@@ -0,0 +1,35 @@
+export function jsonSafe(value) {
+  if (typeof value === "bigint") {
+    return value.toString();
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => jsonSafe(item));
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, jsonSafe(item)])
+    );
+  }
+  return value;
+}
+
+export function sendJson(response, statusCode, payload) {
+  const body = JSON.stringify(jsonSafe(payload));
+  response.writeHead(statusCode, {
+    "Content-Type": "application/json",
+    "Content-Length": Buffer.byteLength(body),
+  });
+  response.end(body);
+}
+
+export async function readJsonBody(request) {
+  const chunks = [];
+  for await (const chunk of request) {
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString("utf8").trim();
+  if (!raw) {
+    return {};
+  }
+  return JSON.parse(raw);
+}

package/wdk-btc-wallet/src/local_vault.js

@@ -0,0 +1,432 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import WDK from "@tetherto/wdk";
+
+const scryptAsync = promisify(crypto.scrypt);
+
+const REGISTRY_FILE = "registry.json";
+const WALLETS_DIR = "wallets";
+const VAULT_VERSION = 1;
+
+function assertNonEmptyString(value, fieldName) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${fieldName} is required.`);
+  }
+  return value.trim();
+}
+
+function assertPositiveInteger(value, fieldName) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`${fieldName} must be a positive integer.`);
+  }
+  return parsed;
+}
+
+function assertNonNegativeInteger(value, fieldName) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`${fieldName} must be a non-negative integer.`);
+  }
+  return parsed;
+}
+
+function sanitizeLabel(label) {
+  const normalized = String(label ?? "").trim();
+  return normalized || "BTC Wallet";
+}
+
+function assertValidNetwork(network, fieldName = "network") {
+  const normalized = assertNonEmptyString(network, fieldName);
+  if (!["bitcoin", "testnet", "regtest"].includes(normalized)) {
+    throw new Error(`${fieldName} must be one of: bitcoin, testnet, regtest.`);
+  }
+  return normalized;
+}
+
+async function deriveKey(password, salt) {
+  return scryptAsync(password, salt, 32, {
+    N: 1 << 15,
+    r: 8,
+    p: 1,
+    maxmem: 64 * 1024 * 1024,
+  });
+}
+
+async function encryptSeedPhrase({ seedPhrase, password, walletId }) {
+  const salt = crypto.randomBytes(16);
+  const iv = crypto.randomBytes(12);
+  const key = await deriveKey(password, salt);
+  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+  cipher.setAAD(Buffer.from(`wdk-btc-wallet:${walletId}:v${VAULT_VERSION}`, "utf8"));
+  const ciphertext = Buffer.concat([
+    cipher.update(Buffer.from(seedPhrase, "utf8")),
+    cipher.final(),
+  ]);
+  const tag = cipher.getAuthTag();
+  return {
+    version: VAULT_VERSION,
+    kdf: {
+      name: "scrypt",
+      salt: salt.toString("base64"),
+      N: 1 << 15,
+      r: 8,
+      p: 1,
+    },
+    cipher: {
+      name: "aes-256-gcm",
+      iv: iv.toString("base64"),
+      tag: tag.toString("base64"),
+    },
+    ciphertext: ciphertext.toString("base64"),
+  };
+}
+
+async function decryptSeedPhrase({ encrypted, password, walletId }) {
+  const salt = Buffer.from(encrypted.kdf.salt, "base64");
+  const iv = Buffer.from(encrypted.cipher.iv, "base64");
+  const tag = Buffer.from(encrypted.cipher.tag, "base64");
+  const ciphertext = Buffer.from(encrypted.ciphertext, "base64");
+  const key = await deriveKey(password, salt);
+  const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+  decipher.setAAD(Buffer.from(`wdk-btc-wallet:${walletId}:v${VAULT_VERSION}`, "utf8"));
+  decipher.setAuthTag(tag);
+  const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  return plaintext.toString("utf8");
+}
+
+async function decryptSeedPhraseWithPasswordCheck(args) {
+  try {
+    return await decryptSeedPhrase(args);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (
+      message.includes("authenticate data") ||
+      message.includes("unable to authenticate") ||
+      message.includes("Unsupported state")
+    ) {
+      throw new Error("Invalid password.");
+    }
+    throw error;
+  }
+}
+
+export class LocalBtcVault {
+  constructor(config) {
+    this.config = config;
+    this._unlocked = new Map();
+  }
+
+  async createWallet({
+    label = "",
+    password,
+    words = 12,
+    revealSeedPhrase = false,
+    network,
+  }) {
+    const count = assertPositiveInteger(words, "words");
+    if (count !== 12) {
+      throw new Error("Only 12-word wallet creation is currently supported.");
+    }
+    const seedPhrase = WDK.getRandomSeedPhrase();
+    const wallet = await this.#storeWallet({
+      label,
+      password,
+      seedPhrase,
+      source: "created",
+      network,
+    });
+    await this.unlockWallet({ walletId: wallet.walletId, password, timeoutSeconds: 0 });
+    return {
+      ...wallet,
+      unlocked: true,
+      unlockExpiresAt: null,
+      ...(revealSeedPhrase ? { seedPhrase } : {}),
+    };
+  }
+
+  async importWallet({ label = "", password, seedPhrase, network }) {
+    const mnemonic = assertNonEmptyString(seedPhrase, "seedPhrase");
+    if (!WDK.isValidSeed(mnemonic)) {
+      throw new Error("seedPhrase must be a valid BIP-39 seed phrase.");
+    }
+    const wallet = await this.#storeWallet({
+      label,
+      password,
+      seedPhrase: mnemonic,
+      source: "imported",
+      network,
+    });
+    await this.unlockWallet({ walletId: wallet.walletId, password, timeoutSeconds: 0 });
+    return {
+      ...wallet,
+      unlocked: true,
+      unlockExpiresAt: null,
+    };
+  }
+
+  async listWallets() {
+    this.#sweepExpiredUnlocked();
+    const registry = await this.#loadRegistry();
+    return registry.wallets.map((wallet) => {
+      const unlocked = this._unlocked.get(wallet.walletId);
+      return {
+        ...wallet,
+        unlocked: Boolean(unlocked),
+        unlockExpiresAt: unlocked ? unlocked.expiresAt : null,
+      };
+    });
+  }
+
+  async getWallet({ walletId }) {
+    this.#sweepExpiredUnlocked();
+    const wallet = await this.#getWalletMetadata(assertNonEmptyString(walletId, "walletId"));
+    const unlocked = this._unlocked.get(wallet.walletId);
+    return {
+      ...wallet,
+      unlocked: Boolean(unlocked),
+      unlockExpiresAt: unlocked ? unlocked.expiresAt : null,
+    };
+  }
+
+  async unlockWallet({ walletId, password, timeoutSeconds }) {
+    const metadata = await this.#getWalletMetadata(assertNonEmptyString(walletId, "walletId"));
+    const encrypted = await this.#loadEncryptedWallet(walletId);
+    const secret = await decryptSeedPhraseWithPasswordCheck({
+      encrypted,
+      password: assertNonEmptyString(password, "password"),
+      walletId,
+    });
+    if (!WDK.isValidSeed(secret)) {
+      throw new Error("Decrypted wallet seed phrase is invalid.");
+    }
+    const ttl =
+      timeoutSeconds === undefined || timeoutSeconds === null
+        ? this.config.unlockTimeoutSeconds
+        : assertNonNegativeInteger(timeoutSeconds, "timeoutSeconds");
+    const expiresAt = ttl === 0 ? null : new Date(Date.now() + ttl * 1000).toISOString();
+    this._unlocked.set(walletId, {
+      seedPhrase: secret,
+      expiresAt,
+    });
+    return {
+      walletId,
+      label: metadata.label,
+      unlocked: true,
+      unlockExpiresAt: expiresAt,
+    };
+  }
+
+  async lockWallet({ walletId }) {
+    this._unlocked.delete(assertNonEmptyString(walletId, "walletId"));
+    return {
+      walletId,
+      unlocked: false,
+    };
+  }
+
+  async revealSeedPhrase({ walletId, password }) {
+    const id = assertNonEmptyString(walletId, "walletId");
+    const metadata = await this.#getWalletMetadata(id);
+    const encrypted = await this.#loadEncryptedWallet(id);
+    const seedPhrase = await decryptSeedPhraseWithPasswordCheck({
+      encrypted,
+      password: assertNonEmptyString(password, "password"),
+      walletId: id,
+    });
+    if (!WDK.isValidSeed(seedPhrase)) {
+      throw new Error("Decrypted wallet seed phrase is invalid.");
+    }
+    return {
+      walletId: id,
+      label: metadata.label,
+      seedPhrase,
+    };
+  }
+
+  async changePassword({ walletId, currentPassword, newPassword }) {
+    const id = assertNonEmptyString(walletId, "walletId");
+    const safeCurrentPassword = assertNonEmptyString(currentPassword, "currentPassword");
+    const safeNewPassword = assertNonEmptyString(newPassword, "newPassword");
+    const metadata = await this.#getWalletMetadata(id);
+    const encrypted = await this.#loadEncryptedWallet(id);
+    const seedPhrase = await decryptSeedPhraseWithPasswordCheck({
+      encrypted,
+      password: safeCurrentPassword,
+      walletId: id,
+    });
+    if (!WDK.isValidSeed(seedPhrase)) {
+      throw new Error("Decrypted wallet seed phrase is invalid.");
+    }
+    const reencrypted = await encryptSeedPhrase({
+      seedPhrase,
+      password: safeNewPassword,
+      walletId: id,
+    });
+    await fs.writeFile(this.#walletFilePath(id), JSON.stringify(reencrypted, null, 2), {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+
+    const registry = await this.#loadRegistry();
+    const index = registry.wallets.findIndex((wallet) => wallet.walletId === id);
+    if (index === -1) {
+      throw new Error(`Unknown walletId: ${id}`);
+    }
+    const updatedAt = new Date().toISOString();
+    registry.wallets[index] = {
+      ...registry.wallets[index],
+      updatedAt,
+    };
+    await this.#saveRegistry(registry);
+
+    const unlocked = this._unlocked.get(id);
+    if (unlocked) {
+      this._unlocked.set(id, {
+        seedPhrase,
+        expiresAt: unlocked.expiresAt,
+      });
+    }
+
+    return {
+      walletId: id,
+      label: metadata.label,
+      passwordChanged: true,
+      updatedAt,
+      unlocked: Boolean(this._unlocked.get(id)),
+      unlockExpiresAt: this._unlocked.get(id)?.expiresAt ?? null,
+    };
+  }
+
+  async resolveSeedPhrase({ walletId, seedPhrase }) {
+    if (typeof seedPhrase === "string" && seedPhrase.trim()) {
+      if (!WDK.isValidSeed(seedPhrase.trim())) {
+        throw new Error("seedPhrase must be a valid BIP-39 seed phrase.");
+      }
+      return {
+        seedPhrase: seedPhrase.trim(),
+        source: "request",
+        walletId: null,
+      };
+    }
+    const id = assertNonEmptyString(walletId, "walletId");
+    this.#sweepExpiredUnlocked();
+    const unlocked = this._unlocked.get(id);
+    if (!unlocked) {
+      throw new Error("Wallet is locked. Unlock it first or provide seedPhrase explicitly.");
+    }
+    return {
+      seedPhrase: unlocked.seedPhrase,
+      source: "local-vault",
+      walletId: id,
+      unlockExpiresAt: unlocked.expiresAt,
+    };
+  }
+
+  async #storeWallet({ label, password, seedPhrase, source, network }) {
+    const safePassword = assertNonEmptyString(password, "password");
+    await this.#ensureLayout();
+
+    const walletId = crypto.randomUUID();
+    const now = new Date().toISOString();
+    const encrypted = await encryptSeedPhrase({
+      seedPhrase,
+      password: safePassword,
+      walletId,
+    });
+    const entry = {
+      walletId,
+      label: sanitizeLabel(label),
+      createdAt: now,
+      updatedAt: now,
+      network: assertValidNetwork(network ?? this.config.network, "network"),
+      bip: this.config.bip,
+      source,
+    };
+
+    await fs.writeFile(this.#walletFilePath(walletId), JSON.stringify(encrypted, null, 2), {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+    const registry = await this.#loadRegistry();
+    registry.wallets.push(entry);
+    await this.#saveRegistry(registry);
+
+    return {
+      walletId,
+      label: entry.label,
+      createdAt: entry.createdAt,
+      updatedAt: entry.updatedAt,
+      network: entry.network,
+      bip: entry.bip,
+      source: entry.source,
+    };
+  }
+
+  async #getWalletMetadata(walletId) {
+    const registry = await this.#loadRegistry();
+    const wallet = registry.wallets.find((item) => item.walletId === walletId);
+    if (!wallet) {
+      throw new Error(`Unknown walletId: ${walletId}`);
+    }
+    return wallet;
+  }
+
+  async #loadEncryptedWallet(walletId) {
+    const raw = await fs.readFile(this.#walletFilePath(walletId), "utf8");
+    return JSON.parse(raw);
+  }
+
+  async #ensureLayout() {
+    await fs.mkdir(this.config.dataDir, { recursive: true, mode: 0o700 });
+    await fs.mkdir(path.join(this.config.dataDir, WALLETS_DIR), {
+      recursive: true,
+      mode: 0o700,
+    });
+    try {
+      await fs.access(this.#registryPath());
+    } catch {
+      await this.#saveRegistry({
+        version: VAULT_VERSION,
+        wallets: [],
+      });
+    }
+  }
+
+  async #loadRegistry() {
+    await this.#ensureLayout();
+    const raw = await fs.readFile(this.#registryPath(), "utf8");
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed.wallets)) {
+      throw new Error("Vault registry is invalid.");
+    }
+    return parsed;
+  }
+
+  async #saveRegistry(registry) {
+    await fs.writeFile(this.#registryPath(), JSON.stringify(registry, null, 2), {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+  }
+
+  #walletFilePath(walletId) {
+    return path.join(this.config.dataDir, WALLETS_DIR, `${walletId}.json`);
+  }
+
+  #registryPath() {
+    return path.join(this.config.dataDir, REGISTRY_FILE);
+  }
+
+  #sweepExpiredUnlocked() {
+    const now = Date.now();
+    for (const [walletId, state] of this._unlocked.entries()) {
+      if (state.expiresAt && Date.parse(state.expiresAt) <= now) {
+        this._unlocked.delete(walletId);
+      }
+    }
+  }
+}