@agentlayer.tech/wallet 0.1.0

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

@@ -0,0 +1,84 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const NETWORK_FILE = "network.json";
+
+function assertValidNetwork(network, fieldName = "network") {
+  const normalized = String(network ?? "").trim();
+  if (!["bitcoin", "testnet", "regtest"].includes(normalized)) {
+    throw new Error(`${fieldName} must be one of: bitcoin, testnet, regtest.`);
+  }
+  return normalized;
+}
+
+export class BtcNetworkState {
+  constructor(config) {
+    this.config = config;
+  }
+
+  async getActiveNetwork() {
+    const state = await this.#loadState();
+    return state.network;
+  }
+
+  async getNetworkInfo(networkOverride = undefined) {
+    const activeNetwork = networkOverride
+      ? assertValidNetwork(networkOverride)
+      : await this.getActiveNetwork();
+    return {
+      activeNetwork,
+      profiles: this.config.networkProfiles,
+      selectedProfile: this.config.networkProfiles[activeNetwork],
+    };
+  }
+
+  async setActiveNetwork({ network }) {
+    const nextNetwork = assertValidNetwork(network);
+    await this.#ensureLayout();
+    await fs.writeFile(this.#statePath(), JSON.stringify({ network: nextNetwork }, null, 2), {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+    return this.getNetworkInfo(nextNetwork);
+  }
+
+  async resolveRuntimeConfig(networkOverride = undefined) {
+    const activeNetwork = networkOverride
+      ? assertValidNetwork(networkOverride, "network")
+      : await this.getActiveNetwork();
+    const profile = this.config.networkProfiles[activeNetwork];
+    return {
+      ...this.config,
+      network: activeNetwork,
+      electrumProtocol: profile.electrumProtocol,
+      electrumHost: profile.electrumHost,
+      electrumPort: profile.electrumPort,
+    };
+  }
+
+  async #ensureLayout() {
+    await fs.mkdir(this.config.dataDir, { recursive: true, mode: 0o700 });
+    try {
+      await fs.access(this.#statePath());
+    } catch {
+      await fs.writeFile(
+        this.#statePath(),
+        JSON.stringify({ network: this.config.network }, null, 2),
+        { encoding: "utf8", mode: 0o600 }
+      );
+    }
+  }
+
+  async #loadState() {
+    await this.#ensureLayout();
+    const raw = await fs.readFile(this.#statePath(), "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+      network: assertValidNetwork(parsed.network),
+    };
+  }
+
+  #statePath() {
+    return path.join(this.config.dataDir, NETWORK_FILE);
+  }
+}

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

@@ -0,0 +1,257 @@
+import "dotenv/config";
+
+import crypto from "node:crypto";
+import { createServer } from "node:http";
+
+import { loadConfig } from "./config.js";
+import { jsonSafe, readJsonBody, sendJson } from "./json.js";
+import { LocalBtcVault } from "./local_vault.js";
+import { BtcNetworkState } from "./network_state.js";
+import { WdkBtcWalletService } from "./wdk_btc_wallet.js";
+
+const config = loadConfig();
+const service = new WdkBtcWalletService(config);
+const vault = new LocalBtcVault(config);
+const networkState = new BtcNetworkState(config);
+
+function notFound(response) {
+  sendJson(response, 404, { ok: false, error: "Not Found" });
+}
+
+function unauthorized(response) {
+  response.setHeader("WWW-Authenticate", 'Bearer realm="wdk-btc-wallet"');
+  sendJson(response, 401, { ok: false, error: "Unauthorized." });
+}
+
+function pathRequiresAuth(pathname) {
+  return pathname !== "/health";
+}
+
+function isAuthorized(request) {
+  const header = String(request.headers.authorization || "").trim();
+  if (!header.startsWith("Bearer ")) {
+    return false;
+  }
+  const provided = Buffer.from(header.slice("Bearer ".length).trim(), "utf8");
+  const expected = Buffer.from(String(config.authToken || ""), "utf8");
+  if (provided.length === 0 || provided.length !== expected.length) {
+    return false;
+  }
+  return crypto.timingSafeEqual(provided, expected);
+}
+
+async function withResolvedSeed(body = {}) {
+  const resolved = await vault.resolveSeedPhrase({
+    walletId: body.walletId,
+    seedPhrase: body.seedPhrase,
+  });
+  return {
+    ...body,
+    seedPhrase: resolved.seedPhrase,
+    walletId: resolved.walletId ?? body.walletId ?? null,
+    credentialSource: resolved.source,
+    unlockExpiresAt: resolved.unlockExpiresAt ?? null,
+  };
+}
+
+async function withResolvedNetwork(body = {}) {
+  const runtimeConfig = await networkState.resolveRuntimeConfig(body.network);
+  return {
+    ...body,
+    network: runtimeConfig.network,
+  };
+}
+
+async function handleRequest(request, response) {
+  try {
+    const url = new URL(request.url || "/", "http://localhost");
+    const { method = "GET" } = request;
+
+    if (pathRequiresAuth(url.pathname) && !isAuthorized(request)) {
+      return unauthorized(response);
+    }
+
+    if (method === "GET" && url.pathname === "/health") {
+      const runtimeConfig = await networkState.resolveRuntimeConfig();
+      const networkInfo = await networkState.getNetworkInfo();
+      return sendJson(response, 200, {
+        ok: true,
+        service: "wdk-btc-wallet",
+        version: "0.1.0",
+        wallet: "bitcoin",
+        network: runtimeConfig.network,
+        bip: config.bip,
+        host: config.host,
+        dataDir: config.dataDir,
+        authRequired: config.authRequired,
+        unlockTimeoutSeconds: config.unlockTimeoutSeconds,
+        availableNetworks: Object.keys(config.networkProfiles),
+        electrum: {
+          protocol: runtimeConfig.electrumProtocol,
+          host: runtimeConfig.electrumHost,
+          port: runtimeConfig.electrumPort,
+        },
+        networkProfiles: networkInfo.profiles,
+        source: "wdk",
+      });
+    }
+
+    if (method === "POST" && url.pathname === "/v1/btc/seed-phrase/generate") {
+      const body = await readJsonBody(request);
+      return sendJson(response, 200, {
+        ok: true,
+        data: service.generateSeedPhrase(body.words ?? 12),
+      });
+    }
+
+    if (method === "GET" && url.pathname === "/v1/btc/wallets") {
+      const activeNetwork = await networkState.getActiveNetwork();
+      return sendJson(response, 200, {
+        ok: true,
+        data: (await vault.listWallets()).map((wallet) => ({
+          ...wallet,
+          activeNetwork,
+        })),
+      });
+    }
+
+    if (method === "GET" && url.pathname === "/v1/btc/network") {
+      return sendJson(response, 200, {
+        ok: true,
+        data: await networkState.getNetworkInfo(),
+      });
+    }
+
+    if (method === "POST" && url.pathname === "/v1/btc/network/set") {
+      const body = await readJsonBody(request);
+      return sendJson(response, 200, {
+        ok: true,
+        data: await networkState.setActiveNetwork(body),
+      });
+    }
+
+    if (method === "POST" && url.pathname === "/v1/btc/wallets/get") {
+      const body = await readJsonBody(request);
+      const activeNetwork = await networkState.getActiveNetwork();
+      return sendJson(response, 200, {
+        ok: true,
+        data: {
+          ...(await vault.getWallet(body)),
+          activeNetwork,
+        },
+      });
+    }
+
+    if (method === "POST" && url.pathname === "/v1/btc/wallets/create") {
+      const body = await withResolvedNetwork(await readJsonBody(request));
+      return sendJson(response, 200, {
+        ok: true,
+        data: await vault.createWallet(body),
+      });
+    }
+
+    if (method === "POST" && url.pathname === "/v1/btc/wallets/import") {
+      const body = await withResolvedNetwork(await readJsonBody(request));
+      return sendJson(response, 200, {
+        ok: true,
+        data: await vault.importWallet(body),
+      });
+    }
+
+    if (method === "POST" && url.pathname === "/v1/btc/wallets/unlock") {
+      const body = await readJsonBody(request);
+      return sendJson(response, 200, {
+        ok: true,
+        data: await vault.unlockWallet(body),
+      });
+    }
+
+    if (method === "POST" && url.pathname === "/v1/btc/wallets/lock") {
+      const body = await readJsonBody(request);
+      return sendJson(response, 200, {
+        ok: true,
+        data: await vault.lockWallet(body),
+      });
+    }
+
+    if (method === "POST" && url.pathname === "/v1/btc/wallets/reveal-seed") {
+      const body = await readJsonBody(request);
+      return sendJson(response, 200, {
+        ok: true,
+        data: await vault.revealSeedPhrase(body),
+      });
+    }
+
+    if (method === "POST" && url.pathname === "/v1/btc/wallets/change-password") {
+      const body = await readJsonBody(request);
+      return sendJson(response, 200, {
+        ok: true,
+        data: await vault.changePassword(body),
+      });
+    }
+
+    if (method === "POST" && url.pathname === "/v1/btc/address/resolve") {
+      const body = await withResolvedNetwork(await withResolvedSeed(await readJsonBody(request)));
+      const data = await service.resolveAddress(body);
+      return sendJson(response, 200, { ok: true, data });
+    }
+
+    if (method === "POST" && url.pathname === "/v1/btc/balance/get") {
+      const body = await withResolvedNetwork(await withResolvedSeed(await readJsonBody(request)));
+      const data = await service.getBalance(body);
+      return sendJson(response, 200, { ok: true, data });
+    }
+
+    if (method === "POST" && url.pathname === "/v1/btc/transfers/get") {
+      const body = await withResolvedNetwork(await withResolvedSeed(await readJsonBody(request)));
+      const data = await service.getTransfers(body);
+      return sendJson(response, 200, { ok: true, data });
+    }
+
+    if (method === "POST" && url.pathname === "/v1/btc/max-spendable/get") {
+      const body = await withResolvedNetwork(await withResolvedSeed(await readJsonBody(request)));
+      const data = await service.getMaxSpendable(body);
+      return sendJson(response, 200, { ok: true, data });
+    }
+
+    if (method === "POST" && url.pathname === "/v1/btc/fee-rates/get") {
+      const body = await withResolvedNetwork(await readJsonBody(request));
+      const data = await service.getFeeRates(body);
+      return sendJson(response, 200, { ok: true, data });
+    }
+
+    if (method === "POST" && url.pathname === "/v1/btc/transfer/quote") {
+      const body = await withResolvedNetwork(await withResolvedSeed(await readJsonBody(request)));
+      const data = await service.quoteTransfer(body);
+      return sendJson(response, 200, { ok: true, data: jsonSafe(data) });
+    }
+
+    if (method === "POST" && url.pathname === "/v1/btc/transfer/send") {
+      const body = await withResolvedNetwork(await withResolvedSeed(await readJsonBody(request)));
+      const data = await service.sendTransfer(body);
+      return sendJson(response, 200, { ok: true, data: jsonSafe(data) });
+    }
+
+    return notFound(response);
+  } catch (error) {
+    return sendJson(response, 400, {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+const server = createServer((request, response) => {
+  handleRequest(request, response).catch((error) => {
+    sendJson(response, 500, {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  });
+});
+
+server.listen(config.port, config.host, () => {
+  console.log(
+    `wdk-btc-wallet listening on ${config.host}:${config.port} (${config.network}, bip${config.bip})`
+  );
+});

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

@@ -0,0 +1,332 @@
+import WDK from "@tetherto/wdk";
+import WalletManagerBtc, {
+  ElectrumSsl,
+  ElectrumTcp,
+  ElectrumTls,
+  ElectrumWs,
+} from "@tetherto/wdk-wallet-btc";
+
+function assertNonEmptyString(value, fieldName) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${fieldName} is required.`);
+  }
+  return value.trim();
+}
+
+function assertValidSeedPhrase(seedPhrase) {
+  const mnemonic = assertNonEmptyString(seedPhrase, "seedPhrase");
+  if (!WDK.isValidSeed(mnemonic)) {
+    throw new Error("seedPhrase must be a valid BIP-39 seed phrase.");
+  }
+  return mnemonic;
+}
+
+function assertValidNetwork(network, fieldName = "network") {
+  if (network === undefined || network === null || network === "") {
+    return null;
+  }
+  const normalized = String(network).trim();
+  if (!["bitcoin", "testnet", "regtest"].includes(normalized)) {
+    throw new Error(`${fieldName} must be one of: bitcoin, testnet, regtest.`);
+  }
+  return normalized;
+}
+
+function assertNonNegativeInteger(value, fieldName) {
+  if (typeof value === "boolean") {
+    throw new Error(`${fieldName} must be a non-negative integer.`);
+  }
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`${fieldName} must be a non-negative integer.`);
+  }
+  return parsed;
+}
+
+function assertPositiveInteger(value, fieldName) {
+  const parsed = assertNonNegativeInteger(value, fieldName);
+  if (parsed <= 0) {
+    throw new Error(`${fieldName} must be greater than zero.`);
+  }
+  return parsed;
+}
+
+function buildElectrumClient(config) {
+  const clientConfig = {
+    host: config.electrumHost,
+    port: config.electrumPort,
+    network: config.network,
+  };
+  if (config.electrumProtocol === "tcp") {
+    return new ElectrumTcp(clientConfig);
+  }
+  if (config.electrumProtocol === "tls") {
+    return new ElectrumTls(clientConfig);
+  }
+  if (config.electrumProtocol === "ssl") {
+    return new ElectrumSsl(clientConfig);
+  }
+  if (config.electrumProtocol === "ws") {
+    return new ElectrumWs(clientConfig);
+  }
+  throw new Error(`Unsupported Electrum protocol: ${config.electrumProtocol}`);
+}
+
+async function maybeDispose(value) {
+  if (value && typeof value.dispose === "function") {
+    await value.dispose();
+  }
+  if (value && typeof value.close === "function") {
+    await value.close();
+  }
+}
+
+export class WdkBtcWalletService {
+  constructor(config) {
+    this.config = config;
+  }
+
+  generateSeedPhrase(words = 12) {
+    const count = assertPositiveInteger(words, "words");
+    if (count !== 12) {
+      throw new Error(
+        "Only 12-word seed phrase generation is exposed by this service because that is the documented WDK helper surface."
+      );
+    }
+    return {
+      seedPhrase: WDK.getRandomSeedPhrase(),
+      wordCount: count,
+      source: "wdk",
+    };
+  }
+
+  async resolveAddress({ seedPhrase, accountIndex = 0, derivationPath = "", network }) {
+    return this.#withAccount(
+      { seedPhrase, accountIndex, derivationPath, network },
+      async (account, runtimeConfig) => ({
+      network: runtimeConfig.network,
+      bip: runtimeConfig.bip,
+      accountIndex: derivationPath ? null : accountIndex,
+      derivationPath: derivationPath || null,
+      address: await account.getAddress(),
+      source: "wdk-wallet-btc",
+      })
+    );
+  }
+
+  async getBalance({ seedPhrase, accountIndex = 0, derivationPath = "", network }) {
+    return this.#withAccount({ seedPhrase, accountIndex, derivationPath, network }, async (
+      account,
+      runtimeConfig
+    ) => {
+      const address = await account.getAddress();
+      const balance = await account.getBalance();
+      return {
+        network: runtimeConfig.network,
+        bip: runtimeConfig.bip,
+        accountIndex: derivationPath ? null : accountIndex,
+        derivationPath: derivationPath || null,
+        address,
+        balance,
+        source: "wdk-wallet-btc",
+      };
+    });
+  }
+
+  async getTransfers({
+    seedPhrase,
+    accountIndex = 0,
+    derivationPath = "",
+    network,
+    direction = "all",
+    limit = 10,
+    skip = 0,
+  }) {
+    return this.#withAccount(
+      { seedPhrase, accountIndex, derivationPath, network },
+      async (account, runtimeConfig) => {
+      if (!["incoming", "outgoing", "all"].includes(direction)) {
+        throw new Error("direction must be one of: incoming, outgoing, all.");
+      }
+      const options = {
+        direction,
+        limit: assertNonNegativeInteger(limit, "limit"),
+        skip: assertNonNegativeInteger(skip, "skip"),
+      };
+      const address = await account.getAddress();
+      const transfers = await account.getTransfers(options);
+      return {
+        network: runtimeConfig.network,
+        bip: runtimeConfig.bip,
+        accountIndex: derivationPath ? null : accountIndex,
+        derivationPath: derivationPath || null,
+        address,
+        options,
+        transfers,
+        source: "wdk-wallet-btc",
+      };
+      }
+    );
+  }
+
+  async getMaxSpendable({
+    seedPhrase,
+    accountIndex = 0,
+    derivationPath = "",
+    network,
+    feeRate,
+  }) {
+    return this.#withAccount(
+      { seedPhrase, accountIndex, derivationPath, network },
+      async (account, runtimeConfig) => {
+      const address = await account.getAddress();
+      const options = {};
+      if (feeRate !== undefined) {
+        options.feeRate = assertPositiveInteger(feeRate, "feeRate");
+      }
+      const maxSpendable = await account.getMaxSpendable(options);
+      return {
+        network: runtimeConfig.network,
+        bip: runtimeConfig.bip,
+        accountIndex: derivationPath ? null : accountIndex,
+        derivationPath: derivationPath || null,
+        address,
+        options,
+        maxSpendable,
+        source: "wdk-wallet-btc",
+      };
+      }
+    );
+  }
+
+  async getFeeRates({ seedPhrase = "", network } = {}) {
+    return this.#withWallet(
+      { seedPhrase: seedPhrase || WDK.getRandomSeedPhrase(), network },
+      async (wallet, runtimeConfig) => {
+      const feeRates = await wallet.getFeeRates();
+      return {
+        network: runtimeConfig.network,
+        feeRates,
+        source: "wdk-wallet-btc",
+      };
+      }
+    );
+  }
+
+  async quoteTransfer({
+    seedPhrase,
+    to,
+    value,
+    accountIndex = 0,
+    derivationPath = "",
+    network,
+    feeRate,
+    confirmationTarget,
+  }) {
+    return this.#withAccount(
+      { seedPhrase, accountIndex, derivationPath, network },
+      async (account, runtimeConfig) => {
+      const tx = this.#buildTransaction({ to, value, feeRate, confirmationTarget });
+      const quote = await account.quoteSendTransaction(tx);
+      return {
+        network: runtimeConfig.network,
+        bip: runtimeConfig.bip,
+        accountIndex: derivationPath ? null : accountIndex,
+        derivationPath: derivationPath || null,
+        transaction: tx,
+        quote,
+        source: "wdk-wallet-btc",
+      };
+      }
+    );
+  }
+
+  async sendTransfer({
+    seedPhrase,
+    to,
+    value,
+    accountIndex = 0,
+    derivationPath = "",
+    network,
+    feeRate,
+    confirmationTarget,
+  }) {
+    return this.#withAccount(
+      { seedPhrase, accountIndex, derivationPath, network },
+      async (account, runtimeConfig) => {
+      if (typeof account.sendTransaction !== "function") {
+        throw new Error("The current WDK BTC account does not expose sendTransaction.");
+      }
+      const tx = this.#buildTransaction({ to, value, feeRate, confirmationTarget });
+      const result = await account.sendTransaction(tx);
+      return {
+        network: runtimeConfig.network,
+        bip: runtimeConfig.bip,
+        accountIndex: derivationPath ? null : accountIndex,
+        derivationPath: derivationPath || null,
+        transaction: tx,
+        result,
+        source: "wdk-wallet-btc",
+      };
+      }
+    );
+  }
+
+  #buildTransaction({ to, value, feeRate, confirmationTarget }) {
+    const tx = {
+      to: assertNonEmptyString(to, "to"),
+      value: assertPositiveInteger(value, "value"),
+    };
+    if (feeRate !== undefined) {
+      tx.feeRate = assertPositiveInteger(feeRate, "feeRate");
+    }
+    if (confirmationTarget !== undefined) {
+      tx.confirmationTarget = assertPositiveInteger(
+        confirmationTarget,
+        "confirmationTarget"
+      );
+    }
+    return tx;
+  }
+
+  #resolveRuntimeConfig(networkOverride) {
+    const network = assertValidNetwork(networkOverride) || this.config.network;
+    const profile = this.config.networkProfiles?.[network];
+    if (!profile) {
+      throw new Error(`Missing Electrum profile for network: ${network}`);
+    }
+    return {
+      ...this.config,
+      network,
+      electrumProtocol: profile.electrumProtocol,
+      electrumHost: profile.electrumHost,
+      electrumPort: profile.electrumPort,
+    };
+  }
+
+  async #withWallet({ seedPhrase, network }, callback) {
+    const mnemonic = assertValidSeedPhrase(seedPhrase);
+    const runtimeConfig = this.#resolveRuntimeConfig(network);
+    const client = buildElectrumClient(runtimeConfig);
+    const wallet = new WalletManagerBtc(mnemonic, {
+      client,
+      network: runtimeConfig.network,
+      bip: runtimeConfig.bip,
+    });
+    try {
+      return await callback(wallet, runtimeConfig);
+    } finally {
+      await maybeDispose(wallet);
+      await maybeDispose(client);
+    }
+  }
+
+  async #withAccount({ seedPhrase, accountIndex, derivationPath, network }, callback) {
+    return this.#withWallet({ seedPhrase, network }, async (wallet, runtimeConfig) => {
+      const account = derivationPath
+        ? await wallet.getAccountByPath(assertNonEmptyString(derivationPath, "derivationPath"))
+        : await wallet.getAccount(assertNonNegativeInteger(accountIndex, "accountIndex"));
+      return await callback(account, runtimeConfig);
+    });
+  }
+}