diff --git a/scripts/theme-baseline.json b/scripts/theme-baseline.json
index 6f7651b3..39c476f2 100644
--- a/scripts/theme-baseline.json
+++ b/scripts/theme-baseline.json
@@ -12,6 +12,5 @@
"src/workspaces/officerdev/src/apps/Preview": 4,
"src/workspaces/officerdev/src/apps/QrTransfer": 5,
"src/workspaces/officerdev/src/apps/SystemMonitor": 1,
- "src/workspaces/officerdev/src/apps/Terminal": 10,
- "src/workspaces/officerdev/src/apps/Wallet": 68
+ "src/workspaces/officerdev/src/apps/Terminal": 10
}
diff --git a/src/apps/officer-web/App.tsx b/src/apps/officer-web/App.tsx
index e09bd5db..bdf714ae 100644
--- a/src/apps/officer-web/App.tsx
+++ b/src/apps/officer-web/App.tsx
@@ -107,8 +107,6 @@ export function App() {
} />
} />
} />
- } />
- } />
} />
} />
{/* TEMPORARY / EXPERIMENTAL — offline file transfer over animated QR codes */}
diff --git a/src/apps/officer-web/Screens/Dashboard/Wallet/WalletScreen.tsx b/src/apps/officer-web/Screens/Dashboard/Wallet/WalletScreen.tsx
deleted file mode 100644
index 5f612ace..00000000
--- a/src/apps/officer-web/Screens/Dashboard/Wallet/WalletScreen.tsx
+++ /dev/null
@@ -1,39 +0,0 @@
-import { Navigate, useLocation, useParams } from 'react-router';
-import type { LayoutNode } from 'officerdev';
-import { WorkspaceView, DEFAULT_WALLET_SECTION, walletSectionPath, isWalletSection } from 'officerdev';
-import { useDashboardState } from 'state/useDashboardState';
-import { defaultLayout } from './defaultLayout';
-
-// /wallet uses the Workspace/Panel system (like /command-hq): the wallet list and section nav on the left,
-// the section itself on the right. Both talk to the officer-wallet sidecar through the /api/wallet auth
-// proxy, which holds no key material of its own — seeds live encrypted in the sidecar and are decrypted
-// there only for the length of an unlock window.
-//
-// The open section is :section in the URL, the open wallet is ?wallet= and any coin-control selection is
-// ?coins=, so both panels read the URL with useParams/useSearchParams rather than passing state between
-// themselves over a channel. This screen backs both /wallet and /wallet/:section and is the single place
-// that decides what an absent or bogus section means.
-
-export const WalletScreen = () => {
- const { section } = useParams();
- const { search } = useLocation();
- const workspace = useDashboardState('screens/wallet', defaultLayout);
-
- // Bare /wallet, or a section that doesn't exist, resolves to a canonical URL rather than rendering a
- // default while the address bar says something else — the nav highlight is derived from the URL. The
- // ?wallet= param is deliberately carried through rather than dropped: /wallet?wallet=3 is a legitimate
- // deep link and canonicalising the section must not silently change which wallet is open.
- if (!isWalletSection(section)) {
- return ;
- }
-
- return (
-
-
-
- );
-};
diff --git a/src/apps/officer-web/Screens/Dashboard/Wallet/defaultLayout.ts b/src/apps/officer-web/Screens/Dashboard/Wallet/defaultLayout.ts
deleted file mode 100644
index ebdad736..00000000
--- a/src/apps/officer-web/Screens/Dashboard/Wallet/defaultLayout.ts
+++ /dev/null
@@ -1,11 +0,0 @@
-import type { LayoutNode } from 'officerdev';
-
-export const defaultLayout: LayoutNode = {
- type: 'group',
- id: 'wallet-root',
- direction: 'horizontal',
- children: [
- { node: { type: 'panel', id: 'wallet-nav', appType: 'wallet-nav' }, size: 24 },
- { node: { type: 'panel', id: 'wallet-view', appType: 'wallet-view' }, size: 76 },
- ],
-};
diff --git a/src/apps/officer-web/Screens/Dashboard/Wallet/index.tsx b/src/apps/officer-web/Screens/Dashboard/Wallet/index.tsx
deleted file mode 100644
index b39d800e..00000000
--- a/src/apps/officer-web/Screens/Dashboard/Wallet/index.tsx
+++ /dev/null
@@ -1 +0,0 @@
-export * from './WalletScreen';
diff --git a/src/apps/officer-web/Screens/Dashboard/index.tsx b/src/apps/officer-web/Screens/Dashboard/index.tsx
index 902d20c6..37410a2a 100644
--- a/src/apps/officer-web/Screens/Dashboard/index.tsx
+++ b/src/apps/officer-web/Screens/Dashboard/index.tsx
@@ -15,7 +15,6 @@ export * from './Calendar';
export * from './Contacts';
export * from './CommandHQ';
export * from './Gitea';
-export * from './Wallet';
export * from './SystemMonitor';
export * from './Activity';
export * from './CodeEditor';
diff --git a/src/apps/officer-web/state/usePageTitle.ts b/src/apps/officer-web/state/usePageTitle.ts
index 94c72a89..117eec9c 100644
--- a/src/apps/officer-web/state/usePageTitle.ts
+++ b/src/apps/officer-web/state/usePageTitle.ts
@@ -25,7 +25,6 @@ const RULES: TitleRule[] = [
{ match: (p) => p.startsWith('/plugins'), title: 'Marketplace' },
{ match: (p) => p.startsWith('/command-hq'), title: 'Command HQ' },
{ match: (p) => p.startsWith('/gitea'), title: 'Gitea' },
- { match: (p) => p.startsWith('/wallet'), title: 'Wallet' },
{ match: (p) => p.startsWith('/system-monitor'), title: 'System Monitor' },
{ match: (p) => p.startsWith('/qr-transfer'), title: 'QR Transfer' },
{ match: (p) => p.startsWith('/activity'), title: 'Activity' },
diff --git a/src/databases/officer_db/src/index.ts b/src/databases/officer_db/src/index.ts
index b14ea104..fe9850cc 100644
--- a/src/databases/officer_db/src/index.ts
+++ b/src/databases/officer_db/src/index.ts
@@ -47,7 +47,6 @@ export * from './user-data';
export * from './dav';
export * from './notify';
-export * from './wallet';
// `operations` is absent because it no longer exists: it held task_logs, and the Task Logs feature was
// deleted end to end on 2026-08-13 after `task-logger.ts` turned out to have no callers — a full read
diff --git a/src/databases/officer_db/src/schema.ts b/src/databases/officer_db/src/schema.ts
index 57e4d6f4..efa142d2 100644
--- a/src/databases/officer_db/src/schema.ts
+++ b/src/databases/officer_db/src/schema.ts
@@ -48,7 +48,6 @@ export * from './service-connections/schema'; // service_connections
// export * from './notify/schema'; // push_devices officer-notify
// export * from './dav/schema'; // dav_app_passwords officer-caldav
-// export * from './wallet/schema'; // wallet_wallets, _labels, _frozen_utxos, _chain_cache
// ── Plugin tables are NOT here ───────────────────────────────────────────────────────────────────
//
diff --git a/src/databases/officer_db/src/wallet/index.ts b/src/databases/officer_db/src/wallet/index.ts
deleted file mode 100644
index 53d8d137..00000000
--- a/src/databases/officer_db/src/wallet/index.ts
+++ /dev/null
@@ -1,30 +0,0 @@
-export {
- listWallets,
- getWallet,
- getActiveWallet,
- getWalletSecrets,
- getSealedSeed,
- createWallet,
- updateWallet,
- replaceSealedSeed,
- setActiveWallet,
- deleteWallet,
- getWalletLabels,
- setWalletLabel,
- getFrozenOutpoints,
- setUtxoFrozen,
- getWalletChainCache,
- saveWalletChainCache,
- recordWalletChainError,
-} from './queries';
-
-export type {
- WalletKind,
- WalletSummary,
- WalletSecrets,
- WalletLabel,
- CreateWalletParams,
- WalletChainCache,
-} from './queries';
-
-export type { WalletChainSnapshot } from './schema';
diff --git a/src/databases/officer_db/src/wallet/queries.ts b/src/databases/officer_db/src/wallet/queries.ts
deleted file mode 100644
index 76a5fbfa..00000000
--- a/src/databases/officer_db/src/wallet/queries.ts
+++ /dev/null
@@ -1,349 +0,0 @@
-import type { WalletChainSnapshot } from './schema';
-import { eq, and, desc } from 'drizzle-orm';
-import { db } from '../db';
-import { walletWallets, walletLabels, walletFrozenUtxos, walletChainCache } from './schema';
-import { encryptSecret, decryptSecret } from '../crypto';
-
-// Wallet access for the officer-wallet sidecar. Callers deal in PLAINTEXT — the at-rest layer ('wallet'
-// purpose in the secret store) is
-// applied and stripped here, so route handlers never touch crypto. See ../crypto.ts, ../schema/wallet.ts.
-//
-// Note what "plaintext" means for `seedEnvelope`: it is the passphrase-sealed envelope, which is itself
-// still ciphertext. This layer only removes the SECOND wrapping. Nothing in this file can read a mnemonic,
-// and that is intentional — only servers/sidecar/wallet/keys.ts can, and only with the owner passphrase.
-//
-// THREE return types, and the projection is what enforces the separation:
-// WalletSummary — safe to serialize to the browser. No config, no seed envelope, at all.
-// WalletSecrets — decrypted config for the sidecar's own upstream calls. Never returned by a handler.
-// SealedSeed — the sealed envelope, for keys.ts to open with the owner passphrase.
-// A bare `select()` would leak both ciphertext columns into every list response the moment someone
-// forgot to strip them, so no function here uses one.
-
-export type WalletKind = 'onchain' | 'lnd' | 'cln-rest' | 'lndhub' | 'nwc';
-
-export type WalletSummary = {
- id: number;
- name: string;
- kind: WalletKind;
- network: string;
- fingerprint: string | null;
- xpubs: Record | null;
- defaultBip: number;
- isActive: boolean;
- /** Whether this wallet holds a seed at all — i.e. whether unlock/lock apply to it. */
- hasSeed: boolean;
- createdAt: Date;
-};
-
-export type WalletSecrets = { id: number; kind: WalletKind; network: string; config: Record | null };
-
-const walletCols = {
- id: walletWallets.id,
- name: walletWallets.name,
- kind: walletWallets.kind,
- network: walletWallets.network,
- fingerprint: walletWallets.fingerprint,
- xpubs: walletWallets.xpubs,
- defaultBip: walletWallets.defaultBip,
- isActive: walletWallets.isActive,
- createdAt: walletWallets.createdAt,
- seedEnvelope: walletWallets.seedEnvelope,
-};
-
-function toSummary(row: {
- id: number;
- name: string;
- kind: string;
- network: string;
- fingerprint: string | null;
- xpubs: Record | null;
- defaultBip: number;
- isActive: boolean;
- createdAt: Date;
- seedEnvelope: string | null;
-}): WalletSummary {
- return {
- id: row.id,
- name: row.name,
- kind: row.kind as WalletKind,
- network: row.network,
- fingerprint: row.fingerprint,
- xpubs: row.xpubs,
- defaultBip: row.defaultBip,
- isActive: row.isActive,
- hasSeed: row.seedEnvelope !== null,
- createdAt: row.createdAt,
- };
-}
-
-/** Every wallet the owner has registered, active first then newest. Never includes secrets. */
-export async function listWallets(userId: number): Promise {
- const rows = await db
- .select(walletCols)
- .from(walletWallets)
- .where(eq(walletWallets.userId, userId))
- .orderBy(desc(walletWallets.isActive), desc(walletWallets.createdAt));
- return rows.map(toSummary);
-}
-
-export async function getWallet(userId: number, id: number): Promise {
- const [row] = await db
- .select(walletCols)
- .from(walletWallets)
- .where(and(eq(walletWallets.userId, userId), eq(walletWallets.id, id)));
- return row ? toSummary(row) : null;
-}
-
-export async function getActiveWallet(userId: number): Promise {
- const [row] = await db
- .select(walletCols)
- .from(walletWallets)
- .where(and(eq(walletWallets.userId, userId), eq(walletWallets.isActive, true)));
- return row ? toSummary(row) : null;
-}
-
-/** Decrypted backend connection config, for the sidecar's upstream calls. Never leaves the sidecar. */
-export async function getWalletSecrets(userId: number, id: number): Promise {
- const [row] = await db
- .select({
- id: walletWallets.id,
- kind: walletWallets.kind,
- network: walletWallets.network,
- config: walletWallets.config,
- })
- .from(walletWallets)
- .where(and(eq(walletWallets.userId, userId), eq(walletWallets.id, id)));
- if (!row) return null;
- return {
- id: row.id,
- kind: row.kind as WalletKind,
- network: row.network,
- config: row.config ? (JSON.parse(decryptSecret('wallet', row.config)) as Record) : null,
- };
-}
-
-/**
- * The passphrase-sealed seed envelope, still sealed. Returns null for wallets that hold no seed.
- * The ONLY caller should be the sidecar's unlock path.
- */
-export async function getSealedSeed(userId: number, id: number): Promise {
- const [row] = await db
- .select({ seedEnvelope: walletWallets.seedEnvelope })
- .from(walletWallets)
- .where(and(eq(walletWallets.userId, userId), eq(walletWallets.id, id)));
- if (!row?.seedEnvelope) return null;
- return decryptSecret('wallet', row.seedEnvelope);
-}
-
-export type CreateWalletParams = {
- userId: number;
- name: string;
- kind: WalletKind;
- network: string;
- /** Plaintext; encrypted here. */
- config?: Record | null;
- /** The already-sealed envelope as JSON; encrypted again here. */
- sealedSeed?: string | null;
- fingerprint?: string | null;
- xpubs?: Record | null;
- defaultBip?: number;
- makeActive?: boolean;
-};
-
-export async function createWallet(params: CreateWalletParams): Promise {
- return db.transaction(async (tx) => {
- if (params.makeActive) {
- await tx
- .update(walletWallets)
- .set({ isActive: false })
- .where(and(eq(walletWallets.userId, params.userId), eq(walletWallets.isActive, true)));
- }
- const [row] = await tx
- .insert(walletWallets)
- .values({
- userId: params.userId,
- name: params.name,
- kind: params.kind,
- network: params.network,
- config: params.config ? encryptSecret('wallet', JSON.stringify(params.config)) : null,
- seedEnvelope: params.sealedSeed ? encryptSecret('wallet', params.sealedSeed) : null,
- fingerprint: params.fingerprint ?? null,
- xpubs: params.xpubs ?? null,
- defaultBip: params.defaultBip ?? 84,
- isActive: params.makeActive ?? false,
- })
- .returning(walletCols);
- return toSummary(row!);
- });
-}
-
-/**
- * Mutable wallet metadata. CANNOT TOUCH THE SEED — see replaceSealedSeed below for why that is a
- * separate function rather than one more optional field here.
- */
-export async function updateWallet(
- userId: number,
- id: number,
- patch: { name?: string; config?: Record; defaultBip?: number },
-): Promise {
- const set: Record = { updatedAt: new Date() };
- if (patch.name !== undefined) set.name = patch.name;
- if (patch.defaultBip !== undefined) set.defaultBip = patch.defaultBip;
- if (patch.config !== undefined) set.config = encryptSecret('wallet', JSON.stringify(patch.config));
-
- const [row] = await db
- .update(walletWallets)
- .set(set)
- .where(and(eq(walletWallets.userId, userId), eq(walletWallets.id, id)))
- .returning(walletCols);
- return row ? toSummary(row) : null;
-}
-
-/**
- * Overwrite the encrypted seed. The ONLY caller is the passphrase change, which reseals the same words
- * under a new passphrase and has already proved knowledge of the old one.
- *
- * It is a function of its own, rather than a fourth field on updateWallet, because it was one: the PATCH
- * route typed its request body as `{name, defaultBip, config}` and passed the parsed object straight
- * through, and a TypeScript annotation strips nothing at runtime. Any authenticated caller could send a
- * `sealedSeed` key and replace the seed — no passphrase, no unlock, no confirmation — and since
- * encryptSecret happily encrypts nonsense, the damage only surfaced at the next unlock attempt. Keeping
- * the two apart means the next field added to that body cannot re-open it.
- */
-export async function replaceSealedSeed(userId: number, id: number, sealedSeed: string): Promise {
- await db
- .update(walletWallets)
- .set({ seedEnvelope: encryptSecret('wallet', sealedSeed), updatedAt: new Date() })
- .where(and(eq(walletWallets.userId, userId), eq(walletWallets.id, id)));
-}
-
-/** Exactly one active wallet per owner. Cleared and set in one transaction; the partial unique index is the backstop. */
-export async function setActiveWallet(userId: number, id: number): Promise {
- await db.transaction(async (tx) => {
- await tx
- .update(walletWallets)
- .set({ isActive: false })
- .where(and(eq(walletWallets.userId, userId), eq(walletWallets.isActive, true)));
- await tx
- .update(walletWallets)
- .set({ isActive: true, updatedAt: new Date() })
- .where(and(eq(walletWallets.userId, userId), eq(walletWallets.id, id)));
- });
-}
-
-export async function deleteWallet(userId: number, id: number): Promise {
- const rows = await db
- .delete(walletWallets)
- .where(and(eq(walletWallets.userId, userId), eq(walletWallets.id, id)))
- .returning({ id: walletWallets.id });
- return rows.length > 0;
-}
-
-// ── labels ───────────────────────────────────────────────────────────────────────────────────────
-
-export type WalletLabel = { kind: 'address' | 'tx'; ref: string; label: string };
-
-export async function getWalletLabels(walletId: number): Promise {
- const rows = await db
- .select({ kind: walletLabels.kind, ref: walletLabels.ref, label: walletLabels.label })
- .from(walletLabels)
- .where(eq(walletLabels.walletId, walletId));
- return rows.map((r) => ({ kind: r.kind as 'address' | 'tx', ref: r.ref, label: r.label }));
-}
-
-export async function setWalletLabel(
- walletId: number,
- kind: 'address' | 'tx',
- ref: string,
- label: string,
-): Promise {
- // An empty label is a delete — the UI clears a field rather than pressing a separate button.
- if (!label.trim()) {
- await db
- .delete(walletLabels)
- .where(and(eq(walletLabels.walletId, walletId), eq(walletLabels.kind, kind), eq(walletLabels.ref, ref)));
- return;
- }
- await db
- .insert(walletLabels)
- .values({ walletId, kind, ref, label })
- .onConflictDoUpdate({ target: [walletLabels.walletId, walletLabels.kind, walletLabels.ref], set: { label } });
-}
-
-// ── frozen UTXOs ─────────────────────────────────────────────────────────────────────────────────
-
-export async function getFrozenOutpoints(walletId: number): Promise {
- const rows = await db
- .select({ outpoint: walletFrozenUtxos.outpoint })
- .from(walletFrozenUtxos)
- .where(eq(walletFrozenUtxos.walletId, walletId));
- return rows.map((r) => r.outpoint);
-}
-
-export async function setUtxoFrozen(
- walletId: number,
- outpoint: string,
- frozen: boolean,
- reason?: string,
-): Promise {
- if (!frozen) {
- await db
- .delete(walletFrozenUtxos)
- .where(and(eq(walletFrozenUtxos.walletId, walletId), eq(walletFrozenUtxos.outpoint, outpoint)));
- return;
- }
- await db
- .insert(walletFrozenUtxos)
- .values({ walletId, outpoint, reason: reason ?? null })
- .onConflictDoNothing();
-}
-
-// ── chain cache ──────────────────────────────────────────────────────────────────────────────────
-//
-// Unlike everything above, none of this is authoritative — see the comment on the table. These three
-// functions are deliberately total: a cache read or write must never be able to fail a wallet request,
-// so the sidecar treats every one of them as best-effort.
-
-export type WalletChainCache = {
- snapshot: WalletChainSnapshot | null;
- syncedAt: Date | null;
- lastError: string | null;
- lastErrorAt: Date | null;
-};
-
-export async function getWalletChainCache(walletId: number): Promise {
- const [row] = await db
- .select({
- snapshot: walletChainCache.snapshot,
- syncedAt: walletChainCache.syncedAt,
- lastError: walletChainCache.lastError,
- lastErrorAt: walletChainCache.lastErrorAt,
- })
- .from(walletChainCache)
- .where(eq(walletChainCache.walletId, walletId));
- return row ?? null;
-}
-
-/** A successful refresh. Clears the error columns — the upstream just answered, so nothing is wrong now. */
-export async function saveWalletChainCache(walletId: number, snapshot: WalletChainSnapshot): Promise {
- const syncedAt = new Date();
- await db
- .insert(walletChainCache)
- .values({ walletId, snapshot, syncedAt, lastError: null, lastErrorAt: null })
- .onConflictDoUpdate({
- target: walletChainCache.walletId,
- set: { snapshot, syncedAt, lastError: null, lastErrorAt: null },
- });
-}
-
-/** A failed refresh. Touches only the error columns, so the last good snapshot and its age survive. */
-export async function recordWalletChainError(walletId: number, message: string): Promise {
- const lastErrorAt = new Date();
- // Bounded because this is an upstream message verbatim, and an HTML error page from a misconfigured
- // proxy would otherwise land whole in the column.
- const lastError = message.slice(0, 500);
- await db
- .insert(walletChainCache)
- .values({ walletId, snapshot: null, syncedAt: null, lastError, lastErrorAt })
- .onConflictDoUpdate({ target: walletChainCache.walletId, set: { lastError, lastErrorAt } });
-}
diff --git a/src/databases/officer_db/src/wallet/schema.ts b/src/databases/officer_db/src/wallet/schema.ts
deleted file mode 100644
index 40ebf6f6..00000000
--- a/src/databases/officer_db/src/wallet/schema.ts
+++ /dev/null
@@ -1,175 +0,0 @@
-import { pgTable, serial, integer, text, boolean, timestamp, jsonb, uniqueIndex } from 'drizzle-orm/pg-core';
-import { sql } from 'drizzle-orm';
-import { users } from '../auth/schema';
-
-// Bitcoin wallets for the officer-wallet sidecar. The owner registers one or more wallets — either a
-// self-custodial on-chain wallet whose seed lives here, or a connection to a node (LND / Core Lightning /
-// LNDHub / NWC) exactly as Zeus models them — and switches between them.
-//
-// TWO COLUMNS HOLD SPENDING AUTHORITY AND THEY ARE PROTECTED DIFFERENTLY. This asymmetry is deliberate:
-//
-// `config` — node credentials (macaroon, rune, LNDHub password, NWC URI). Encrypted at rest with
-// the 'wallet' store key via ../crypto.ts, the way offscale_servers.api_key uses its
-// own. It CANNOT be
-// passphrase-protected: background balance polling needs it without the owner present.
-//
-// `seed_envelope` — a BIP39 mnemonic that is ALREADY sealed under an owner passphrase by the sidecar
-// (see servers/sidecar/wallet/keys.ts) before it ever arrives here, and is then
-// encrypted AGAIN with the 'wallet' store key on the way into this column. Two independent
-// secrets, neither sufficient alone. A database dump does not spend; a leaked .env
-// does not spend.
-//
-// `xpubs` and `fingerprint` are stored in the CLEAR, on purpose. They are what lets the wallet show
-// balances, history and fresh receive addresses while locked — the watch-only-when-locked property. An
-// xpub leak costs privacy (an observer can enumerate the wallet's addresses), never funds.
-//
-// Every table is `wallet_`-prefixed and this file holds nothing else, so it can move into
-// src/servers/sidecar/wallet/ wholesale when sidecars own their schema. Only officer-wallet reads these.
-
-export const walletWallets = pgTable(
- 'wallet_wallets',
- {
- id: serial('id').primaryKey(),
- userId: integer('user_id')
- .notNull()
- .references(() => users.id, { onDelete: 'cascade' }),
- name: text('name').notNull(),
- // BackendKind: 'onchain' | 'lnd' | 'cln-rest' | 'lndhub' | 'nwc'. TS-only enum, no DB CHECK —
- // matches how pipeline_jobs.mode is handled elsewhere in this schema.
- kind: text('kind').notNull(),
- // BitcoinNetwork: 'bitcoin' | 'testnet' | 'signet' | 'regtest'.
- network: text('network').notNull().default('bitcoin'),
- // Backend connection config as JSON, encrypted. Null for a pure on-chain wallet, which connects to
- // nothing but the Esplora endpoint the sidecar is configured with.
- config: text('config'),
- // The passphrase-sealed SeedEnvelope, encrypted again. Null for every remote-node wallet — those
- // hold no seed, the node does.
- seedEnvelope: text('seed_envelope'),
- // BIP32 master fingerprint (8 hex chars), for PSBT construction and hardware-wallet pairing.
- fingerprint: text('fingerprint'),
- // { "44": "xpub…", "49": "ypub…", "84": "zpub…", "86": "xpub…" } — plaintext, see header.
- xpubs: jsonb('xpubs').$type>(),
- // Which derivation standard new receive addresses use. 84 (native segwit) is the default.
- defaultBip: integer('default_bip').notNull().default(84),
- isActive: boolean('is_active').notNull().default(false),
- createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
- updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
- },
- (t) => [
- uniqueIndex('uq_wallet_wallets_user_name').on(t.userId, t.name),
- // At most one active wallet per owner, enforced by the DB rather than convention — a partial unique
- // index over active rows only, mirroring uq_offscale_servers_one_active.
- uniqueIndex('uq_wallet_wallets_one_active')
- .on(t.userId)
- .where(sql`${t.isActive}`),
- ],
-);
-
-// Owner-assigned labels for addresses and transactions. Zeus keeps these client-side; here they belong to
-// the server so every client sees the same annotations.
-export const walletLabels = pgTable(
- 'wallet_labels',
- {
- id: serial('id').primaryKey(),
- walletId: integer('wallet_id')
- .notNull()
- .references(() => walletWallets.id, { onDelete: 'cascade' }),
- // 'address' | 'tx'
- kind: text('kind').notNull(),
- // The address string or txid being labelled.
- ref: text('ref').notNull(),
- label: text('label').notNull(),
- createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
- },
- (t) => [uniqueIndex('uq_wallet_labels_wallet_kind_ref').on(t.walletId, t.kind, t.ref)],
-);
-
-// Frozen UTXOs, excluded from automatic coin selection. Separate from labels because this one affects
-// what the wallet will actually spend — losing a label is cosmetic, losing a freeze spends a coin the
-// owner meant to keep back.
-//
-// NOTE the contrast with wallet_chain_cache below: this table is POLICY (the owner's decision, only
-// they can restate it) and that one is OBSERVATION (the chain's, refetchable at any time). That is why
-// only one of them can be safely truncated.
-export const walletFrozenUtxos = pgTable(
- 'wallet_frozen_utxos',
- {
- id: serial('id').primaryKey(),
- walletId: integer('wallet_id')
- .notNull()
- .references(() => walletWallets.id, { onDelete: 'cascade' }),
- // `txid:vout`
- outpoint: text('outpoint').notNull(),
- reason: text('reason'),
- createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
- },
- (t) => [uniqueIndex('uq_wallet_frozen_utxos_wallet_outpoint').on(t.walletId, t.outpoint)],
-);
-
-/**
- * The last thing the chain told us about an on-chain wallet, so a wallet screen paints real numbers
- * immediately instead of nothing while a gap-limit scan runs.
- *
- * Every field is DERIVED and rebuildable — it is recomputed from the account xpubs above on each
- * successful refresh, so this table holds no secret and nothing authoritative. Truncating it costs one
- * slow load and nothing else.
- *
- * Only the chain's own facts are stored. Addresses, scripts and pubkeys are NOT: they are pure EC
- * derivation from the xpub, cheaper to recompute on load than to persist, and re-deriving them means a
- * restored snapshot can never disagree with the wallet's actual keys.
- */
-export type WalletChainSnapshot = {
- /** Bumped when the shape below changes; a snapshot at any other version is discarded, not migrated. */
- v: 1;
- tipHeight: number;
- /** One entry per address the scan visited, keyed by its derivation coordinates. */
- addresses: {
- /** AddressType: 'p2wpkh' | 'p2tr' | 'p2sh-p2wpkh' | 'p2pkh'. */
- type: string;
- /** BIP44 chain index: 0 receive, 1 change. */
- chain: number;
- index: number;
- confirmed: number;
- unconfirmed: number;
- txCount: number;
- }[];
- utxos: {
- txid: string;
- vout: number;
- value: number;
- type: string;
- chain: number;
- index: number;
- /** Null while unconfirmed. Confirmations are recomputed against tipHeight, never stored. */
- blockHeight: number | null;
- }[];
- /** The OnchainTx shape from servers/sidecar/wallet/types.ts, restated here so this package imports nothing. */
- transactions: {
- txid: string;
- amount: number;
- feeSats: number | null;
- blockHeight: number | null;
- timestamp: number | null;
- confirmations: number;
- label: string | null;
- destAddresses: string[];
- rawHex: string | null;
- }[];
-};
-
-export const walletChainCache = pgTable('wallet_chain_cache', {
- // One row per wallet, so a refresh is a single atomic upsert with no partially-written window.
- walletId: integer('wallet_id')
- .primaryKey()
- .references(() => walletWallets.id, { onDelete: 'cascade' }),
- // Nullable: a wallet whose very first refresh failed has an error to report and no data to report it
- // against, and that row still has to exist for the UI to say why the screen is empty.
- snapshot: jsonb('snapshot').$type(),
- /** When the chain was last read successfully — the age the UI shows. Not when the row was written. */
- syncedAt: timestamp('synced_at', { withTimezone: true }),
- // Kept ALONGSIDE the last good snapshot rather than replacing it. A failure that wiped the data would
- // reproduce the exact bug this table exists to fix: an unreachable upstream rendering as a zero balance
- // instead of as a stale one.
- lastError: text('last_error'),
- lastErrorAt: timestamp('last_error_at', { withTimezone: true }),
-});
diff --git a/src/servers/api/wallet/router.ts b/src/servers/api/wallet/router.ts
deleted file mode 100644
index 17f6486d..00000000
--- a/src/servers/api/wallet/router.ts
+++ /dev/null
@@ -1,16 +0,0 @@
-import { createSidecarProxy } from '../../sidecar/create-proxy';
-
-// /api/wallet/* — auth, then forward to officer-wallet. No routes of its own, and no wallet knowledge
-// whatsoever: not a seed, not a node credential, not an xpub. The platform cannot spend and cannot read a
-// balance except by asking the sidecar.
-//
-// The unlock passphrase DOES transit this proxy — the browser has to send it somewhere — but it is
-// forwarded as an opaque body and never parsed, logged or retained. See sidecar/create-proxy.ts, which
-// deliberately performs no body inspection; that restraint matters more for this sidecar than any other.
-
-const proxy = createSidecarProxy({ name: 'wallet', prefix: '/api/wallet' });
-
-export const walletRouter = proxy.router;
-
-/** Base URL of the sidecar's HTTP server, or null if it hasn't reported in yet. */
-export const getWalletServerUrl = proxy.getHttpUrl;
diff --git a/src/servers/app-store/catalogue.ts b/src/servers/app-store/catalogue.ts
index 9d2609b2..9f2454c7 100644
--- a/src/servers/app-store/catalogue.ts
+++ b/src/servers/app-store/catalogue.ts
@@ -257,17 +257,6 @@ export const CATALOGUE: CatalogueEntry[] = [
// `[open]` This is the "two dock sources" seam. The store keeps its own catalogue while the plugin
// system builds tiles from manifests, and the self endpoint concatenates both. One when the store is
// rebuilt on the plugin system.
- {
- id: 'wallet',
- ui: { name: 'Wallet', icon: 'Bitcoin', color: '#f7931a', rootRoute: '/wallet', routes: ['/wallet'] },
- process: 'officer-wallet',
- label: 'Wallet',
- summary: 'Bitcoin and Lightning, with keys held by the sidecar alone',
- members: 'none',
- modes: ['config'],
- permission: 'wallet',
- configFields: [],
- },
{
id: 'notify',
process: 'officer-notify',
diff --git a/src/servers/hono.ts b/src/servers/hono.ts
index fcbddf18..e9cb5e1f 100644
--- a/src/servers/hono.ts
+++ b/src/servers/hono.ts
@@ -24,7 +24,6 @@ import { devProxyRouter } from './api/dev-proxy/router';
import { pluginsRouter } from './api/plugins/router';
import { isPluginPublicPath, pluginForProtocolHeaders } from './plugins/public-paths';
import { agentHandoffRouter } from './api/agent-handoff/router';
-// import { walletRouter } from './api/wallet/router';
import { terminalRouter } from './api/terminal/sidecar-server';
import { caldavRouter } from './api/dav/sidecar-server';
// import { memosRouter } from './api/memos/router';
@@ -147,7 +146,6 @@ const PROTECTED_MOUNTS: [prefix: string, router: ReturnType
['/dav', davRouter], // app-password management (the sync door is /dav, top-level)
// ['/notify', notifyRouter], // plugin — switched off 2026-08-13
// ['/photos', photosRouter], // plugin — switched off 2026-08-13
- // ['/wallet', walletRouter], // plugin — switched off 2026-08-13
['/system-monitor', systemMonitorRouter],
['/activity', activityRouter],
['/dock', dockRouter],
diff --git a/src/servers/permissions/registry.test.ts b/src/servers/permissions/registry.test.ts
index 1d9a44c1..cc78e969 100644
--- a/src/servers/permissions/registry.test.ts
+++ b/src/servers/permissions/registry.test.ts
@@ -202,7 +202,9 @@ describe('self-service routes', () => {
});
test('permissions without the field are unaffected', () => {
- expect(isSelfServiceRoute(PERMISSION_BY_KEY.get('wallet')!, 'PUT', '/api/wallet')).toBe(false);
+ // Was `wallet` until 2026-08-19, when it became `plugins/wallet/`. Any permission with no
+ // selfService field will do — this pins the absence, not the key.
+ expect(isSelfServiceRoute(PERMISSION_BY_KEY.get('terminal')!, 'PUT', '/api/terminal')).toBe(false);
});
});
@@ -242,9 +244,11 @@ describe('kinds', () => {
test('admin permissions are never grantable', () => {
const grantable = new Set(GRANTABLE_PERMISSIONS.map((c) => c.key));
- // `headscale` was here until 2026-08-15, when it left with offscale. A plugin's permissions are
- // registered at install from its manifest, so they are not in this compile-time list by design.
- for (const key of ['user-admin', 'server-admin', 'wallet']) {
+ // `headscale` was here until 2026-08-15 when it left with offscale, and `wallet` until 2026-08-19.
+ // A plugin's permissions are registered at install from its manifest, so they are not in this
+ // compile-time list by design — and a plugin's are ALWAYS `app`, which is exactly why the wallet
+ // becoming one had to be a deliberate decision rather than a side effect.
+ for (const key of ['user-admin', 'server-admin']) {
expect(PERMISSION_BY_KEY.get(key)?.kind).toBe('admin');
expect(grantable.has(key)).toBe(false);
}
diff --git a/src/servers/permissions/registry.ts b/src/servers/permissions/registry.ts
index 5f62d114..5aa0319f 100644
--- a/src/servers/permissions/registry.ts
+++ b/src/servers/permissions/registry.ts
@@ -381,15 +381,6 @@ const CORE_REGISTRY: Permission[] = [
// `headscale` lived here until 2026-08-15, when it left with the rest of offscale. A plugin declares
// its own permissions in its manifest and they are registered at install — see plugins/mount.ts. The
// platform no longer knows this permission exists, which is the entire point.
- {
- key: 'wallet',
- label: 'Wallet',
- description: "The server owner's bitcoin",
- kind: 'admin',
- // api: ['/wallet'], // plugin — switched off 2026-08-13
- api: [],
- routes: ['/wallet'],
- },
];
// ── Derived lookups ───────────────────────────────────────────────────────────────────────────────
diff --git a/src/servers/plugins/marketplace.ts b/src/servers/plugins/marketplace.ts
index 322c9f8f..07fb2cad 100644
--- a/src/servers/plugins/marketplace.ts
+++ b/src/servers/plugins/marketplace.ts
@@ -212,6 +212,28 @@ const BUNDLED: CatalogueEntry[] = [
// shows rather than the daemon behind it. See its PLUGIN.md for what that cost.
has: { api: true, schema: true, sidecar: true, web: true },
},
+ {
+ appName: 'bitcoin-wallet',
+ publisher: 'officerdev',
+ version: '1.0.0',
+ platform: '>=1.0.0',
+ label: 'Bitcoin Wallet',
+ summary: 'A self-custodial bitcoin wallet — keys sealed on the server, never on a device',
+ color: '#f7931a',
+ icon: 'Bitcoin',
+ source: 'https://gitea.officer.dev/plugins/bitcoin-wallet.git',
+ permissions: [
+ {
+ key: 'bitcoin-wallet',
+ label: 'Bitcoin Wallet',
+ description: "Bitcoin wallet — each account gets its own, sealed under that account's own passphrase",
+ },
+ ],
+ // Grantable, unlike the `kind: 'admin'` it had in the core registry — every query is scoped by
+ // user_id, so granting it gives an account its OWN wallet rather than access to anyone else's.
+ // See its PLUGIN.md; this was a deliberate decision, not a side effect of extraction.
+ has: { api: true, schema: true, sidecar: true, web: true },
+ },
{
appName: 'vault',
publisher: 'officerdev',
diff --git a/src/servers/sidecar/wallet/aezeed/aez.ts b/src/servers/sidecar/wallet/aezeed/aez.ts
deleted file mode 100644
index 85105fda..00000000
--- a/src/servers/sidecar/wallet/aezeed/aez.ts
+++ /dev/null
@@ -1,380 +0,0 @@
-import { blake2b } from '@noble/hashes/blake2.js';
-
-// AEZ v5 — the wide-block cipher LND's aezeed uses to encrypt a cipher seed.
-//
-// SCOPE, deliberately narrow. This is a DECRYPT-ONLY implementation of the SHORT-INPUT path:
-//
-// - No encrypt. Officer never mints aezeed seeds — it only imports ones LND/Zeus already created.
-// A new Officer wallet gets a BIP39 mnemonic, which is the portable format.
-// - No aezCore. An aezeed ciphertext is a FIXED 23 bytes (33 total, minus the 1-byte version, the
-// 5-byte salt and the 4-byte CRC), and AEZ dispatches on length: anything under 32 bytes takes the
-// `aezTiny` Feistel path. `aezCore` is unreachable here, so shipping it would mean carrying ~120
-// lines of untested cipher in a seed-recovery path. `decrypt` throws rather than guess.
-// - No aezPRF. Only reached when the ciphertext is exactly `tau` bytes (empty plaintext).
-//
-// Every line below is exercised by the tests. That is the point of the narrowness — a subtle bug in
-// unreachable crypto is a bug nobody finds until it eats someone's wallet.
-//
-// Ported from the reference implementation (Yawning/aez, as used by lnd/aezeed). Faithful to the point
-// of preserving its integer-truncation quirks; where the original relied on a JavaScript accident, the
-// comment says so.
-
-const BLOCK_SIZE = 16;
-const EXTRACTED_KEY_SIZE = 48;
-const ZERO = new Uint8Array(BLOCK_SIZE);
-
-// ── AES round tables ─────────────────────────────────────────────────────────────────────────────
-//
-// AEZ is built on reduced-round AES (4 and 10 rounds, always with MixColumns and no key schedule —
-// the "keys" are just the extracted key material). The four 256-entry T-tables are pure functions of
-// the AES S-box: TE0[i] = [2·S[i], S[i], S[i], 3·S[i]] big-endian, and TE1..TE3 are TE0 rotated right
-// by 8, 16 and 24 bits. Deriving them costs microseconds once and removes 1024 hand-copied constants
-// from a file where a single wrong digit silently produces the wrong wallet.
-
-// prettier-ignore
-const SBOX_HEX =
- '637c777bf26b6fc53001672bfed7ab76ca82c97dfa5947f0add4a2af9ca472c0' +
- 'b7fd9326363ff7cc34a5e5f171d8311504c723c31896059a071280e2eb27b275' +
- '09832c1a1b6e5aa0523bd6b329e32f8453d100ed20fcb15b6acbbe394a4c58cf' +
- 'd0efaafb434d338545f9027f503c9fa851a3408f929d38f5bcb6da2110fff3d2' +
- 'cd0c13ec5f974417c4a77e3d645d197360814fdc222a908846eeb814de5e0bdb' +
- 'e0323a0a4906245cc2d3ac629195e479e7c8376d8dd54ea96c56f4ea657aae08' +
- 'ba78252e1ca6b4c6e8dd741f4bbd8b8a703eb5664803f60e613557b986c11d9e' +
- 'e1f8981169d98e949b1e87e9ce5528df8ca1890dbfe6426841992d0fb054bb16';
-
-const SBOX = Uint8Array.from(SBOX_HEX.match(/../g)!, (h) => parseInt(h, 16));
-
-/** GF(2^8) doubling — the `xtime` of the AES spec. */
-const xtime = (b: number): number => ((b << 1) ^ (b & 0x80 ? 0x1b : 0)) & 0xff;
-
-function buildTables(): [Uint32Array, Uint32Array, Uint32Array, Uint32Array] {
- const te0 = new Uint32Array(256);
- for (let i = 0; i < 256; i++) {
- const s = SBOX[i]!;
- te0[i] = ((xtime(s) << 24) | (s << 16) | (s << 8) | (xtime(s) ^ s)) >>> 0;
- }
- const ror8 = (x: number): number => ((x >>> 8) | (x << 24)) >>> 0;
- const te1 = te0.map(ror8);
- const te2 = te1.map(ror8);
- const te3 = te2.map(ror8);
- return [te0, te1, te2, te3];
-}
-
-const [TE0, TE1, TE2, TE3] = buildTables();
-
-// ── block helpers ────────────────────────────────────────────────────────────────────────────────
-
-const block = (size = BLOCK_SIZE): Uint8Array => new Uint8Array(size);
-
-function xor16(a: Uint8Array, b: Uint8Array, dst: Uint8Array): void {
- for (let i = 0; i < BLOCK_SIZE; i++) dst[i] = a[i]! ^ b[i]!;
-}
-
-function xor4x16(a: Uint8Array, b: Uint8Array, c: Uint8Array, d: Uint8Array, dst: Uint8Array): void {
- for (let i = 0; i < BLOCK_SIZE; i++) dst[i] = a[i]! ^ b[i]! ^ c[i]! ^ d[i]!;
-}
-
-/** Multiply a block by x in GF(2^128), in place. */
-function doubleBlock(p: Uint8Array): void {
- const carry = p[0]!;
- for (let i = 0; i < 15; i++) p[i] = ((p[i]! << 1) | (p[i + 1]! >> 7)) & 0xff;
- p[15] = ((p[15]! << 1) ^ (carry >> 7 ? 135 : 0)) & 0xff;
-}
-
-/** Multiply a block by the integer `x` in GF(2^128) — repeated doubling, accumulating odd bits. */
-function multBlock(x: number, src: Uint8Array, dst: Uint8Array): void {
- const t = block();
- const r = block();
- t.set(src);
- let n = x;
- while (n !== 0) {
- if (n & 1) xor16(r, t, r);
- doubleBlock(t);
- n >>= 1;
- }
- dst.set(r);
-}
-
-const readU32BE = (b: Uint8Array, off: number): number =>
- ((b[off]! << 24) | (b[off + 1]! << 16) | (b[off + 2]! << 8) | b[off + 3]!) >>> 0;
-
-function writeU32BE(b: Uint8Array, off: number, v: number): void {
- b[off] = (v >>> 24) & 0xff;
- b[off + 1] = (v >>> 16) & 0xff;
- b[off + 2] = (v >>> 8) & 0xff;
- b[off + 3] = v & 0xff;
-}
-
-// ── reduced-round AES ────────────────────────────────────────────────────────────────────────────
-
-type AesKeys = { aes4: Uint32Array; aes10: Uint32Array };
-
-/** Lay the 48-byte extracted key out into the fixed round-key schedules AEZ prescribes. */
-function aesKeys(extracted: Uint8Array): AesKeys {
- const k = new Uint32Array(12);
- for (let i = 0; i < 12; i++) k[i] = readU32BE(extracted, 4 * i);
-
- const aes10 = new Uint32Array(40);
- aes10.set(k, 0);
- aes10.set(k, 12);
- aes10.set(k, 24);
- aes10.set(k.subarray(0, 4), 36);
-
- const aes4 = new Uint32Array(16);
- aes4.set(k.subarray(4, 8), 0);
- aes4.set(k.subarray(0, 4), 4);
- aes4.set(k.subarray(8, 12), 8);
-
- return { aes4, aes10 };
-}
-
-/** AES rounds with MixColumns applied on every round, including the last (as AEZ specifies). */
-function rounds(keys: Uint32Array, count: number, b: Uint8Array): void {
- let s0 = readU32BE(b, 0);
- let s1 = readU32BE(b, 4);
- let s2 = readU32BE(b, 8);
- let s3 = readU32BE(b, 12);
-
- for (let r = 0; r < count; r++) {
- const o = r * 4;
- const t0 =
- TE0[(s0 >>> 24) & 0xff]! ^ TE1[(s1 >>> 16) & 0xff]! ^ TE2[(s2 >>> 8) & 0xff]! ^ TE3[s3 & 0xff]! ^ keys[o]!;
- const t1 =
- TE0[(s1 >>> 24) & 0xff]! ^ TE1[(s2 >>> 16) & 0xff]! ^ TE2[(s3 >>> 8) & 0xff]! ^ TE3[s0 & 0xff]! ^ keys[o + 1]!;
- const t2 =
- TE0[(s2 >>> 24) & 0xff]! ^ TE1[(s3 >>> 16) & 0xff]! ^ TE2[(s0 >>> 8) & 0xff]! ^ TE3[s1 & 0xff]! ^ keys[o + 2]!;
- const t3 =
- TE0[(s3 >>> 24) & 0xff]! ^ TE1[(s0 >>> 16) & 0xff]! ^ TE2[(s1 >>> 8) & 0xff]! ^ TE3[s2 & 0xff]! ^ keys[o + 3]!;
- s0 = t0 >>> 0;
- s1 = t1 >>> 0;
- s2 = t2 >>> 0;
- s3 = t3 >>> 0;
- }
-
- writeU32BE(b, 0, s0);
- writeU32BE(b, 4, s1);
- writeU32BE(b, 8, s2);
- writeU32BE(b, 12, s3);
-}
-
-function aes4(k: AesKeys, j: Uint8Array, i: Uint8Array, l: Uint8Array, src: Uint8Array, dst: Uint8Array): void {
- xor4x16(j, i, l, src, dst);
- rounds(k.aes4, 4, dst);
-}
-
-function aes10(k: AesKeys, l: Uint8Array, src: Uint8Array, dst: Uint8Array): void {
- xor16(src, l, dst);
- rounds(k.aes10, 10, dst);
-}
-
-// ── AEZ state ────────────────────────────────────────────────────────────────────────────────────
-
-type AezState = { I: Uint8Array[]; J: Uint8Array[]; L: Uint8Array[]; aes: AesKeys };
-
-/** AEZ tolerates any key length by hashing it to 48 bytes; a 48-byte key is used verbatim. */
-function extractKey(key: Uint8Array): Uint8Array {
- return key.length === EXTRACTED_KEY_SIZE ? key : blake2b(key, { dkLen: EXTRACTED_KEY_SIZE });
-}
-
-function init(key: Uint8Array): AezState {
- const ext = extractKey(key);
- const I = [block(), block()];
- const J = [block(), block(), block()];
- const L = Array.from({ length: 8 }, () => block());
-
- I[0]!.set(ext.subarray(0, 16));
- multBlock(2, I[0]!, I[1]!);
-
- J[0]!.set(ext.subarray(16, 32));
- multBlock(2, J[0]!, J[1]!);
- multBlock(2, J[1]!, J[2]!);
-
- // L[0] is deliberately left as the zero block — the reference never assigns it.
- L[1]!.set(ext.subarray(32, 48));
- multBlock(2, L[1]!, L[2]!);
- xor16(L[2]!, L[1]!, L[3]!);
- multBlock(2, L[2]!, L[4]!);
- xor16(L[4]!, L[1]!, L[5]!);
- multBlock(2, L[3]!, L[6]!);
- xor16(L[6]!, L[1]!, L[7]!);
-
- return { I, J, L, aes: aesKeys(ext) };
-}
-
-/** The AXU hash binding the tag length, the nonce and each associated-data string into `delta`. */
-function aezHash(st: AezState, nonce: Uint8Array | null, ad: Uint8Array[], tauBits: number): Uint8Array {
- const buf = block();
- const sum = block();
- const I = block();
- const J = block();
-
- writeU32BE(buf, 12, tauBits >>> 0);
- xor16(st.J[0]!, st.J[1]!, J);
- aes4(st.aes, J, st.I[1]!, st.L[1]!, buf, sum);
-
- const nonceEmpty = !nonce || nonce.length === 0;
- let n = nonce ?? new Uint8Array(0);
- let nBytes = n.length;
- I.set(st.I[1]!);
- for (let i = 1; nBytes >= BLOCK_SIZE; i++, nBytes -= BLOCK_SIZE) {
- aes4(st.aes, st.J[2]!, I, st.L[i % 8]!, n.subarray(0, BLOCK_SIZE), buf);
- xor16(sum, buf, sum);
- n = n.subarray(BLOCK_SIZE);
- if (i % 8 === 0) doubleBlock(I);
- }
- if (nBytes > 0 || nonceEmpty) {
- buf.fill(0);
- if (!nonceEmpty) buf.set(n.subarray(0, nBytes));
- buf[nBytes] = 0x80;
- aes4(st.aes, st.J[2]!, st.I[0]!, st.L[0]!, buf, buf);
- xor16(sum, buf, sum);
- }
-
- ad.forEach((entry, k) => {
- let p = entry ?? new Uint8Array(0);
- const adEmpty = p.length === 0;
- let bytes = p.length;
- I.set(st.I[1]!);
- multBlock(5 + k, st.J[0]!, J);
- for (let i = 1; bytes >= BLOCK_SIZE; i++, bytes -= BLOCK_SIZE) {
- aes4(st.aes, J, I, st.L[i % 8]!, p.subarray(0, BLOCK_SIZE), buf);
- xor16(sum, buf, sum);
- p = p.subarray(BLOCK_SIZE);
- if (i % 8 === 0) doubleBlock(I);
- }
- if (bytes > 0 || adEmpty) {
- buf.fill(0);
- if (!adEmpty) buf.set(p.subarray(0, bytes));
- buf[bytes] = 0x80;
- aes4(st.aes, J, st.I[0]!, st.L[0]!, buf, buf);
- xor16(sum, buf, sum);
- }
- });
-
- return sum;
-}
-
-/**
- * The short-input (< 32 byte) balanced Feistel network. `d` is 0 to encipher, 1 to decipher — the only
- * difference is which end of the round counter it starts from.
- */
-function aezTiny(st: AezState, delta: Uint8Array, input: Uint8Array, d: 0 | 1, dst: Uint8Array): void {
- const inBytes = input.length;
- const buf = block(2 * BLOCK_SIZE);
- const L = block();
- const R = block();
- const tmp = block();
- let mask = 0x00;
- let pad = 0x80;
-
- // Integer halves. The reference indexes with `inBytes/2` and leans on truncation; spelling the two
- // halves out makes the odd-length case readable instead of accidental.
- const half = inBytes >> 1;
- const halfUp = (inBytes + 1) >> 1;
-
- let i = 7;
- let roundCount: number;
- if (inBytes === 1) roundCount = 24;
- else if (inBytes === 2) roundCount = 16;
- else if (inBytes < 16) roundCount = 10;
- else {
- i = 6;
- roundCount = 8;
- }
-
- L.set(input.subarray(0, halfUp));
- R.set(input.subarray(half, half + halfUp));
-
- if (inBytes & 1) {
- // Odd length: the two halves overlap by a nibble, so shift R left by 4 bits and switch to
- // nibble-granular padding.
- for (let k = 0; k < half; k++) R[k] = ((R[k]! << 4) | (R[k + 1]! >> 4)) & 0xff;
- R[half] = (R[half]! << 4) & 0xff;
- pad = 0x08;
- mask = 0xf0;
- }
-
- let j: number;
- let step: number;
- if (d !== 0) {
- if (inBytes < 16) {
- buf.set(input.subarray(0, BLOCK_SIZE));
- buf[0] = buf[0]! | 0x80;
- xor16(delta, buf, buf);
- aes4(st.aes, ZERO, st.I[1]!, st.L[3]!, buf, tmp);
- L[0] = L[0]! ^ (tmp[0]! & 0x80);
- }
- j = roundCount - 1;
- step = -1;
- } else {
- j = 0;
- step = 1;
- }
-
- for (let k = 0; k < roundCount / 2; k++, j += step * 2) {
- buf.fill(0, 0, BLOCK_SIZE);
- buf.set(R.subarray(0, halfUp));
- buf[half] = (buf[half]! & mask) | pad;
- xor16(buf, delta, buf);
- buf[15] = buf[15]! ^ (j & 0xff);
- aes4(st.aes, ZERO, st.I[1]!, st.L[i]!, buf, tmp);
- xor16(L, tmp, L);
-
- buf.fill(0, 0, BLOCK_SIZE);
- buf.set(L.subarray(0, halfUp));
- buf[half] = (buf[half]! & mask) | pad;
- xor16(buf, delta, buf);
- buf[15] = buf[15]! ^ ((j + step) & 0xff);
- aes4(st.aes, ZERO, st.I[1]!, st.L[i]!, buf, tmp);
- xor16(R, tmp, R);
- }
-
- buf.set(R.subarray(0, half), 0);
- buf.set(L.subarray(0, halfUp), half);
- if (inBytes & 1) {
- for (let k = inBytes - 1; k > half; k--) buf[k] = ((buf[k]! >> 4) | (buf[k - 1]! << 4)) & 0xff;
- buf[half] = (L[0]! >> 4) | (R[half]! & 0xf0);
- }
-
- dst.set(buf.subarray(0, inBytes));
-
- if (inBytes < 16 && d === 0) {
- buf.fill(0, inBytes, BLOCK_SIZE);
- buf[0] = buf[0]! | 0x80;
- xor16(delta, buf, buf);
- aes4(st.aes, ZERO, st.I[1]!, st.L[3]!, buf, tmp);
- dst[0] = dst[0]! ^ (tmp[0]! & 0x80);
- }
-}
-
-/**
- * AEZ decrypt-and-verify. Returns the plaintext, or `null` when the `tau`-byte authenticator does not
- * check out — which is the signal that the key (and therefore the seed passphrase) is wrong.
- *
- * Throws for inputs outside the aezeed envelope rather than silently taking an untested path; see the
- * scope note at the top of this file.
- */
-export function aezDecrypt(
- key: Uint8Array,
- nonce: Uint8Array | null,
- ad: Uint8Array[],
- tau: number,
- ciphertext: Uint8Array,
-): Uint8Array | null {
- if (ciphertext.length >= 32 || ciphertext.length <= tau) {
- throw new Error(`aez: unsupported ciphertext length ${ciphertext.length} (decrypt is short-input only)`);
- }
-
- const st = init(key);
- const delta = aezHash(st, nonce, ad, tau * 8);
- const x = new Uint8Array(ciphertext.length);
- aezTiny(st, delta, ciphertext, 1, x);
-
- // Constant-time-ish: fold every authenticator byte before deciding, so the comparison does not
- // short-circuit on the first mismatch.
- let sum = 0;
- for (let i = 0; i < tau; i++) sum |= x[ciphertext.length - tau + i]!;
- if (sum !== 0) return null;
-
- return x.slice(0, ciphertext.length - tau);
-}
diff --git a/src/servers/sidecar/wallet/aezeed/aezeed.test.ts b/src/servers/sidecar/wallet/aezeed/aezeed.test.ts
deleted file mode 100644
index e27976a7..00000000
--- a/src/servers/sidecar/wallet/aezeed/aezeed.test.ts
+++ /dev/null
@@ -1,124 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { generateMnemonic } from '@scure/bip39';
-import { wordlist } from '@scure/bip39/wordlists/english';
-import {
- AezeedError,
- birthdayToDate,
- decipherMnemonic,
- isAezeedPhrase,
- mnemonicToCipherSeedBytes,
-} from './cipher-seed';
-
-// Fixtures were produced by the `aezeed` npm package (an INDEPENDENT implementation, different author
-// and codebase, itself matching lnd/aezeed). Deterministic entropy and salt make them reproducible, so
-// agreement here is genuine cross-implementation evidence rather than this port agreeing with itself.
-//
-// entropy 000102...0f, salt 0102030405, internalVersion 0, birthday 5593
-const ENTROPY_HEX = '000102030405060708090a0b0c0d0e0f';
-const DEFAULT_PW =
- 'about wisdom spawn awkward catalog large teach salad large phrase drip caught coral snake chief mountain manage gym dog alcohol doctor valley evolve citizen';
-const CUSTOM_PW =
- 'above shop hair museum laugh diamond win skin habit inspire hero box category crime boss black nest useless dog alcohol doctor radar urban split';
-const CUSTOM_PASSPHRASE = 'correct horse battery staple';
-// entropy ffee...00, salt a1b2c3d4e5, internalVersion 1, birthday 0
-const BIRTHDAY_ZERO =
- 'abstract three say vacant about cable tent neck other jeans certain accident arrest market couch front inflict laptop hole marble exact okay owner number';
-
-const split = (phrase: string): string[] => phrase.split(' ');
-const hex = (b: Uint8Array): string => Buffer.from(b).toString('hex');
-
-describe('isAezeedPhrase', () => {
- test('accepts aezeed cipher seeds', () => {
- expect(isAezeedPhrase(split(DEFAULT_PW))).toBe(true);
- expect(isAezeedPhrase(split(CUSTOM_PW))).toBe(true);
- expect(isAezeedPhrase(split(BIRTHDAY_ZERO))).toBe(true);
- });
-
- test('is passphrase-independent — structure only, no scrypt', () => {
- // Both fixtures hold the SAME entropy under different passphrases. Detection must not care.
- expect(isAezeedPhrase(split(DEFAULT_PW))).toBe(isAezeedPhrase(split(CUSTOM_PW)));
- });
-
- test('rejects genuine BIP39 mnemonics', () => {
- // The whole point: a 24-word BIP39 phrase is also 33 bytes, so only the CRC separates them.
- for (let i = 0; i < 25; i++) {
- expect(isAezeedPhrase(split(generateMnemonic(wordlist, 256)))).toBe(false);
- }
- });
-
- test('rejects wrong lengths and non-wordlist words', () => {
- expect(isAezeedPhrase(split(DEFAULT_PW).slice(0, 12))).toBe(false);
- expect(isAezeedPhrase([...split(DEFAULT_PW).slice(0, 23), 'notaword'])).toBe(false);
- expect(isAezeedPhrase([])).toBe(false);
- });
-
- test('rejects a single transposed word', () => {
- const words = split(DEFAULT_PW);
- const swapped = [...words];
- swapped[3] = words[4]!;
- swapped[4] = words[3]!;
- expect(isAezeedPhrase(swapped)).toBe(false);
- });
-});
-
-describe('decipherMnemonic', () => {
- test('recovers entropy under the default passphrase', async () => {
- const seed = await decipherMnemonic(split(DEFAULT_PW));
- expect(hex(seed.entropy)).toBe(ENTROPY_HEX);
- expect(seed.entropy).toHaveLength(16);
- expect(seed.internalVersion).toBe(0);
- expect(seed.birthday).toBe(5593);
- });
-
- test('recovers the same entropy under a custom passphrase', async () => {
- const seed = await decipherMnemonic(split(CUSTOM_PW), CUSTOM_PASSPHRASE);
- expect(hex(seed.entropy)).toBe(ENTROPY_HEX);
- });
-
- test('decodes internalVersion 1 and a zero birthday', async () => {
- const seed = await decipherMnemonic(split(BIRTHDAY_ZERO));
- expect(hex(seed.entropy)).toBe('ffeeddccbbaa99887766554433221100');
- expect(seed.internalVersion).toBe(1);
- expect(seed.birthday).toBe(0);
- });
-
- test('a wrong passphrase fails the AEZ tag rather than returning junk', async () => {
- // This is the property that makes the whole port safe: a bad key CANNOT yield plausible-looking
- // entropy, so we can never silently derive the wrong wallet.
- const err = await decipherMnemonic(split(CUSTOM_PW), 'not the passphrase').catch((e) => e);
- expect(err).toBeInstanceOf(AezeedError);
- expect(err.code).toBe('BAD_PASSPHRASE');
- });
-
- test('the default passphrase is not silently accepted for a custom-passphrase seed', async () => {
- const err = await decipherMnemonic(split(CUSTOM_PW)).catch((e) => e);
- expect(err.code).toBe('BAD_PASSPHRASE');
- });
-
- test('a corrupted checksum is caught before scrypt', async () => {
- const bytes = mnemonicToCipherSeedBytes(split(DEFAULT_PW))!;
- bytes[32] = bytes[32]! ^ 0xff;
- const { decipherCipherSeed } = await import('./cipher-seed');
- const err = await decipherCipherSeed(bytes, 'aezeed').catch((e) => e);
- expect(err.code).toBe('BAD_CHECKSUM');
- });
-
- test('rejects a non-aezeed phrase', async () => {
- const err = await decipherMnemonic(split(generateMnemonic(wordlist, 256))).catch((e) => e);
- expect(err).toBeInstanceOf(AezeedError);
- });
-});
-
-describe('framing', () => {
- test('24 words pack into exactly 33 bytes', () => {
- const bytes = mnemonicToCipherSeedBytes(split(DEFAULT_PW));
- expect(bytes).toHaveLength(33);
- expect(bytes![0]).toBe(0); // aezeed version
- });
-
- test('birthday maps to a real date', () => {
- // 5593 days after the genesis block.
- expect(birthdayToDate(5593).toISOString().slice(0, 10)).toBe('2024-04-27');
- expect(birthdayToDate(0).toISOString().slice(0, 10)).toBe('2009-01-03');
- });
-});
diff --git a/src/servers/sidecar/wallet/aezeed/cipher-seed.ts b/src/servers/sidecar/wallet/aezeed/cipher-seed.ts
deleted file mode 100644
index ccca58a3..00000000
--- a/src/servers/sidecar/wallet/aezeed/cipher-seed.ts
+++ /dev/null
@@ -1,202 +0,0 @@
-import { scrypt as scryptCb } from 'node:crypto';
-import { promisify } from 'node:util';
-import { wordlist } from '@scure/bip39/wordlists/english';
-import { aezDecrypt } from './aez';
-
-// LND's aezeed cipher seed — the format Zeus's embedded LND node hands out as a "backup phrase".
-//
-// It is NOT BIP39, and that is the entire problem this module exists to solve. An aezeed phrase is 24
-// words drawn from the very same BIP39 English wordlist, so it is visually indistinguishable from a
-// BIP39 mnemonic, but the bits underneath are a different structure entirely:
-//
-// byte 0 version (0)
-// bytes 1..24 ciphertext (19-byte plaintext + 4-byte AEZ authenticator)
-// bytes 24..29 salt (scrypt salt for the passphrase)
-// bytes 29..33 CRC32-Castagnoli over bytes 0..29
-// ─────
-// 33 bytes = 24 words x 11 bits
-//
-// A BIP39 24-word phrase is also 33 bytes, but its last 8 bits are a SHA-256 checksum. So an aezeed
-// phrase fails BIP39 validation every single time, with an error that reads exactly like "you mistyped
-// a word" — which is unfixable advice, because nothing is mistyped.
-//
-// The deciphered plaintext is:
-//
-// byte 0 internal version
-// bytes 1..3 birthday (days since the Bitcoin genesis block, big-endian uint16)
-// bytes 3..19 entropy (16 bytes)
-//
-// That 16-byte entropy is used DIRECTLY as the BIP32 master seed — LND does not run it through BIP39's
-// PBKDF2. This is why an aezeed cannot be converted into an equivalent BIP39 phrase: doing so would
-// change the derived keys and produce an empty wallet at different addresses.
-
-const scrypt = promisify(scryptCb) as (
- password: string | Buffer,
- salt: Buffer,
- keylen: number,
- options: { N: number; r: number; p: number; maxmem: number },
-) => Promise;
-
-export const CIPHER_SEED_VERSION = 0;
-export const ENCIPHERED_SIZE = 33;
-export const ENTROPY_SIZE = 16;
-const PLAINTEXT_SIZE = 19;
-const SALT_SIZE = 5;
-const CHECKSUM_SIZE = 4;
-const CIPHERTEXT_EXPANSION = 4;
-const SALT_OFFSET = ENCIPHERED_SIZE - CHECKSUM_SIZE - SALT_SIZE; // 24
-const CHECKSUM_OFFSET = ENCIPHERED_SIZE - CHECKSUM_SIZE; // 29
-
-/**
- * LND's default when the user declines to set a seed passphrase. Not a secret — it is a literal
- * constant in lnd/aezeed, and every Zeus wallet created without an explicit passphrase uses it.
- */
-export const DEFAULT_AEZEED_PASSPHRASE = 'aezeed';
-
-// scrypt parameters for version 0, straight from lnd/aezeed/params.go.
-const SCRYPT_N = 32768;
-const SCRYPT_R = 8;
-const SCRYPT_P = 1;
-const KEY_LEN = 32;
-// 128 * N * r is ~33.5 MB here, over Node's 32 MB default, which fails with a bare MEMORY_LIMIT_EXCEEDED.
-const SCRYPT_MAXMEM = 64 * 1024 * 1024;
-
-/** LND counts a seed's birthday in days from this instant. */
-const BITCOIN_GENESIS = Date.UTC(2009, 0, 3, 18, 15, 5);
-const ONE_DAY_MS = 86_400_000;
-
-// ── CRC32-Castagnoli ─────────────────────────────────────────────────────────────────────────────
-//
-// Castagnoli (0x82F63B78), NOT the far more common IEEE polynomial. Getting this wrong makes every
-// valid seed look corrupt.
-
-const CRC32C_TABLE = Uint32Array.from({ length: 256 }, (_, n) => {
- let c = n;
- for (let k = 0; k < 8; k++) c = c & 1 ? 0x82f63b78 ^ (c >>> 1) : c >>> 1;
- return c >>> 0;
-});
-
-function crc32c(bytes: Uint8Array): number {
- let c = 0xffffffff;
- for (const b of bytes) c = CRC32C_TABLE[(c ^ b) & 0xff]! ^ (c >>> 8);
- return (c ^ 0xffffffff) >>> 0;
-}
-
-// ── mnemonic <-> bytes ───────────────────────────────────────────────────────────────────────────
-
-const WORD_INDEX = new Map(wordlist.map((w, i) => [w, i]));
-
-/**
- * Pack 24 words into the 33 raw bytes, 11 bits each. Returns null when any word is outside the
- * wordlist or the count is wrong — i.e. when this cannot be an aezeed phrase at all.
- */
-export function mnemonicToCipherSeedBytes(words: string[]): Uint8Array | null {
- if (words.length !== 24) return null;
-
- const bits: number[] = [];
- for (const word of words) {
- const index = WORD_INDEX.get(word);
- if (index === undefined) return null;
- for (let b = 10; b >= 0; b--) bits.push((index >> b) & 1);
- }
-
- const bytes = new Uint8Array(ENCIPHERED_SIZE);
- for (let i = 0; i < ENCIPHERED_SIZE; i++) {
- let v = 0;
- for (let b = 0; b < 8; b++) v = (v << 1) | bits[i * 8 + b]!;
- bytes[i] = v;
- }
- return bytes;
-}
-
-/**
- * Whether a phrase is an aezeed cipher seed. Cheap, offline, and decisive: it checks the version byte
- * and the CRC32C, so it never touches scrypt or the passphrase. Safe to run on every phrase the owner
- * types, and safe to ship to a client — it reveals nothing and needs no secret.
- */
-export function isAezeedPhrase(words: string[]): boolean {
- const bytes = mnemonicToCipherSeedBytes(words);
- if (!bytes) return false;
- if (bytes[0] !== CIPHER_SEED_VERSION) return false;
- return crc32c(bytes.subarray(0, CHECKSUM_OFFSET)) === readU32BE(bytes, CHECKSUM_OFFSET);
-}
-
-const readU32BE = (b: Uint8Array, off: number): number =>
- ((b[off]! << 24) | (b[off + 1]! << 16) | (b[off + 2]! << 8) | b[off + 3]!) >>> 0;
-
-// ── decipher ─────────────────────────────────────────────────────────────────────────────────────
-
-export type CipherSeed = {
- internalVersion: number;
- /** Days since the Bitcoin genesis block. */
- birthday: number;
- /** The BIP32 master seed. 16 bytes. Caller is responsible for zeroing it. */
- entropy: Uint8Array;
-};
-
-export class AezeedError extends Error {
- constructor(
- message: string,
- readonly code: 'BAD_VERSION' | 'BAD_CHECKSUM' | 'BAD_PASSPHRASE' | 'BAD_LENGTH',
- ) {
- super(message);
- this.name = 'AezeedError';
- }
-}
-
-/** Convert a birthday (days since genesis) to a date — useful as a rescan floor. */
-export function birthdayToDate(birthday: number): Date {
- return new Date(BITCOIN_GENESIS + birthday * ONE_DAY_MS);
-}
-
-/**
- * Decipher a 33-byte aezeed. Throws AezeedError with a code the caller can turn into a useful message —
- * in particular BAD_PASSPHRASE, which is the difference between "your words are wrong" (they are not)
- * and "this seed has a passphrase set and we need it".
- */
-export async function decipherCipherSeed(bytes: Uint8Array, passphrase: string): Promise {
- if (bytes.length !== ENCIPHERED_SIZE) {
- throw new AezeedError(`aezeed must be ${ENCIPHERED_SIZE} bytes, got ${bytes.length}`, 'BAD_LENGTH');
- }
- if (bytes[0] !== CIPHER_SEED_VERSION) {
- throw new AezeedError(`unsupported aezeed version ${bytes[0]}`, 'BAD_VERSION');
- }
- if (crc32c(bytes.subarray(0, CHECKSUM_OFFSET)) !== readU32BE(bytes, CHECKSUM_OFFSET)) {
- throw new AezeedError('aezeed checksum mismatch', 'BAD_CHECKSUM');
- }
-
- const salt = Buffer.from(bytes.subarray(SALT_OFFSET, SALT_OFFSET + SALT_SIZE));
- const key = await scrypt(passphrase.normalize('NFKD'), salt, KEY_LEN, {
- N: SCRYPT_N,
- r: SCRYPT_R,
- p: SCRYPT_P,
- maxmem: SCRYPT_MAXMEM,
- });
-
- // Associated data is the version byte followed by the salt, so a seed cannot be replayed under a
- // different version or salt.
- const ad = new Uint8Array(1 + SALT_SIZE);
- ad[0] = CIPHER_SEED_VERSION;
- ad.set(salt, 1);
-
- try {
- const plaintext = aezDecrypt(key, null, [ad], CIPHERTEXT_EXPANSION, bytes.subarray(1, SALT_OFFSET));
- if (!plaintext || plaintext.length !== PLAINTEXT_SIZE) {
- throw new AezeedError('incorrect seed passphrase', 'BAD_PASSPHRASE');
- }
- return {
- internalVersion: plaintext[0]!,
- birthday: (plaintext[1]! << 8) | plaintext[2]!,
- entropy: plaintext.slice(3, 3 + ENTROPY_SIZE),
- };
- } finally {
- key.fill(0);
- }
-}
-
-/** Convenience: words straight to a deciphered seed. */
-export async function decipherMnemonic(words: string[], passphrase = DEFAULT_AEZEED_PASSPHRASE): Promise {
- const bytes = mnemonicToCipherSeedBytes(words);
- if (!bytes) throw new AezeedError('not a 24-word phrase from the BIP39 wordlist', 'BAD_LENGTH');
- return decipherCipherSeed(bytes, passphrase);
-}
diff --git a/src/servers/sidecar/wallet/backends/base.ts b/src/servers/sidecar/wallet/backends/base.ts
deleted file mode 100644
index 1f5bd79f..00000000
--- a/src/servers/sidecar/wallet/backends/base.ts
+++ /dev/null
@@ -1,194 +0,0 @@
-import {
- BackendError,
- type Balances,
- type BackendKind,
- type Capability,
- type Channel,
- type CreateInvoiceRequest,
- type DecodedInvoice,
- type FeeEstimates,
- type Invoice,
- type KeysendRequest,
- type NewAddressRequest,
- type NodeInfo,
- type OnchainTx,
- type PayInvoiceRequest,
- type Payment,
- type Peer,
- type SendCoinsRequest,
- type SendCoinsResult,
- type SignMessageResult,
- type Utxo,
- type VerifyMessageResult,
- type WalletBackend,
- type AddressType,
-} from '../types';
-
-/**
- * Shared backend base. Declares its capability set once and turns every unimplemented method into a
- * clean 501 — the counterpart to Zeus's `BackendUtils.call()` returning `false` for a missing method
- * (utils/BackendUtils.ts:56-58), but loud instead of silent.
- */
-export abstract class BaseBackend implements WalletBackend {
- abstract readonly kind: BackendKind;
- protected abstract readonly capabilities: ReadonlySet;
-
- supports(cap: Capability): boolean {
- return this.capabilities.has(cap);
- }
-
- protected notSupported(op: string): never {
- throw new BackendError(`${this.kind} does not support ${op}`, 501, 'NOT_SUPPORTED');
- }
-
- abstract getInfo(): Promise;
- abstract getBalances(): Promise;
-
- getTransactions(_opts?: { limit?: number }): Promise {
- return this.notSupported('on-chain transaction history');
- }
- getNewAddress(_req?: NewAddressRequest): Promise<{ address: string; type: AddressType }> {
- return this.notSupported('on-chain receive');
- }
- getUtxos(): Promise {
- return this.notSupported('coin control');
- }
- estimateFees(): Promise {
- return this.notSupported('fee estimation');
- }
- sendCoins(_req: SendCoinsRequest): Promise {
- return this.notSupported('on-chain send');
- }
-
- getInvoices(_opts?: { limit?: number }): Promise {
- return this.notSupported('invoice listing');
- }
- createInvoice(_req: CreateInvoiceRequest): Promise {
- return this.notSupported('lightning receive');
- }
- lookupInvoice(_paymentHash: string): Promise {
- return this.notSupported('invoice lookup');
- }
- decodeInvoice(_bolt11: string): Promise {
- return this.notSupported('invoice decoding');
- }
- getPayments(_opts?: { limit?: number }): Promise {
- return this.notSupported('payment history');
- }
- payInvoice(_req: PayInvoiceRequest): Promise {
- return this.notSupported('lightning send');
- }
- sendKeysend(_req: KeysendRequest): Promise {
- return this.notSupported('keysend');
- }
-
- getChannels(): Promise {
- return this.notSupported('channels');
- }
- getPeers(): Promise {
- return this.notSupported('peers');
- }
-
- signMessage(_message: string): Promise {
- return this.notSupported('message signing');
- }
- verifyMessage(_message: string, _signature: string): Promise {
- return this.notSupported('message verification');
- }
-}
-
-// ── HTTP ─────────────────────────────────────────────────────────────────────────────────────────
-
-// Zeus reaches its REST backends through `react-native-blob-util` with a `trusty: true` flag, which
-// disables TLS verification wholesale so a node with a self-signed cert is reachable (backends/LND.ts).
-// Bun's fetch takes an equivalent per-request `tls` option, so no extra HTTP client is needed.
-//
-// Verification is only relaxed when the owner explicitly opts in for a specific node, and it is a real
-// trade: it buys reachability for a node with a self-signed cert at the cost of MITM protection on that
-// connection. Acceptable over loopback or a tailnet, not over the open internet — which is why it is a
-// per-wallet flag the owner sets deliberately, never a default.
-type BunFetchInit = RequestInit & { tls?: { rejectUnauthorized?: boolean } };
-
-export type HttpOptions = {
- method?: string;
- path: string;
- base: string;
- headers?: Record;
- body?: unknown;
- query?: Record;
- allowSelfSigned?: boolean;
- timeoutMs?: number;
- /** Return the raw Response instead of parsed JSON. */
- raw?: boolean;
-};
-
-const DEFAULT_TIMEOUT_MS = 30_000;
-
-/** The single door every REST backend goes through. Normalizes errors into BackendError. */
-export async function httpJson(opts: HttpOptions): Promise {
- const base = opts.base.replace(/\/+$/, '');
- const url = new URL(`${base}${opts.path.startsWith('/') ? opts.path : `/${opts.path}`}`);
- for (const [k, v] of Object.entries(opts.query ?? {})) {
- if (v !== undefined) url.searchParams.set(k, String(v));
- }
-
- const headers: Record = { Accept: 'application/json', ...opts.headers };
- let body: string | undefined;
- if (opts.body !== undefined) {
- body = JSON.stringify(opts.body);
- headers['Content-Type'] ??= 'application/json';
- }
-
- const controller = new AbortController();
- const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-
- const init: BunFetchInit = {
- method: opts.method ?? 'GET',
- headers,
- body,
- signal: controller.signal,
- };
- if (opts.allowSelfSigned) init.tls = { rejectUnauthorized: false };
-
- let res: Response;
- try {
- res = await fetch(url, init);
- } catch (err) {
- const msg = controller.signal.aborted ? `timed out after ${opts.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms` : String(err);
- throw new BackendError(`request to ${url.host} failed: ${msg}`, 502, 'UPSTREAM_UNREACHABLE');
- } finally {
- clearTimeout(timer);
- }
-
- if (opts.raw) return res as unknown as T;
-
- const text = await res.text();
- let parsed: unknown = null;
- if (text) {
- try {
- parsed = JSON.parse(text);
- } catch {
- if (!res.ok) throw new BackendError(`upstream ${res.status}: ${text.slice(0, 200)}`, res.status);
- throw new BackendError(`upstream returned non-JSON: ${text.slice(0, 200)}`, 502);
- }
- }
-
- if (!res.ok) {
- // LND puts {error, code}; CLN puts {message}; LNDHub puts {error, message}. Try all three.
- const p = parsed as { error?: string; message?: string; code?: number } | null;
- const msg = p?.error ?? p?.message ?? `upstream returned ${res.status}`;
- throw new BackendError(msg, res.status, p?.code != null ? String(p.code) : undefined);
- }
-
- return parsed as T;
-}
-
-/** Hex → base64. LND's REST API takes bytes fields base64-encoded; callers hold hex. */
-export function hexToBase64(hex: string): string {
- return Buffer.from(hex, 'hex').toString('base64');
-}
-
-/** Base64 → hex, for reading LND's bytes fields back out. */
-export function base64ToHex(b64: string): string {
- return Buffer.from(b64, 'base64').toString('hex');
-}
diff --git a/src/servers/sidecar/wallet/backends/clnrest.ts b/src/servers/sidecar/wallet/backends/clnrest.ts
deleted file mode 100644
index 8eabd636..00000000
--- a/src/servers/sidecar/wallet/backends/clnrest.ts
+++ /dev/null
@@ -1,1012 +0,0 @@
-// Core Lightning REST backend — ported from Zeus's `backends/CLNRest.ts` together with
-// `backends/CoreLightningRequestHandler.ts`, which holds all of the actual shaping logic (balances,
-// channels, peers, chain transactions) that CLNRest.ts delegates to.
-//
-// CLNRest is POST-only: every command is `POST /v1/` with a JSON body (`{}` when the command
-// takes no arguments) and a `Rune: ` header. There are no GET endpoints and no path parameters.
-//
-// UNITS. CLN reports millisatoshis two ways depending on the endpoint and on the node's deprecated-API
-// setting: a bare JSON number (`1234`) or a suffixed string (`"1234msat"`). Zeus assumes the number form
-// everywhere — `opArray[i].amount_msat / 1000` in CoreLightningRequestHandler — which yields NaN against a
-// node still emitting the string form. `parseMsat` below accepts both.
-//
-// INTENTIONAL BEHAVIOURAL DIFFERENCES FROM ZEUS
-//
-// 1. No Tor, no in-flight call de-duplication, no `trusty:`-style blanket TLS bypass — see the same three
-// notes in `lnd.ts`. Self-signed certs are accepted only when the owner opts in per node.
-// 2. `payLightningInvoice` no longer sends `amount_msat: Number(data.amt && data.amt * 1000)`. When `amt`
-// is undefined that expression is `0`, and CLN rejects an explicit zero amount on an invoice that
-// already carries one. We omit the field unless an amount was actually requested.
-// 3. `feeLimitMsat` is honoured via `pay`'s `maxfee`. Zeus declares `supportsCustomFeeLimit = () => false`
-// for CLN and only ever sends `maxfeepercent`; both forms are supported here.
-// 4. `signMessage` returns the **zbase** signature. CLN's signmessage returns `signature` (hex),
-// `recid` and `zbase`, but its own `checkmessage` only accepts zbase — returning the hex form would
-// produce a signature this backend could not verify.
-// 5. Channel states are reported rather than dropped. Zeus's `listPeerChannels` filters ONCHAIN, CLOSED
-// and CHANNELD_AWAITING_LOCKIN out of the list entirely because its flat model has nowhere to put
-// them; `Channel.status` does, so awaiting-lockin surfaces as 'pending-open'.
-// 6. Chain-transaction confirmations are `tip - height + 1`. Zeus computes `tip - height`, which reports
-// a transaction in the tip block as having zero confirmations.
-// 7. `getInvoices` recovers each invoice's creation time by reading the 35-bit timestamp straight out of
-// the BOLT11 data part. Zeus does the same thing via `Bolt11Utils.decode`; listinvoices genuinely has
-// no creation-time column, only `paid_at` and `expires_at`.
-// 8. `customPreimages` is NOT declared, matching Zeus's `supportsCustomPreimages = () => false`, even
-// though CLN's `invoice` command does accept a `preimage` argument.
-// 9. `accounts` is NOT declared — `supportsAccounts = () => false` in Zeus. CLN has no account concept.
-// 10. `NewAddressRequest.peek` is ignored: `newaddr` always derives a fresh address.
-// 11. `SendCoinsRequest.rbf` and `.label` are ignored — `withdraw` exposes neither.
-// 12. BOLT12 offer management (`listoffers`, `offer`, `disableoffer`, `fetchinvoice`, `invoicerequest`,
-// `sendinvoice`) and the askrene/getroutes/sendpay routing surface are not ported: `WalletBackend`
-// has no methods for them. The `offers` capability is still declared, since the node supports them.
-//
-// DEPENDENCIES ON CLN PLUGINS. `getInvoices`, `getPayments` and `getTransactions` go through the **sql**
-// plugin, exactly as Zeus does; `getTransactions` additionally reads the **bookkeeper**'s
-// `bkpr_accountevents` table. Both plugins ship with CLN and are enabled by default, but a node that has
-// disabled either will fail those three calls and no others.
-
-import * as bitcoin from 'bitcoinjs-lib';
-import {
- BackendError,
- type AddressType,
- type Balances,
- type BackendKind,
- type BitcoinNetwork,
- type Capability,
- type Channel,
- type CreateInvoiceRequest,
- type DecodedInvoice,
- type FeeEstimates,
- type Invoice,
- type InvoiceState,
- type KeysendRequest,
- type NewAddressRequest,
- type NodeInfo,
- type OnchainTx,
- type PayInvoiceRequest,
- type Payment,
- type PaymentStatus,
- type Peer,
- type SendCoinsRequest,
- type SendCoinsResult,
- type SignMessageResult,
- type Utxo,
- type VerifyMessageResult,
-} from '../types';
-import { BaseBackend, httpJson } from './base';
-
-// ── upstream wire types ──────────────────────────────────────────────────────────────────────────
-//
-// Field names are lightningd's own, verbatim. `Msat` marks every field that may arrive as either a number
-// or a `"…msat"` string — see the UNITS note above.
-
-type Msat = number | string;
-
-type ClnGetInfo = {
- id?: string;
- alias?: string;
- version?: string;
- blockheight?: number;
- network?: string;
- fees_collected_msat?: Msat;
- warning_bitcoind_sync?: string;
- warning_lightningd_sync?: string;
-};
-
-type ClnFundsOutput = {
- txid?: string;
- output?: number;
- amount_msat?: Msat;
- scriptpubkey?: string;
- address?: string;
- status?: string;
- blockheight?: number;
- reserved?: boolean;
-};
-
-type ClnFundsChannel = {
- peer_id?: string;
- our_amount_msat?: Msat;
- amount_msat?: Msat;
- connected?: boolean;
- state?: string;
-};
-
-type ClnListFunds = { outputs?: ClnFundsOutput[]; channels?: ClnFundsChannel[] };
-
-type ClnPeerChannel = {
- peer_id?: string;
- peer_connected?: boolean;
- state?: string;
- channel_id?: string;
- short_channel_id?: string;
- funding_txid?: string;
- funding_outnum?: number;
- total_msat?: Msat;
- to_us_msat?: Msat;
- private?: boolean;
-};
-
-type ClnPeer = { id?: string; connected?: boolean; num_channels?: number; netaddr?: string[] };
-
-type ClnNode = { nodeid?: string; alias?: string };
-
-type ClnTxOutput = { index?: number; amount_msat?: Msat; scriptPubKey?: string };
-
-type ClnTransaction = {
- hash?: string;
- rawtx?: string;
- blockheight?: number;
- txindex?: number;
- outputs?: ClnTxOutput[];
-};
-
-/** The sql plugin answers with positional rows in the order the SELECT names its columns. */
-type ClnSqlResult = { rows?: SqlCell[][] };
-
-type ClnFeerateEstimate = { blockcount?: number; feerate?: number; smoothed_feerate?: number };
-
-type ClnFeerates = {
- perkb?: {
- min_acceptable?: number;
- max_acceptable?: number;
- floor?: number;
- opening?: number;
- estimates?: ClnFeerateEstimate[];
- };
-};
-
-type ClnNewAddr = { bech32?: string; p2tr?: string };
-
-type ClnWithdraw = { tx?: string; txid?: string; psbt?: string };
-
-type ClnInvoiceResponse = {
- bolt11?: string;
- payment_hash?: string;
- payment_secret?: string;
- expires_at?: number;
- created_index?: number;
-};
-
-type ClnListInvoice = {
- label?: string;
- bolt11?: string;
- bolt12?: string;
- payment_hash?: string;
- amount_msat?: Msat;
- status?: string;
- amount_received_msat?: Msat;
- paid_at?: number;
- payment_preimage?: string;
- description?: string;
- expires_at?: number;
-};
-
-type ClnDecoded = {
- type?: string;
- valid?: boolean;
- created_at?: number;
- expiry?: number;
- payee?: string;
- amount_msat?: Msat;
- payment_hash?: string;
- description?: string;
- min_final_cltv_expiry?: number;
- features?: string;
- routes?: unknown[];
-};
-
-type ClnPayResult = {
- payment_preimage?: string;
- payment_hash?: string;
- created_at?: number;
- parts?: number;
- amount_msat?: Msat;
- amount_sent_msat?: Msat;
- status?: string;
- destination?: string;
-};
-
-type ClnSignMessage = { signature?: string; recid?: number; zbase?: string };
-
-type ClnCheckMessage = { verified?: boolean; pubkey?: string };
-
-// ── helpers ──────────────────────────────────────────────────────────────────────────────────────
-
-/** Accepts `1234`, `"1234"` and `"1234msat"`; returns a decimal msat string, never a number. */
-function parseMsat(value: Msat | null | undefined): string | null {
- if (value == null) return null;
- if (typeof value === 'number') return Number.isFinite(value) ? Math.round(value).toString() : null;
- const match = /^(\d+)\s*(msat)?$/i.exec(value.trim());
- return match?.[1] ?? null;
-}
-
-/** msat (either form) → whole satoshis, truncated the way CLN's own sat-denominated views truncate. */
-function msatToSats(value: Msat | null | undefined): number {
- const msat = parseMsat(value);
- return msat == null ? 0 : Math.floor(Number(msat) / 1000);
-}
-
-function toNumber(value: unknown): number {
- const n = Number(value);
- return Number.isFinite(n) ? n : 0;
-}
-
-/**
- * Caller-supplied msat decimal string → the JSON number CLN's API expects.
- *
- * CLN takes amounts as JSON numbers, so a msat value above 2^53 would silently lose precision on the
- * way out — a request to pay 1 msat more than MAX_SAFE_INTEGER would be rounded rather than rejected.
- * The amounts involved are absurd (2^53 msat ≈ 90,000 BTC) but the failure is silent and the input is
- * caller-controlled, so it is checked rather than assumed. Mirrors toMsatNumber() in nwc.ts.
- */
-function msatToApiNumber(msat: string, field: string): number {
- let value: bigint;
- try {
- value = BigInt(msat);
- } catch {
- throw new BackendError(`${field} must be a decimal msat string, got "${msat}"`, 400, 'BAD_AMOUNT');
- }
- if (value < 0n || value > BigInt(Number.MAX_SAFE_INTEGER)) {
- throw new BackendError(`${field}=${msat}msat is out of range`, 400, 'BAD_AMOUNT');
- }
- return Number(value);
-}
-
-function toNetwork(network: string | undefined): BitcoinNetwork {
- switch (network) {
- case 'testnet':
- case 'testnet4':
- return 'testnet';
- case 'signet':
- return 'signet';
- case 'regtest':
- return 'regtest';
- default:
- return 'bitcoin';
- }
-}
-
-const BECH32_CHARSET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
-
-/**
- * BOLT11 puts a 35-bit creation timestamp in the first seven characters of the data part, immediately
- * after the separator (the LAST '1' in the string, per the spec — the human-readable part may contain
- * one). Reading it directly avoids pulling in a full bech32 decoder just for `listinvoices`, which has no
- * creation-time column at all.
- */
-function bolt11Timestamp(bolt11: string | null | undefined): number | null {
- if (!bolt11) return null;
- const invoice = bolt11.toLowerCase();
- const separator = invoice.lastIndexOf('1');
- if (separator < 0) return null;
- const data = invoice.slice(separator + 1);
- if (data.length < 7) return null;
-
- let timestamp = 0;
- for (let i = 0; i < 7; i++) {
- const char = data[i];
- // indexOf('') would answer 0, so the empty case has to be rejected before the lookup.
- if (!char) return null;
- const value = BECH32_CHARSET.indexOf(char);
- if (value < 0) return null;
- timestamp = timestamp * 32 + value;
- }
- return timestamp;
-}
-
-// ── sql plugin cells ─────────────────────────────────────────────────────────────────────────────
-//
-// The sql plugin returns positional rows, so every read is an index into an array of loosely-typed cells.
-// These three readers keep that in one place instead of scattering casts through the mappers.
-
-type SqlCell = string | number | boolean | null | undefined;
-
-function cellStr(cell: SqlCell): string | null {
- return typeof cell === 'string' && cell.length > 0 ? cell : null;
-}
-
-function cellNum(cell: SqlCell): number | null {
- if (cell == null || typeof cell === 'boolean') return null;
- const n = Number(cell);
- return Number.isFinite(n) ? n : null;
-}
-
-function cellMsat(cell: SqlCell): Msat | undefined {
- return typeof cell === 'number' || typeof cell === 'string' ? cell : undefined;
-}
-
-/**
- * The sql plugin takes a whole SQL string, not bound parameters, so `limit` is the one caller-supplied
- * value that reaches it. Force it to a bounded integer before it is ever interpolated.
- */
-function clampLimit(limit: number | undefined, fallback: number): number {
- const n = Math.floor(Number(limit));
- if (!Number.isFinite(n) || n <= 0) return fallback;
- return Math.min(n, 5000);
-}
-
-/**
- * Address type by prefix. `listfunds` reports the address but not its kind, and the prefix is an exact
- * discriminator across every network CLN runs on, so no lookup is needed.
- */
-function addressType(address: string | undefined): AddressType | null {
- if (!address) return null;
- const addr = address.toLowerCase();
- const bech32Prefix = /^(bc1|tb1|bcrt1)/.exec(addr);
- if (bech32Prefix) return addr[bech32Prefix[0].length] === 'p' ? 'p2tr' : 'p2wpkh';
- if (addr.startsWith('3') || addr.startsWith('2')) return 'p2sh-p2wpkh';
- if (addr.startsWith('1') || addr.startsWith('m') || addr.startsWith('n')) return 'p2pkh';
- return null;
-}
-
-/** bitcoinjs has no signet parameter set; signet reuses testnet's version bytes and 'tb' hrp. */
-function bitcoinjsNetwork(network: BitcoinNetwork): bitcoin.Network {
- switch (network) {
- case 'regtest':
- return bitcoin.networks.regtest;
- case 'testnet':
- case 'signet':
- return bitcoin.networks.testnet;
- default:
- return bitcoin.networks.bitcoin;
- }
-}
-
-function toPaymentStatus(status: string | undefined): PaymentStatus {
- switch (status) {
- case 'complete':
- return 'succeeded';
- case 'failed':
- return 'failed';
- default:
- return 'pending';
- }
-}
-
-/**
- * CLN's channel state machine → the coarse status in `Channel`. Zeus never models this; it filters the
- * terminal states out and treats everything else as open.
- */
-function toChannelStatus(state: string | undefined): string {
- switch (state) {
- case 'CHANNELD_NORMAL':
- return 'open';
- case 'OPENINGD':
- case 'CHANNELD_AWAITING_LOCKIN':
- case 'DUALOPEND_OPEN_INIT':
- case 'DUALOPEND_AWAITING_LOCKIN':
- case 'DUALOPEND_OPEN_COMMITTED':
- case 'DUALOPEND_OPEN_COMMIT_READY':
- return 'pending-open';
- case 'CHANNELD_SHUTTING_DOWN':
- case 'CLOSINGD_SIGEXCHANGE':
- case 'CLOSINGD_COMPLETE':
- return 'pending-close';
- case 'AWAITING_UNILATERAL':
- case 'FUNDING_SPEND_SEEN':
- case 'ONCHAIN':
- return 'force-closing';
- case 'CLOSED':
- return 'closed';
- default:
- return state ?? 'open';
- }
-}
-
-/** Column indices for the two SQL projections below — positional rows are otherwise unreadable. */
-const INVOICE_COL = {
- label: 0,
- bolt11: 1,
- bolt12: 2,
- paymentHash: 3,
- amountMsat: 4,
- status: 5,
- amountReceivedMsat: 6,
- paidAt: 7,
- preimage: 8,
- description: 9,
- expiresAt: 10,
-} as const;
-
-const PAYMENT_COL = {
- paymentHash: 0,
- groupId: 1,
- status: 2,
- destination: 3,
- createdAt: 4,
- description: 5,
- bolt11: 6,
- bolt12: 7,
- amountSentMsat: 8,
- amountMsat: 9,
- preimage: 10,
-} as const;
-
-const ACCOUNT_EVENT_COL = {
- account: 0,
- tag: 1,
- outpoint: 2,
- creditMsat: 3,
- debitMsat: 4,
- timestamp: 5,
- blockheight: 6,
-} as const;
-
-/** TLV record carrying a free-text note alongside a keysend payment. */
-const KEYSEND_MESSAGE_RECORD = '34349334';
-
-export type ClnRestConfig = {
- /** Full base URL including scheme and port, e.g. `https://192.168.1.5:3010`. */
- url: string;
- /** The rune authorising this connection. Sent as the `Rune` header. */
- rune: string;
- allowSelfSigned?: boolean;
-};
-
-// ── the backend ──────────────────────────────────────────────────────────────────────────────────
-
-export class ClnRestBackend extends BaseBackend {
- readonly kind: BackendKind = 'cln-rest';
-
- protected readonly capabilities: ReadonlySet = new Set([
- 'onchainReceive',
- 'onchainSend',
- 'coinControl', // Zeus: supportsCoinControl / supportsChannelCoinControl
- 'sweep', // `withdraw … satoshi: "all"`
- 'lightningReceive',
- 'lightningSend',
- 'keysend',
- 'offers', // Zeus: supportsOffers / supportsListingOffers / supportsBolt12Address
- 'channels',
- 'peers',
- 'routing',
- 'signMessage',
- // Deliberately absent: psbt, bumpFee (supportsBumpFee = false), accounts (supportsAccounts = false),
- // customPreimages (supportsCustomPreimages = false).
- ]);
-
- constructor(private readonly config: ClnRestConfig) {
- super();
- }
-
- // ── transport ──────────────────────────────────────────────────────────────────────────────────
-
- /** Every CLNRest command is a POST with a JSON body; commands without arguments still need `{}`. */
- private call(command: string, body: Record = {}, timeoutMs?: number): Promise {
- return httpJson({
- base: this.config.url,
- path: `/v1/${command}`,
- method: 'POST',
- body,
- headers: { Rune: this.config.rune },
- allowSelfSigned: this.config.allowSelfSigned,
- timeoutMs,
- });
- }
-
- private sql(query: string): Promise {
- return this.call('sql', { query });
- }
-
- /**
- * Resolve node aliases in one pass. Zeus issues a `listnodes` per channel and per peer inside
- * `Promise.all` and lets a single failure reject the whole list; we de-duplicate by pubkey and swallow
- * individual lookups, because a missing alias must not cost you the channel list.
- */
- private async resolveAliases(pubkeys: string[]): Promise> {
- const unique = [...new Set(pubkeys.filter(Boolean))];
- const entries = await Promise.all(
- unique.map(async (id): Promise<[string, string] | null> => {
- try {
- const res = await this.call<{ nodes?: ClnNode[] }>('listnodes', { id });
- const alias = res.nodes?.[0]?.alias;
- return alias ? [id, alias] : null;
- } catch {
- return null;
- }
- }),
- );
- return new Map(entries.filter((entry): entry is [string, string] => entry !== null));
- }
-
- // ── node / balances ────────────────────────────────────────────────────────────────────────────
-
- override async getInfo(): Promise {
- const info = await this.call('getinfo');
- return {
- kind: this.kind,
- pubkey: info.id ?? null,
- alias: info.alias ?? null,
- version: info.version ?? null,
- network: toNetwork(info.network),
- blockHeight: info.blockheight ?? null,
- // CLN reports lag by ADDING a warning field; their absence is the only "synced" signal there is.
- synced: !info.warning_bitcoind_sync && !info.warning_lightningd_sync,
- };
- }
-
- override async getBalances(): Promise {
- // One listfunds call answers both halves — Zeus makes two, one via getBalance and one via
- // getOffchainBalance, each re-fetching the identical payload.
- const funds = await this.call('listfunds');
-
- let onchainConfirmed = 0;
- let onchainUnconfirmed = 0;
- for (const output of funds.outputs ?? []) {
- // 'spent' and 'immature' outputs are also listed; neither is spendable balance.
- if (output.status === 'confirmed') onchainConfirmed += msatToSats(output.amount_msat);
- else if (output.status === 'unconfirmed') onchainUnconfirmed += msatToSats(output.amount_msat);
- }
-
- let lightningBalance = 0;
- let lightningInbound = 0;
- for (const channel of funds.channels ?? []) {
- // Zeus counts only connected CHANNELD_NORMAL channels towards the spendable balance; funds in
- // disconnected or still-opening channels are real but not usable right now.
- if (channel.state !== 'CHANNELD_NORMAL' || channel.connected !== true) continue;
- const ours = Number(parseMsat(channel.our_amount_msat) ?? '0');
- const total = Number(parseMsat(channel.amount_msat) ?? '0');
- lightningBalance += Math.floor(ours / 1000);
- lightningInbound += Math.floor((total - ours) / 1000);
- }
-
- // Core Lightning reserves coins itself; Officer freezing is the route's overlay, so 0 here.
- return { onchainConfirmed, onchainUnconfirmed, onchainFrozen: 0, lightningBalance, lightningInbound };
- }
-
- // ── on-chain ───────────────────────────────────────────────────────────────────────────────────
-
- /**
- * Port of `CoreLightningRequestHandler.getChainTransactions`.
- *
- * CLN has no single "wallet transactions" command. `listtransactions` knows every transaction the node
- * has seen but not what it MEANT; the bookkeeper's `bkpr_accountevents` knows the meaning (deposit to
- * the wallet vs. payment out to an external account) but is keyed by outpoint. So the two are joined on
- * txid, and any transaction that is really a channel open or close is excluded — otherwise a channel
- * funding would show up as an ordinary withdrawal.
- */
- override async getTransactions(opts?: { limit?: number }): Promise {
- const limit = clampLimit(opts?.limit, 150);
- const query =
- 'SELECT account, tag, outpoint, credit_msat, debit_msat, timestamp, blockheight ' +
- "FROM bkpr_accountevents WHERE (tag='deposit' OR tag='to_them' OR tag='channel_open' " +
- `OR tag='channel_close') ORDER BY timestamp DESC LIMIT ${limit}`;
-
- // Zeus uses allSettled here so a missing bookkeeper or sql plugin degrades instead of failing; only
- // getinfo is load-bearing (it supplies the chain tip and the network for address decoding).
- const [eventsResult, txsResult, infoResult] = await Promise.allSettled([
- this.sql(query),
- this.call<{ transactions?: ClnTransaction[] }>('listtransactions'),
- this.call('getinfo'),
- ]);
-
- if (infoResult.status !== 'fulfilled') return [];
- const tip = infoResult.value.blockheight ?? 0;
- const network = bitcoinjsNetwork(toNetwork(infoResult.value.network));
-
- const rows = eventsResult.status === 'fulfilled' ? (eventsResult.value.rows ?? []) : [];
- const transactions = txsResult.status === 'fulfilled' ? (txsResult.value.transactions ?? []) : [];
-
- const txidOf = (row: SqlCell[]): string | null => {
- const outpoint = cellStr(row[ACCOUNT_EVENT_COL.outpoint]);
- return outpoint ? (outpoint.split(':')[0] ?? null) : null;
- };
-
- const deposits = rows.filter((row) => row[ACCOUNT_EVENT_COL.tag] === 'deposit');
- const walletDeposits = deposits.filter((row) => row[ACCOUNT_EVENT_COL.account] === 'wallet');
- const externalDeposits = deposits.filter((row) => row[ACCOUNT_EVENT_COL.account] === 'external');
-
- const isChannelChange = (txid: string): boolean =>
- rows.some(
- (row) =>
- txidOf(row) === txid &&
- (row[ACCOUNT_EVENT_COL.tag] === 'channel_open' || row[ACCOUNT_EVENT_COL.tag] === 'channel_close'),
- );
-
- const result: OnchainTx[] = [];
- for (const tx of transactions) {
- const txid = tx.hash ?? '';
- if (!txid || isChannelChange(txid)) continue;
-
- // A deposit booked against the 'external' account is money leaving us; against 'wallet', arriving.
- const outgoing = externalDeposits.find((row) => txidOf(row) === txid);
- const incoming = outgoing ? undefined : walletDeposits.find((row) => txidOf(row) === txid);
- const row = outgoing ?? incoming;
- if (!row) continue;
-
- const credit = Number(parseMsat(cellMsat(row[ACCOUNT_EVENT_COL.creditMsat])) ?? '0');
- const amount = Math.floor((outgoing ? -Math.abs(credit) : credit) / 1000);
- const height = cellNum(row[ACCOUNT_EVENT_COL.blockheight]) || null;
-
- const destAddresses: string[] = [];
- for (const output of tx.outputs ?? []) {
- if (!output.scriptPubKey) continue;
- try {
- destAddresses.push(bitcoin.address.fromOutputScript(Buffer.from(output.scriptPubKey, 'hex'), network));
- } catch {
- // Non-standard or unrecognised script — CLN reports it, we simply have no address for it.
- }
- }
-
- result.push({
- txid,
- amount,
- // bkpr records the fee as its own accountevent tag, not on the deposit row.
- feeSats: null,
- blockHeight: height,
- timestamp: cellNum(row[ACCOUNT_EVENT_COL.timestamp]) || null,
- confirmations: height ? Math.max(0, tip - height + 1) : 0,
- label: null,
- destAddresses,
- rawHex: tx.rawtx ?? null,
- });
- }
-
- return result.sort((a, b) => (b.timestamp ?? 0) - (a.timestamp ?? 0));
- }
-
- override async getNewAddress(req?: NewAddressRequest): Promise<{ address: string; type: AddressType }> {
- const type: AddressType = req?.type ?? 'p2wpkh';
- // CLN dropped p2sh-segwit issuance in v23.05 and has never issued legacy p2pkh
- // (Zeus: supportsNestedSegWit = () => false).
- const addresstype = type === 'p2wpkh' ? 'bech32' : type === 'p2tr' ? 'p2tr' : null;
- if (!addresstype) {
- throw new BackendError(`core lightning cannot derive a ${type} address`, 400, 'UNSUPPORTED_ADDRESS_TYPE');
- }
-
- const res = await this.call('newaddr', { addresstype });
- // newaddr keys the response by the address type it produced, not by a generic `address` field.
- const address = addresstype === 'p2tr' ? res.p2tr : res.bech32;
- if (!address) throw new BackendError('core lightning returned no address', 502);
- return { address, type };
- }
-
- override async getUtxos(): Promise {
- const [funds, info] = await Promise.all([this.call('listfunds'), this.call('getinfo')]);
- const tip = info.blockheight ?? 0;
-
- return (funds.outputs ?? [])
- .filter((output) => output.status === 'confirmed' || output.status === 'unconfirmed')
- .map((output) => ({
- txid: output.txid ?? '',
- vout: output.output ?? 0,
- amountSats: msatToSats(output.amount_msat),
- address: output.address ?? '',
- addressType: addressType(output.address),
- confirmations: output.blockheight ? Math.max(0, tip - output.blockheight + 1) : 0,
- // CLN's listfunds does not expose the derivation path for its own outputs.
- derivationPath: null,
- // `reserved` is CLN's exclusion flag: an output held for an in-flight psbt or channel open.
- frozen: output.reserved === true,
- }));
- }
-
- override async estimateFees(): Promise {
- const res = await this.call('feerates', { style: 'perkb' });
- const perkb = res.perkb;
- const estimates = perkb?.estimates ?? [];
-
- // perkb is sat per 1000 vbytes; the interface wants sat/vB, and never below the 1 sat/vB relay floor.
- const toVbyte = (perKb: number | undefined): number => Math.max(1, Math.ceil(toNumber(perKb) / 1000));
-
- /** Cheapest estimate that still confirms within `blocks`, falling back to the slowest we have. */
- const forTarget = (blocks: number): number | undefined => {
- const eligible = estimates.filter((e) => (e.blockcount ?? 0) <= blocks && e.feerate != null);
- const best = eligible.length > 0 ? eligible[eligible.length - 1] : estimates[estimates.length - 1];
- return best?.feerate ?? perkb?.opening;
- };
-
- return {
- fastestFee: toVbyte(forTarget(2)),
- halfHourFee: toVbyte(forTarget(3)),
- hourFee: toVbyte(forTarget(6)),
- economyFee: toVbyte(forTarget(144)),
- minimumFee: toVbyte(perkb?.floor ?? perkb?.min_acceptable),
- };
- }
-
- override async sendCoins(req: SendCoinsRequest): Promise {
- const body: Record = {
- destination: req.address,
- // CLN takes a feerate with an explicit unit; sat/vB × 1000 is the perkb form.
- feerate: `${Math.round(req.satPerVbyte * 1000)}perkb`,
- satoshi: req.sendAll ? 'all' : (req.amountSats ?? 0),
- };
- // CLN's utxos are plain `txid:vout` strings, unlike LND's structured outpoints.
- if (req.outpoints?.length) body.utxos = req.outpoints;
- if (req.spendUnconfirmed) body.minconf = 0;
-
- const res = await this.call('withdraw', body);
- if (!res.txid) throw new BackendError('core lightning returned no txid', 502);
- // `withdraw` returns the signed transaction but not the fee it chose.
- return { txid: res.txid, feeSats: 0, rawHex: res.tx ?? null };
- }
-
- // ── lightning ──────────────────────────────────────────────────────────────────────────────────
-
- private toInvoice(inv: ClnListInvoice): Invoice {
- const expiresAt = inv.expires_at ?? null;
-
- let state: InvoiceState;
- switch (inv.status) {
- case 'paid':
- state = 'settled';
- break;
- case 'expired':
- state = 'expired';
- break;
- default:
- state = expiresAt != null && expiresAt * 1000 < Date.now() ? 'expired' : 'open';
- }
-
- const bolt11 = inv.bolt11 ?? '';
- return {
- paymentHash: inv.payment_hash ?? '',
- // A BOLT12-only invoice has no bolt11; fall back to the offer-issued string so the row is still
- // addressable rather than blank.
- bolt11: bolt11 || (inv.bolt12 ?? ''),
- amountMsat: parseMsat(inv.amount_msat),
- amountPaidMsat: parseMsat(inv.amount_received_msat),
- memo: inv.description ? inv.description : null,
- state,
- // See difference 7: listinvoices has no creation-time column.
- createdAt: bolt11Timestamp(bolt11) ?? inv.paid_at ?? 0,
- expiresAt,
- settledAt: inv.paid_at ?? null,
- preimage: inv.payment_preimage ?? null,
- // CLN does not flag keysend-created invoices, and has no AMP at all (Zeus: supportsAMP = false).
- isKeysend: false,
- isAmp: false,
- };
- }
-
- override async getInvoices(opts?: { limit?: number }): Promise {
- const limit = clampLimit(opts?.limit, 150);
- const res = await this.sql(
- 'SELECT label, bolt11, bolt12, payment_hash, amount_msat, status, amount_received_msat, ' +
- `paid_at, payment_preimage, description, expires_at FROM invoices ORDER BY created_index DESC LIMIT ${limit};`,
- );
-
- return (res.rows ?? []).map((row) =>
- this.toInvoice({
- label: cellStr(row[INVOICE_COL.label]) ?? undefined,
- bolt11: cellStr(row[INVOICE_COL.bolt11]) ?? undefined,
- bolt12: cellStr(row[INVOICE_COL.bolt12]) ?? undefined,
- payment_hash: cellStr(row[INVOICE_COL.paymentHash]) ?? undefined,
- amount_msat: cellMsat(row[INVOICE_COL.amountMsat]),
- status: cellStr(row[INVOICE_COL.status]) ?? undefined,
- amount_received_msat: cellMsat(row[INVOICE_COL.amountReceivedMsat]),
- paid_at: cellNum(row[INVOICE_COL.paidAt]) ?? undefined,
- payment_preimage: cellStr(row[INVOICE_COL.preimage]) ?? undefined,
- description: cellStr(row[INVOICE_COL.description]) ?? undefined,
- expires_at: cellNum(row[INVOICE_COL.expiresAt]) ?? undefined,
- }),
- );
- }
-
- override async createInvoice(req: CreateInvoiceRequest): Promise {
- if (req.preimage) this.notSupported('custom preimages');
- if (req.isAmp) this.notSupported('AMP invoices');
-
- const res = await this.call('invoice', {
- description: req.memo ?? '',
- // `label` is CLN's primary key for an invoice and must be unique per node.
- label: `officer.${Date.now()}.${Math.floor(Math.random() * 1_000_000)}`,
- // The literal string 'any' is how CLN expresses a zero-amount (donation) invoice.
- amount_msat: req.amountMsat ? msatToApiNumber(req.amountMsat, 'amountMsat') : 'any',
- expiry: req.expirySeconds,
- // Zeus hardcodes this to true so an invoice is payable through unannounced channels — without it a
- // node whose inbound liquidity is all private is unreachable.
- exposeprivatechannels: req.private ?? true,
- });
-
- const now = Math.floor(Date.now() / 1000);
- return {
- paymentHash: res.payment_hash ?? '',
- bolt11: res.bolt11 ?? '',
- amountMsat: req.amountMsat ?? null,
- amountPaidMsat: null,
- memo: req.memo ?? null,
- state: 'open',
- createdAt: bolt11Timestamp(res.bolt11) ?? now,
- expiresAt: res.expires_at ?? (req.expirySeconds != null ? now + req.expirySeconds : null),
- settledAt: null,
- preimage: null,
- isKeysend: false,
- isAmp: false,
- };
- }
-
- override async lookupInvoice(paymentHash: string): Promise {
- const res = await this.call<{ invoices?: ClnListInvoice[] }>('listinvoices', { payment_hash: paymentHash });
- const invoice = res.invoices?.[0];
- return invoice ? this.toInvoice(invoice) : null;
- }
-
- override async decodeInvoice(bolt11: string): Promise {
- // `decode` handles bolt11 and bolt12 alike but arrives with the offers plugin; `decodepay` is the
- // classic bolt11-only command and is always present. Try the general one, fall back to the old one.
- let decoded: ClnDecoded;
- try {
- decoded = await this.call('decode', { string: bolt11 });
- if (decoded.valid === false) throw new BackendError('invoice failed to decode', 400);
- } catch (err) {
- if (err instanceof BackendError && err.status === 400) throw err;
- decoded = await this.call('decodepay', { bolt11 });
- }
-
- return {
- bolt11,
- paymentHash: decoded.payment_hash ?? '',
- amountMsat: parseMsat(decoded.amount_msat),
- description: decoded.description ? decoded.description : null,
- destination: decoded.payee ?? '',
- timestamp: decoded.created_at ?? 0,
- expiry: decoded.expiry ?? 0,
- cltvExpiry: decoded.min_final_cltv_expiry ?? null,
- routeHints: (decoded.routes ?? []).length > 0,
- // CLN hands back a raw hex feature BITMAP where LND names each feature; expand it to the indices of
- // the set bits so the shape still matches and nothing is invented.
- features: featureBits(decoded.features),
- };
- }
-
- override async getPayments(opts?: { limit?: number }): Promise {
- const limit = clampLimit(opts?.limit, 150);
- // Grouping by (payment_hash, groupid) collapses the parts of an MPP payment back into one row; the
- // per-part rows in `sendpays` would otherwise each look like a separate payment.
- const res = await this.sql(
- 'select sp.payment_hash, sp.groupid, min(sp.status) as status, min(sp.destination) as destination, ' +
- 'min(sp.created_at) as created_at, min(sp.description) as description, min(sp.bolt11) as bolt11, ' +
- "min(sp.bolt12) as bolt12, sum(case when sp.status = 'complete' then sp.amount_sent_msat else null end) " +
- "as amount_sent_msat, sum(case when sp.status = 'complete' then sp.amount_msat else 0 end) as amount_msat, " +
- `max(sp.payment_preimage) as preimage from sendpays sp group by sp.payment_hash, sp.groupid ` +
- `order by created_index desc limit ${limit}`,
- );
-
- return (res.rows ?? []).map((row) => {
- const amountMsat = parseMsat(cellMsat(row[PAYMENT_COL.amountMsat])) ?? '0';
- const sentMsat = parseMsat(cellMsat(row[PAYMENT_COL.amountSentMsat])) ?? amountMsat;
- // The routing fee is the difference between what left us and what reached the payee.
- const fee = BigInt(sentMsat) - BigInt(amountMsat);
-
- return {
- paymentHash: cellStr(row[PAYMENT_COL.paymentHash]) ?? '',
- preimage: cellStr(row[PAYMENT_COL.preimage]),
- amountMsat,
- feeMsat: (fee > 0n ? fee : 0n).toString(),
- status: toPaymentStatus(cellStr(row[PAYMENT_COL.status]) ?? undefined),
- createdAt: cellNum(row[PAYMENT_COL.createdAt]) ?? 0,
- destination: cellStr(row[PAYMENT_COL.destination]),
- memo: cellStr(row[PAYMENT_COL.description]),
- // sendpays records no failure text; a failed attempt only carries a status.
- failureReason: null,
- };
- });
- }
-
- private toPayment(res: ClnPayResult, fallbackDestination: string | null, memo: string | null): Payment {
- const amountMsat = parseMsat(res.amount_msat) ?? '0';
- const sentMsat = parseMsat(res.amount_sent_msat) ?? amountMsat;
- const fee = BigInt(sentMsat) - BigInt(amountMsat);
-
- return {
- paymentHash: res.payment_hash ?? '',
- preimage: res.payment_preimage ?? null,
- amountMsat,
- feeMsat: (fee > 0n ? fee : 0n).toString(),
- status: toPaymentStatus(res.status),
- // created_at is a float in CLN (sub-second resolution); the interface is unix seconds.
- createdAt: Math.floor(toNumber(res.created_at)),
- destination: res.destination ?? fallbackDestination,
- memo,
- failureReason: null,
- };
- }
-
- override async payInvoice(req: PayInvoiceRequest): Promise {
- if (req.feeLimitMsat && req.feeLimitPercent != null) {
- throw new BackendError('feeLimitMsat and feeLimitPercent are mutually exclusive', 400);
- }
-
- const timeoutSeconds = req.timeoutSeconds ?? 60;
- const body: Record = { bolt11: req.bolt11, retry_for: timeoutSeconds };
- // Only send an amount when one was actually requested — see difference 2.
- if (req.amountMsat) body.amount_msat = msatToApiNumber(req.amountMsat, 'amountMsat');
- if (req.feeLimitMsat) body.maxfee = msatToApiNumber(req.feeLimitMsat, 'feeLimitMsat');
- else if (req.feeLimitPercent != null) body.maxfeepercent = req.feeLimitPercent;
-
- // `retry_for` bounds CLN's own retrying; give the socket a little more than that.
- const res = await this.call('pay', body, (timeoutSeconds + 10) * 1000);
- return this.toPayment(res, null, null);
- }
-
- override async sendKeysend(req: KeysendRequest): Promise {
- const timeoutSeconds = 60;
- const body: Record = {
- destination: req.destination,
- amount_msat: msatToApiNumber(req.amountMsat, 'amountMsat'),
- retry_for: timeoutSeconds,
- };
- if (req.feeLimitMsat) body.maxfee = msatToApiNumber(req.feeLimitMsat, 'feeLimitMsat');
- // `extratlvs` values are hex-encoded by CLN's convention, not base64 as in LND's custom records.
- if (req.message) {
- body.extratlvs = { [KEYSEND_MESSAGE_RECORD]: Buffer.from(req.message, 'utf8').toString('hex') };
- }
-
- const res = await this.call('keysend', body, (timeoutSeconds + 10) * 1000);
- return this.toPayment(res, req.destination, req.message ?? null);
- }
-
- // ── channels / peers ───────────────────────────────────────────────────────────────────────────
-
- override async getChannels(): Promise {
- const res = await this.call<{ channels?: ClnPeerChannel[] }>('listpeerchannels');
- const channels = res.channels ?? [];
- const aliases = await this.resolveAliases(channels.map((chan) => chan.peer_id ?? ''));
-
- return channels
- .filter((chan) => chan.state !== 'CLOSED' && chan.state !== 'ONCHAIN')
- .map((chan) => {
- const total = Number(parseMsat(chan.total_msat) ?? '0');
- const ours = Number(parseMsat(chan.to_us_msat) ?? '0');
- return {
- // short_channel_id is the network-visible id but is absent until the funding confirms.
- channelId: chan.short_channel_id ?? chan.channel_id ?? '',
- channelPoint: chan.funding_txid ? `${chan.funding_txid}:${chan.funding_outnum ?? 0}` : null,
- remotePubkey: chan.peer_id ?? '',
- remoteAlias: aliases.get(chan.peer_id ?? '') ?? null,
- capacitySats: Math.floor(total / 1000),
- localBalanceSats: Math.floor(ours / 1000),
- remoteBalanceSats: Math.floor((total - ours) / 1000),
- active: chan.peer_connected === true && chan.state === 'CHANNELD_NORMAL',
- // CLN's `private` is the inverse of the gossip announcement; unset means announced.
- private: chan.private === true,
- status: toChannelStatus(chan.state),
- };
- });
- }
-
- override async getPeers(): Promise {
- const res = await this.call<{ peers?: ClnPeer[] }>('listpeers');
- const peers = res.peers ?? [];
- const aliases = await this.resolveAliases(peers.map((peer) => peer.id ?? ''));
-
- return peers.map((peer) => ({
- pubkey: peer.id ?? '',
- address: peer.netaddr?.[0] ?? '',
- alias: aliases.get(peer.id ?? '') ?? null,
- // listpeers does not report which side dialled; LND's `inbound` has no CLN equivalent.
- inbound: false,
- }));
- }
-
- // ── signing ────────────────────────────────────────────────────────────────────────────────────
-
- override async signMessage(message: string): Promise {
- const res = await this.call('signmessage', { message });
- // zbase, not the hex `signature` — see difference 4.
- if (!res.zbase) throw new BackendError('core lightning returned no signature', 502);
- return { signature: res.zbase };
- }
-
- override async verifyMessage(message: string, signature: string): Promise {
- const res = await this.call('checkmessage', { message, zbase: signature });
- return { valid: res.verified === true, pubkey: res.pubkey ?? null };
- }
-}
-
-/** Hex feature bitmap → the indices of its set bits, least-significant bit first. */
-function featureBits(hex: string | undefined): string[] {
- if (!hex) return [];
- const bytes = Buffer.from(hex, 'hex');
- const bits: string[] = [];
- // The bitmap is big-endian: the LAST byte holds bits 0-7.
- for (let i = 0; i < bytes.length; i++) {
- const byte = bytes[bytes.length - 1 - i] ?? 0;
- for (let bit = 0; bit < 8; bit++) {
- if (byte & (1 << bit)) bits.push(String(i * 8 + bit));
- }
- }
- return bits;
-}
diff --git a/src/servers/sidecar/wallet/backends/lnd.ts b/src/servers/sidecar/wallet/backends/lnd.ts
deleted file mode 100644
index 5ce0483e..00000000
--- a/src/servers/sidecar/wallet/backends/lnd.ts
+++ /dev/null
@@ -1,860 +0,0 @@
-// LND REST backend — ported from Zeus's `backends/LND.ts` (+ `utils/LndUtils.ts` for the address-type
-// mapping). Zeus's class is a thin, untyped RPC shim: every method returns the upstream JSON verbatim and
-// the view layer does the unit conversion. Here the conversion happens once, at the edge, against the
-// `WalletBackend` contract in `../types.ts`.
-//
-// INTENTIONAL BEHAVIOURAL DIFFERENCES FROM ZEUS
-//
-// 1. No Tor. Zeus routes through `doTorRequest` when `enableTor` is set. A sidecar on the owner's own box
-// reaches its node directly; if Tor is ever needed it belongs in the dispatcher, not per backend.
-// 2. No in-flight call de-duplication. Zeus keys a module-level `calls` Map by url+body so a second
-// identical request joins the first, and needs `clearCachedCalls()` to escape a poisoned entry. That
-// cache is a mobile-battery optimisation and a footgun (a failed call can be re-awaited); dropped.
-// 3. No `forcedTimeout` race. Zeus races `payLightningInvoice` against a promise that RESOLVES with a fake
-// `{payment_error: 'timed out'}` after timeout+1s — so a slow payment silently reports failure while
-// still in flight. We pass a real deadline to `httpJson` and let it abort, surfacing a 502.
-// 4. TLS verification is opt-in per node (`allowSelfSigned`), not the blanket `trusty: !certVerification`.
-// 5. Version gating is OPTIMISTIC until `getInfo()` runs. Zeus reads `nodeInfoStore.version`, which is
-// empty before the first getinfo, so every version-gated `supportsX()` answers false. Here the gated
-// capabilities (coinControl, accounts, offers) start ON and are switched OFF once getInfo reports an
-// older node — a pre-getInfo call to an old node fails upstream instead of 501-ing on a modern one.
-// 6. `offers` is declared for v0.18+. Zeus hardcodes `supportsOffers = () => false` for LND.
-// 7. Websocket-only endpoints are not ported: `openChannelStream`, `initChanAcceptor`,
-// `subscribeCustomMessages`, `subscribeInvoice`, `subscribeTransactions`. `WalletBackend` has no
-// streaming surface.
-// 8. `sendCoins` reports `feeSats: 0`. LND's SendCoinsResponse carries only `txid`; the fee is only
-// observable afterwards through GetTransactions, and we do not block the send on a second round trip.
-// 9. `SendCoinsRequest.rbf` is ignored — lnrpc.SendCoins has no replaceability flag to forward.
-// 10. `Utxo.derivationPath` is always null. Zeus reads paths from a separate ListAddresses call (v0.18+);
-// joining that per-UTXO here would double the request count for a field nothing currently consumes.
-// 11. `Peer.alias` is always null, matching Zeus's `listPeers` — /v1/peers has no alias, and resolving one
-// costs a graph lookup per peer. Channels DO get an alias, via ListChannels' own `peer_alias_lookup`.
-// 12. `InvoiceState.expired` is derived (unsettled + past `creation_date + expiry`); lnrpc's Invoice.state
-// enum has no EXPIRED member.
-// 13. `estimateFees` uses walletrpc EstimateFee. Zeus does not ask LND for on-chain fees at all — it reads
-// mempool.space in the app layer.
-
-import { createHash, randomBytes } from 'node:crypto';
-import {
- BackendError,
- type AddressType,
- type Balances,
- type BackendKind,
- type BitcoinNetwork,
- type Capability,
- type Channel,
- type CreateInvoiceRequest,
- type DecodedInvoice,
- type FeeEstimates,
- type Invoice,
- type InvoiceState,
- type KeysendRequest,
- type NewAddressRequest,
- type NodeInfo,
- type OnchainTx,
- type PayInvoiceRequest,
- type Payment,
- type PaymentStatus,
- type Peer,
- type SendCoinsRequest,
- type SendCoinsResult,
- type SignMessageResult,
- type Utxo,
- type VerifyMessageResult,
-} from '../types';
-import { BaseBackend, base64ToHex, hexToBase64, httpJson } from './base';
-
-// ── upstream wire types ──────────────────────────────────────────────────────────────────────────
-//
-// Field names are lnrpc's own, verbatim. grpc-gateway renders every int64 as a decimal STRING and every
-// `bytes` field as base64 — both quirks are load-bearing below, so the types record them exactly.
-
-type LndChain = { chain?: string; network?: string };
-
-type LndGetInfo = {
- version?: string;
- identity_pubkey?: string;
- alias?: string;
- block_height?: number;
- synced_to_chain?: boolean;
- testnet?: boolean;
- chains?: LndChain[];
-};
-
-type LndBlockchainBalance = {
- total_balance?: string;
- confirmed_balance?: string;
- unconfirmed_balance?: string;
-};
-
-/** lnrpc.Amount — the same sat/msat pair LND uses everywhere it reports a channel-side balance. */
-type LndAmount = { sat?: string; msat?: string };
-
-type LndChannelBalance = {
- balance?: string;
- local_balance?: LndAmount;
- remote_balance?: LndAmount;
-};
-
-type LndTransaction = {
- tx_hash?: string;
- amount?: string;
- num_confirmations?: number;
- block_height?: number;
- time_stamp?: string;
- total_fees?: string;
- dest_addresses?: string[];
- raw_tx_hex?: string;
- label?: string;
-};
-
-type LndUtxo = {
- address_type?: string;
- address?: string;
- amount_sat?: string;
- confirmations?: string;
- outpoint?: { txid_str?: string; output_index?: number };
-};
-
-type LndEstimateFee = { sat_per_kw?: string; min_relay_fee_sat_per_kw?: string };
-
-type LndInvoice = {
- memo?: string;
- r_preimage?: string;
- r_hash?: string;
- value?: string;
- value_msat?: string;
- creation_date?: string;
- settle_date?: string;
- payment_request?: string;
- expiry?: string;
- amt_paid_msat?: string;
- state?: string;
- is_keysend?: boolean;
- is_amp?: boolean;
-};
-
-type LndAddInvoiceResponse = { r_hash?: string; payment_request?: string; payment_addr?: string };
-
-type LndFeature = { name?: string; is_required?: boolean; is_known?: boolean };
-
-type LndPayReq = {
- destination?: string;
- payment_hash?: string;
- num_msat?: string;
- num_satoshis?: string;
- timestamp?: string;
- expiry?: string;
- description?: string;
- cltv_expiry?: string;
- route_hints?: unknown[];
- features?: Record;
-};
-
-type LndHop = { pub_key?: string };
-type LndHtlcAttempt = { route?: { hops?: LndHop[] } };
-
-type LndPayment = {
- payment_hash?: string;
- payment_preimage?: string;
- value_msat?: string;
- fee_msat?: string;
- status?: string;
- creation_date?: string;
- creation_time_ns?: string;
- failure_reason?: string;
- htlcs?: LndHtlcAttempt[];
-};
-
-/** One newline-delimited frame of the SendPaymentV2 stream. */
-type LndRouterFrame = { result?: LndPayment; error?: { message?: string; code?: number } };
-
-type LndChannel = {
- chan_id?: string;
- channel_point?: string;
- remote_pubkey?: string;
- peer_alias?: string;
- capacity?: string;
- local_balance?: string;
- remote_balance?: string;
- active?: boolean;
- private?: boolean;
-};
-
-type LndPendingChannel = {
- remote_node_pub?: string;
- channel_point?: string;
- capacity?: string;
- local_balance?: string;
- remote_balance?: string;
- private?: boolean;
-};
-
-type LndPendingChannels = {
- pending_open_channels?: { channel?: LndPendingChannel }[];
- pending_force_closing_channels?: { channel?: LndPendingChannel }[];
- waiting_close_channels?: { channel?: LndPendingChannel }[];
-};
-
-type LndPeer = { pub_key?: string; address?: string; inbound?: boolean };
-
-// ── constants ────────────────────────────────────────────────────────────────────────────────────
-
-/** Zeus's LndUtils.LNRPC_NEW_ADDRESS_TYPE_NAMES, verbatim. See that file for why each row exists. */
-const LNRPC_NEW_ADDRESS_TYPE_NAMES: Record = {
- '0': 'WITNESS_PUBKEY_HASH',
- '1': 'NESTED_PUBKEY_HASH',
- '2': 'UNUSED_WITNESS_PUBKEY_HASH',
- '3': 'UNUSED_NESTED_PUBKEY_HASH',
- '4': 'TAPROOT_PUBKEY',
- '5': 'UNUSED_TAPROOT_PUBKEY',
- NESTED_WITNESS_PUBKEY_HASH: 'NESTED_PUBKEY_HASH',
- HYBRID_NESTED_WITNESS_PUBKEY_HASH: 'NESTED_PUBKEY_HASH',
-};
-
-/**
- * Zeus's `toLnrpcAddressType`. The numeric strings matter: LND REST's grpc-gateway silently treats an
- * unrecognised `type` as WITNESS_PUBKEY_HASH, so sending '1' quietly yields a native segwit address.
- */
-function toLnrpcAddressType(value: string | number | undefined | null): string | undefined {
- if (value == null) return undefined;
- const key = String(value);
- return LNRPC_NEW_ADDRESS_TYPE_NAMES[key] ?? key;
-}
-
-/** Our AddressType → the lnrpc enum index, in normal and `peek` (UNUSED_*, non-advancing) form. */
-const ADDRESS_TYPE_INDEX: Record = {
- p2wpkh: { fresh: '0', peek: '2' },
- 'p2sh-p2wpkh': { fresh: '1', peek: '3' },
- p2tr: { fresh: '4', peek: '5' },
- // lnrpc.NewAddress has no legacy p2pkh member — LND has never handed out a base58 receive address.
- p2pkh: null,
-};
-
-/** walletrpc's AddressType enum (ListUnspent) → ours. The HYBRID_ variant is still a p2sh-p2wpkh. */
-const WALLETRPC_ADDRESS_TYPE: Record = {
- WITNESS_PUBKEY_HASH: 'p2wpkh',
- NESTED_WITNESS_PUBKEY_HASH: 'p2sh-p2wpkh',
- HYBRID_NESTED_WITNESS_PUBKEY_HASH: 'p2sh-p2wpkh',
- TAPROOT_PUBKEY: 'p2tr',
-};
-
-/** BOLT spec TLV records for keysend: the preimage the receiver settles with, and the free-text message. */
-const KEYSEND_PREIMAGE_RECORD = '5482373484';
-const KEYSEND_MESSAGE_RECORD = '34349334';
-
-/** A 32-byte all-zero preimage is LND's "not settled yet" placeholder, not a real preimage. */
-const ZERO_PREIMAGE_HEX = '0'.repeat(64);
-
-// ── helpers ──────────────────────────────────────────────────────────────────────────────────────
-
-/** int64-as-string → number. Used only for sat-denominated fields, which cannot overflow a double. */
-function toSats(value: string | number | undefined | null): number {
- if (value == null || value === '') return 0;
- const n = Number(value);
- return Number.isFinite(n) ? n : 0;
-}
-
-/** int64-as-string → msat decimal string. Never widened to a number: 2.1e18 does not fit a double. */
-function toMsat(value: string | number | undefined | null): string {
- if (value == null || value === '') return '0';
- return typeof value === 'number' ? Math.round(value).toString() : value;
-}
-
-/** `0.18.3-beta commit=v0.18.3-beta` → [0, 18, 3]. Zeus does the same in VersionUtils. */
-function parseVersion(version: string | null): [number, number, number] | null {
- if (!version) return null;
- const m = /(\d+)\.(\d+)\.(\d+)/.exec(version);
- if (!m) return null;
- return [Number(m[1]), Number(m[2]), Number(m[3])];
-}
-
-/** Unknown version counts as "new enough" — see difference 5 in the header. */
-function atLeast(version: string | null, min: string): boolean {
- const have = parseVersion(version);
- const want = parseVersion(min);
- if (!have || !want) return true;
- for (let i = 0; i < 3; i++) {
- const h = have[i] ?? 0;
- const w = want[i] ?? 0;
- if (h !== w) return h > w;
- }
- return true;
-}
-
-function toNetwork(info: LndGetInfo): BitcoinNetwork {
- const raw = info.chains?.[0]?.network ?? (info.testnet ? 'testnet' : 'mainnet');
- switch (raw) {
- case 'testnet':
- case 'testnet3':
- case 'testnet4':
- return 'testnet';
- case 'signet':
- return 'signet';
- // simnet is btcd's private-chain mode; it behaves like regtest for everything we surface.
- case 'regtest':
- case 'simnet':
- return 'regtest';
- default:
- return 'bitcoin';
- }
-}
-
-function toPaymentStatus(status: string | undefined): PaymentStatus {
- switch (status) {
- case 'SUCCEEDED':
- return 'succeeded';
- case 'FAILED':
- return 'failed';
- // UNKNOWN / IN_FLIGHT / INITIATED all mean "not resolved yet".
- default:
- return 'pending';
- }
-}
-
-export type LndConfig = {
- /** Full base URL including scheme and port, e.g. `https://192.168.1.5:8080`. */
- url: string;
- /** Admin (or narrower) macaroon, hex. Sent as `Grpc-Metadata-macaroon`. */
- macaroonHex: string;
- allowSelfSigned?: boolean;
-};
-
-// ── the backend ──────────────────────────────────────────────────────────────────────────────────
-
-export class LndBackend extends BaseBackend {
- readonly kind: BackendKind = 'lnd';
-
- // Mutated in place by `applyVersionGates`; `capabilities` is the same object seen read-only.
- private readonly caps = new Set([
- 'onchainReceive',
- 'onchainSend',
- 'coinControl',
- 'psbt',
- 'bumpFee',
- 'sweep',
- 'accounts',
- 'lightningReceive',
- 'lightningSend',
- 'keysend',
- 'customPreimages',
- 'offers',
- 'channels',
- 'peers',
- 'routing',
- 'signMessage',
- ]);
- protected readonly capabilities: ReadonlySet = this.caps;
-
- constructor(private readonly config: LndConfig) {
- super();
- }
-
- // ── transport ──────────────────────────────────────────────────────────────────────────────────
-
- private get(path: string, query?: Record): Promise {
- return httpJson({
- base: this.config.url,
- path,
- query,
- method: 'GET',
- headers: { 'Grpc-Metadata-macaroon': this.config.macaroonHex },
- allowSelfSigned: this.config.allowSelfSigned,
- });
- }
-
- private post(path: string, body: unknown, timeoutMs?: number): Promise {
- return httpJson({
- base: this.config.url,
- path,
- method: 'POST',
- body: body ?? {},
- headers: { 'Grpc-Metadata-macaroon': this.config.macaroonHex },
- allowSelfSigned: this.config.allowSelfSigned,
- timeoutMs,
- });
- }
-
- /**
- * SendPaymentV2 (`/v2/router/send`) is a SERVER-STREAMING rpc. grpc-gateway renders it as
- * newline-delimited JSON — one `{"result": …}` frame per payment state change — which `JSON.parse` on
- * the whole body cannot read. Zeus handles this in `restReq` by splitting on '\n' and taking
- * `split[length - 2]` (the body has a trailing newline); we take the last non-empty line, which is the
- * same frame without depending on the trailing newline being there.
- *
- * We also set `no_inflight_updates`, so in practice there is exactly one frame: the terminal one.
- */
- private async routerSend(body: Record, timeoutMs: number): Promise {
- const res = await httpJson({
- base: this.config.url,
- path: '/v2/router/send',
- method: 'POST',
- body,
- headers: { 'Grpc-Metadata-macaroon': this.config.macaroonHex },
- allowSelfSigned: this.config.allowSelfSigned,
- timeoutMs,
- raw: true,
- });
-
- const text = await res.text();
- const lines = text.split('\n').filter((line) => line.trim().length > 0);
- const last = lines[lines.length - 1];
-
- if (!last) {
- throw new BackendError(`router/send returned an empty body (HTTP ${res.status})`, res.ok ? 502 : res.status);
- }
-
- let frame: LndRouterFrame;
- try {
- frame = JSON.parse(last) as LndRouterFrame;
- } catch {
- throw new BackendError(`router/send returned non-JSON: ${last.slice(0, 200)}`, res.ok ? 502 : res.status);
- }
-
- // A stream error arrives as a frame, not as a non-2xx status, so check it before `res.ok`.
- if (frame.error) {
- throw new BackendError(
- frame.error.message ?? 'payment failed',
- res.ok ? 502 : res.status,
- frame.error.code != null ? String(frame.error.code) : undefined,
- );
- }
- if (!res.ok || !frame.result) {
- throw new BackendError(`router/send failed: ${last.slice(0, 200)}`, res.ok ? 502 : res.status);
- }
- return frame.result;
- }
-
- /** Zeus's version predicates, evaluated once per getInfo instead of once per `supportsX()` call. */
- private applyVersionGates(version: string | null): void {
- const gate = (cap: Capability, min: string) => {
- if (atLeast(version, min)) this.caps.add(cap);
- else this.caps.delete(cap);
- };
- gate('coinControl', '0.12.0'); // Zeus: supportsCoinControl
- gate('accounts', '0.13.0'); // Zeus: supportsAccounts
- gate('offers', '0.18.0'); // Zeus hardcodes false; see difference 6
- }
-
- // ── node / balances ────────────────────────────────────────────────────────────────────────────
-
- override async getInfo(): Promise {
- const info = await this.get('/v1/getinfo');
- const version = info.version ?? null;
- this.applyVersionGates(version);
- return {
- kind: this.kind,
- pubkey: info.identity_pubkey ?? null,
- alias: info.alias ?? null,
- version,
- network: toNetwork(info),
- blockHeight: info.block_height ?? null,
- synced: info.synced_to_chain === true,
- };
- }
-
- override async getBalances(): Promise {
- const [chain, channels] = await Promise.all([
- this.get('/v1/balance/blockchain'),
- this.get('/v1/balance/channels'),
- ]);
- return {
- onchainConfirmed: toSats(chain.confirmed_balance),
- onchainFrozen: 0,
- onchainUnconfirmed: toSats(chain.unconfirmed_balance),
- // `balance` is the deprecated flat field; the nested Amount is authoritative on v0.11+.
- lightningBalance: toSats(channels.local_balance?.sat ?? channels.balance),
- lightningInbound: toSats(channels.remote_balance?.sat),
- };
- }
-
- // ── on-chain ───────────────────────────────────────────────────────────────────────────────────
-
- override async getTransactions(opts?: { limit?: number }): Promise {
- // `end_height=-1` is LND's "up to and including unconfirmed" sentinel — without it the mempool is
- // excluded and a just-broadcast send is invisible.
- const res = await this.get<{ transactions?: LndTransaction[] }>('/v1/transactions', {
- end_height: -1,
- max_transactions: opts?.limit ?? 500,
- });
- return (res.transactions ?? []).map((tx) => ({
- txid: tx.tx_hash ?? '',
- amount: toSats(tx.amount),
- feeSats: tx.total_fees != null ? toSats(tx.total_fees) : null,
- blockHeight: tx.block_height ? tx.block_height : null,
- timestamp: tx.time_stamp ? toSats(tx.time_stamp) : null,
- confirmations: tx.num_confirmations ?? 0,
- label: tx.label ? tx.label : null,
- destAddresses: tx.dest_addresses ?? [],
- rawHex: tx.raw_tx_hex ?? null,
- }));
- }
-
- override async getNewAddress(req?: NewAddressRequest): Promise<{ address: string; type: AddressType }> {
- const type: AddressType = req?.type ?? 'p2wpkh';
- const index = ADDRESS_TYPE_INDEX[type];
- if (!index) throw new BackendError(`lnd cannot derive a ${type} address`, 400, 'UNSUPPORTED_ADDRESS_TYPE');
-
- // `peek` maps onto the UNUSED_* enum members, which return the current address without advancing the
- // derivation index — LND's only form of "show me the same address again".
- const lnrpcType = toLnrpcAddressType(req?.peek ? index.peek : index.fresh);
- const res = await this.get<{ address?: string }>('/v1/newaddress', { type: lnrpcType });
- if (!res.address) throw new BackendError('lnd returned no address', 502);
- return { address: res.address, type };
- }
-
- override async getUtxos(): Promise {
- // max_confs must be set explicitly: walletrpc defaults it to 0, which matches nothing.
- const res = await this.post<{ utxos?: LndUtxo[] }>('/v2/wallet/utxos', {
- min_confs: 0,
- max_confs: 0x7fffffff,
- });
- return (res.utxos ?? []).map((utxo) => ({
- txid: utxo.outpoint?.txid_str ?? '',
- vout: utxo.outpoint?.output_index ?? 0,
- amountSats: toSats(utxo.amount_sat),
- address: utxo.address ?? '',
- addressType: utxo.address_type ? (WALLETRPC_ADDRESS_TYPE[utxo.address_type] ?? null) : null,
- confirmations: toSats(utxo.confirmations),
- derivationPath: null,
- // ListUnspent already omits leased outputs, so anything we can see here is selectable.
- frozen: false,
- }));
- }
-
- override async estimateFees(): Promise {
- // walletrpc quotes sat/kw (weight units). 1 vB = 4 wu, so sat/vB = sat_per_kw / 250.
- const perVbyte = (satPerKw: string | undefined): number => Math.max(1, Math.ceil(toSats(satPerKw) / 250));
-
- const targets = [2, 3, 6, 144] as const;
- const [fastest, halfHour, hour, economy] = await Promise.all(
- targets.map((target) => this.get(`/v2/wallet/estimatefee/${target}`)),
- );
-
- return {
- fastestFee: perVbyte(fastest?.sat_per_kw),
- halfHourFee: perVbyte(halfHour?.sat_per_kw),
- hourFee: perVbyte(hour?.sat_per_kw),
- economyFee: perVbyte(economy?.sat_per_kw),
- // min_relay_fee_sat_per_kw only exists on v0.18+; 253 sat/kw is bitcoind's floor (~1 sat/vB).
- minimumFee: perVbyte(fastest?.min_relay_fee_sat_per_kw ?? '253'),
- };
- }
-
- override async sendCoins(req: SendCoinsRequest): Promise {
- if (req.outpoints?.length && !this.supports('coinControl')) this.notSupported('coin control');
-
- const body: Record = {
- addr: req.address,
- sat_per_vbyte: String(req.satPerVbyte),
- spend_unconfirmed: req.spendUnconfirmed === true,
- label: req.label,
- };
- if (req.sendAll) body.send_all = true;
- else body.amount = String(req.amountSats ?? 0);
-
- if (req.outpoints?.length) {
- body.outpoints = req.outpoints.map((outpoint) => {
- const [txid, vout] = outpoint.split(':');
- return { txid_str: txid, output_index: Number(vout ?? 0) };
- });
- }
-
- const res = await this.post<{ txid?: string }>('/v1/transactions', body);
- if (!res.txid) throw new BackendError('lnd returned no txid', 502);
- return { txid: res.txid, feeSats: 0, rawHex: null };
- }
-
- // ── lightning ──────────────────────────────────────────────────────────────────────────────────
-
- private toInvoice(inv: LndInvoice): Invoice {
- const createdAt = toSats(inv.creation_date);
- const expiry = toSats(inv.expiry);
- const expiresAt = expiry > 0 ? createdAt + expiry : null;
- const settledAt = toSats(inv.settle_date);
- const preimageHex = inv.r_preimage ? base64ToHex(inv.r_preimage) : '';
-
- let state: InvoiceState;
- switch (inv.state) {
- case 'SETTLED':
- state = 'settled';
- break;
- case 'CANCELED':
- state = 'canceled';
- break;
- case 'ACCEPTED':
- state = 'accepted';
- break;
- default:
- // lnrpc has no EXPIRED member; an unsettled invoice past its deadline is reported as OPEN.
- state = expiresAt != null && expiresAt * 1000 < Date.now() ? 'expired' : 'open';
- }
-
- return {
- paymentHash: inv.r_hash ? base64ToHex(inv.r_hash) : '',
- bolt11: inv.payment_request ?? '',
- amountMsat: inv.value_msat && inv.value_msat !== '0' ? toMsat(inv.value_msat) : null,
- amountPaidMsat: inv.amt_paid_msat && inv.amt_paid_msat !== '0' ? toMsat(inv.amt_paid_msat) : null,
- memo: inv.memo ? inv.memo : null,
- state,
- createdAt,
- expiresAt,
- settledAt: settledAt > 0 ? settledAt : null,
- // LND ships an all-zero r_preimage for anything it has not settled — that is a placeholder, not a
- // secret, and passing it on would let a caller believe it can claim the HTLC.
- preimage: preimageHex && preimageHex !== ZERO_PREIMAGE_HEX ? preimageHex : null,
- isKeysend: inv.is_keysend === true,
- isAmp: inv.is_amp === true,
- };
- }
-
- override async getInvoices(opts?: { limit?: number }): Promise {
- // reversed=true walks the add_index backwards, i.e. newest first.
- const res = await this.get<{ invoices?: LndInvoice[] }>('/v1/invoices', {
- reversed: true,
- num_max_invoices: opts?.limit ?? 500,
- });
- return (res.invoices ?? []).map((inv) => this.toInvoice(inv));
- }
-
- override async createInvoice(req: CreateInvoiceRequest): Promise {
- const res = await this.post('/v1/invoices', {
- memo: req.memo,
- value_msat: req.amountMsat,
- expiry: req.expirySeconds != null ? String(req.expirySeconds) : undefined,
- is_amp: req.isAmp,
- private: req.private,
- r_preimage: req.preimage ? hexToBase64(req.preimage) : undefined,
- });
-
- const paymentHash = res.r_hash ? base64ToHex(res.r_hash) : '';
-
- // AddInvoiceResponse carries only the hash, the request string and the payment address — no
- // timestamps and no state — so read the invoice back to answer with a complete record.
- const stored = paymentHash ? await this.lookupInvoice(paymentHash).catch(() => null) : null;
- if (stored) return stored;
-
- const now = Math.floor(Date.now() / 1000);
- return {
- paymentHash,
- bolt11: res.payment_request ?? '',
- amountMsat: req.amountMsat ?? null,
- amountPaidMsat: null,
- memo: req.memo ?? null,
- state: 'open',
- createdAt: now,
- expiresAt: req.expirySeconds != null ? now + req.expirySeconds : null,
- settledAt: null,
- preimage: null,
- isKeysend: false,
- isAmp: req.isAmp === true,
- };
- }
-
- override async lookupInvoice(paymentHash: string): Promise {
- try {
- // The path segment is `r_hash_str` — hex, not the base64 used by the body fields.
- const inv = await this.get(`/v1/invoice/${paymentHash}`);
- return this.toInvoice(inv);
- } catch (err) {
- if (err instanceof BackendError && err.status === 404) return null;
- throw err;
- }
- }
-
- override async decodeInvoice(bolt11: string): Promise {
- const res = await this.get(`/v1/payreq/${encodeURIComponent(bolt11)}`);
- return {
- bolt11,
- // PayReq.payment_hash is a proto `string` (already hex), unlike Invoice.r_hash which is `bytes`.
- paymentHash: res.payment_hash ?? '',
- amountMsat: res.num_msat && res.num_msat !== '0' ? toMsat(res.num_msat) : null,
- description: res.description ? res.description : null,
- destination: res.destination ?? '',
- timestamp: toSats(res.timestamp),
- expiry: toSats(res.expiry),
- cltvExpiry: res.cltv_expiry != null ? toSats(res.cltv_expiry) : null,
- routeHints: (res.route_hints ?? []).length > 0,
- features: Object.values(res.features ?? {})
- .map((feature) => feature.name)
- .filter((name): name is string => !!name),
- };
- }
-
- private toPayment(payment: LndPayment): Payment {
- const preimage = payment.payment_preimage ?? '';
- // creation_date (seconds) was deprecated in favour of creation_time_ns; accept either.
- const createdAt = payment.creation_date
- ? toSats(payment.creation_date)
- : Math.floor(toSats(payment.creation_time_ns) / 1e9);
- const hops = payment.htlcs?.[0]?.route?.hops ?? [];
-
- return {
- // ListPayments renders payment_hash/payment_preimage as proto `string`s — already hex.
- paymentHash: payment.payment_hash ?? '',
- preimage: preimage && preimage !== ZERO_PREIMAGE_HEX ? preimage : null,
- amountMsat: toMsat(payment.value_msat),
- feeMsat: toMsat(payment.fee_msat),
- status: toPaymentStatus(payment.status),
- createdAt,
- // lnrpc.Payment has no destination field; the last hop of the first attempt's route is the payee.
- destination: hops[hops.length - 1]?.pub_key ?? null,
- // Recovering the memo would mean decoding payment_request on every row.
- memo: null,
- failureReason:
- payment.failure_reason && payment.failure_reason !== 'FAILURE_REASON_NONE' ? payment.failure_reason : null,
- };
- }
-
- override async getPayments(opts?: { limit?: number }): Promise {
- const res = await this.get<{ payments?: LndPayment[] }>('/v1/payments', {
- include_incomplete: true,
- max_payments: opts?.limit ?? 500,
- reversed: true,
- });
- return (res.payments ?? []).map((payment) => this.toPayment(payment));
- }
-
- override async payInvoice(req: PayInvoiceRequest): Promise {
- if (req.feeLimitMsat && req.feeLimitPercent != null) {
- throw new BackendError('feeLimitMsat and feeLimitPercent are mutually exclusive', 400);
- }
-
- const timeoutSeconds = req.timeoutSeconds ?? 60;
- const body: Record = {
- payment_request: req.bolt11,
- timeout_seconds: timeoutSeconds,
- // Zeus sets this so a payment to one's own node is not rejected as a self-payment.
- allow_self_payment: true,
- // Collapses the stream to a single terminal frame — see `routerSend`.
- no_inflight_updates: true,
- };
- if (req.amountMsat) body.amt_msat = req.amountMsat;
-
- if (req.feeLimitMsat) {
- body.fee_limit_msat = req.feeLimitMsat;
- } else if (req.feeLimitPercent != null) {
- // SendPaymentRequest has no percentage form (that is a CLN concept), so resolve the invoice amount
- // and turn the percentage into the absolute cap LND wants.
- const amountMsat = req.amountMsat ?? (await this.decodeInvoice(req.bolt11)).amountMsat;
- if (!amountMsat) {
- throw new BackendError('feeLimitPercent needs an amount: the invoice is zero-amount', 400);
- }
- const limit = (BigInt(amountMsat) * BigInt(Math.round(req.feeLimitPercent * 100))) / 10_000n;
- body.fee_limit_msat = limit.toString();
- }
-
- // Give the HTTP call a little more room than LND's own deadline so the node, not the socket, decides.
- const result = await this.routerSend(body, (timeoutSeconds + 10) * 1000);
- return this.toPayment(result);
- }
-
- override async sendKeysend(req: KeysendRequest): Promise {
- // Keysend is a spontaneous payment: WE pick the preimage, hash it ourselves, and ship the preimage to
- // the receiver in TLV 5482373484 so it can settle an HTLC it never issued an invoice for.
- const preimage = randomBytes(32);
- const paymentHash = createHash('sha256').update(preimage).digest();
-
- const customRecords: Record = {
- [KEYSEND_PREIMAGE_RECORD]: preimage.toString('base64'),
- };
- if (req.message) customRecords[KEYSEND_MESSAGE_RECORD] = Buffer.from(req.message, 'utf8').toString('base64');
-
- const timeoutSeconds = 60;
- const body: Record = {
- dest: hexToBase64(req.destination),
- amt_msat: req.amountMsat,
- payment_hash: paymentHash.toString('base64'),
- dest_custom_records: customRecords,
- // Without a route hint there is no invoice to read a final CLTV delta from; 40 is LND's own default.
- final_cltv_delta: 40,
- timeout_seconds: timeoutSeconds,
- allow_self_payment: true,
- no_inflight_updates: true,
- };
- if (req.feeLimitMsat) body.fee_limit_msat = req.feeLimitMsat;
-
- const result = await this.routerSend(body, (timeoutSeconds + 10) * 1000);
- return this.toPayment(result);
- }
-
- // ── channels / peers ───────────────────────────────────────────────────────────────────────────
-
- override async getChannels(): Promise {
- const [open, pending] = await Promise.all([
- // peer_alias_lookup makes LND resolve each peer's graph alias for us (v0.15.1+); on older nodes the
- // parameter is ignored and `peer_alias` simply comes back absent.
- this.get<{ channels?: LndChannel[] }>('/v1/channels', { peer_alias_lookup: true }),
- this.get('/v1/channels/pending'),
- ]);
-
- const channels: Channel[] = (open.channels ?? []).map((chan) => ({
- channelId: chan.chan_id ?? chan.channel_point ?? '',
- channelPoint: chan.channel_point ?? null,
- remotePubkey: chan.remote_pubkey ?? '',
- remoteAlias: chan.peer_alias ? chan.peer_alias : null,
- capacitySats: toSats(chan.capacity),
- localBalanceSats: toSats(chan.local_balance),
- remoteBalanceSats: toSats(chan.remote_balance),
- active: chan.active === true,
- private: chan.private === true,
- status: 'open',
- }));
-
- const fromPending = (entries: { channel?: LndPendingChannel }[] | undefined, status: string): Channel[] =>
- (entries ?? [])
- .map((entry) => entry.channel)
- .filter((chan): chan is LndPendingChannel => !!chan)
- .map((chan) => ({
- // A pending channel has no short channel id yet — the funding outpoint is its only identity.
- channelId: chan.channel_point ?? '',
- channelPoint: chan.channel_point ?? null,
- remotePubkey: chan.remote_node_pub ?? '',
- remoteAlias: null,
- capacitySats: toSats(chan.capacity),
- localBalanceSats: toSats(chan.local_balance),
- remoteBalanceSats: toSats(chan.remote_balance),
- active: false,
- private: chan.private === true,
- status,
- }));
-
- return [
- ...channels,
- ...fromPending(pending.pending_open_channels, 'pending-open'),
- // "waiting close" is a cooperative close whose closing tx has not confirmed; force-closing is the
- // unilateral path with a timelock still to run.
- ...fromPending(pending.waiting_close_channels, 'pending-close'),
- ...fromPending(pending.pending_force_closing_channels, 'force-closing'),
- ];
- }
-
- override async getPeers(): Promise {
- const res = await this.get<{ peers?: LndPeer[] }>('/v1/peers');
- return (res.peers ?? []).map((peer) => ({
- pubkey: peer.pub_key ?? '',
- address: peer.address ?? '',
- alias: null,
- inbound: peer.inbound === true,
- }));
- }
-
- // ── signing ────────────────────────────────────────────────────────────────────────────────────
-
- override async signMessage(message: string): Promise {
- // lnrpc.SignMessageRequest.msg is `bytes`, so the payload is base64 even though it is plain text.
- const res = await this.post<{ signature?: string }>('/v1/signmessage', {
- msg: Buffer.from(message, 'utf8').toString('base64'),
- });
- if (!res.signature) throw new BackendError('lnd returned no signature', 502);
- return { signature: res.signature };
- }
-
- override async verifyMessage(message: string, signature: string): Promise {
- const res = await this.post<{ valid?: boolean; pubkey?: string }>('/v1/verifymessage', {
- msg: Buffer.from(message, 'utf8').toString('base64'),
- signature,
- });
- return { valid: res.valid === true, pubkey: res.pubkey ?? null };
- }
-}
diff --git a/src/servers/sidecar/wallet/backends/lndhub.ts b/src/servers/sidecar/wallet/backends/lndhub.ts
deleted file mode 100644
index 8e020e76..00000000
--- a/src/servers/sidecar/wallet/backends/lndhub.ts
+++ /dev/null
@@ -1,602 +0,0 @@
-// LNDHub — port of Zeus's backends/LndHub.ts (which `extends LND` and overrides ~10 methods).
-//
-// LNDHub is a CUSTODIAL account API, not a node. The server holds the keys; this backend is a thin
-// client over a REST facade (BlueWallet/LndHub, LNbits' lndhub extension, Alby, lntxbot, …). There is
-// no node identity, no channel view, no UTXO set and no on-chain spend — only a balance, invoices,
-// payments and (on some deployments) a single deposit address.
-//
-// Differences from Zeus, all deliberate:
-//
-// 1. AUTH. Zeus logs in from SettingsStore (SettingsStore.ts:2090-2130), parks `access_token` in an
-// observable and then never refreshes it — an expired token surfaces as a "bad auth" error string
-// in the UI. Here the token is cached in memory, acquired lazily, and re-acquired transparently on
-// the first auth failure of any request, through a single-flight promise so N concurrent calls
-// produce one login rather than N.
-// 2. ERRORS. LNDHub reports failure as **HTTP 200 with `{error, code, message}`** (Zeus checks for
-// this ad hoc in three different stores: InvoicesStore.ts:410, TransactionsStore.ts:795). httpJson
-// only maps non-2xx, so every response goes through `unwrap()` first. Error code 1 ("bad auth") is
-// re-raised as a 401 so it feeds the same re-auth path as a real 401.
-// 3. lookupInvoice / getTransactions. Zeus *inherits* LND's `/v1/invoice/:r_hash` and
-// `/v1/transactions`, neither of which exists on an LNDHub server — those calls simply fail
-// upstream. lookupInvoice here scans `/getuserinvoices`; on-chain history is read out of the
-// `bitcoind_tx` entries that `/gettxs` interleaves with lightning payments.
-// 4. decodeInvoice. Zeus decodes BOLT11 locally (Bolt11Utils). The sidecar has no bolt11 decoder, so
-// this uses the server's own `/decodeinvoice`, which returns LND's payreq shape.
-// 5. The `lnurlAuth` signing modes (Alby vs BlueWallet key derivation) are not ported — LNURL-auth is
-// not part of the WalletBackend contract.
-//
-// UNITS. LNDHub is sloppy here and each field has to be taken on its own terms:
-// • /balance → BTC.AvailableBalance, satoshis
-// • /getuserinvoices → `amt`, satoshis
-// • /gettxs (payment) → `value` and `fee`, satoshis, where `value` already includes `fee`
-// • /gettxs (onchain) → `amount`, **BTC** as a float (verbatim from bitcoind's listtransactions)
-// • /decodeinvoice → `num_satoshis` and `num_msat` side by side
-// Everything is normalised to the contract's sats-as-number / msats-as-decimal-string rule on the way out.
-
-import {
- BackendError,
- type AddressType,
- type Balances,
- type BackendKind,
- type Capability,
- type CreateInvoiceRequest,
- type DecodedInvoice,
- type Invoice,
- type InvoiceState,
- type NewAddressRequest,
- type NodeInfo,
- type OnchainTx,
- type PayInvoiceRequest,
- type Payment,
- type BitcoinNetwork,
-} from '../types';
-import { BaseBackend, base64ToHex, httpJson } from './base';
-import { decodeBolt11 } from '../bolt11';
-
-export type LndHubConfig = {
- /** Base URL of the LNDHub server, e.g. https://lndhub.example.com or https://ln.getalby.com/lndhub. */
- url: string;
- login: string;
- password: string;
- /** Opt-in TLS relaxation for a self-hosted server with a self-signed cert. Never default. */
- allowSelfSigned?: boolean;
-};
-
-// ── upstream wire shapes ─────────────────────────────────────────────────────────────────────────
-
-/** Every LNDHub response can be this instead of the documented shape, with HTTP 200. */
-type LndHubErrorBody = { error?: string | boolean | number; code?: number; message?: string };
-
-/** node's `JSON.stringify(Buffer)` — LNDHub leaks raw Buffers for hash/preimage fields. */
-type LndHubBuffer = { type?: string; data?: number[] };
-type LndHubBytes = string | LndHubBuffer;
-
-type LndHubAuth = { access_token?: string; refresh_token?: string };
-
-type LndHubBalance = { BTC?: { AvailableBalance?: number; TotalBalance?: number } };
-
-type LndHubGetInfo = {
- identity_pubkey?: string;
- alias?: string;
- version?: string;
- block_height?: number;
- testnet?: boolean;
- synced_to_chain?: boolean;
- chains?: { chain?: string; network?: string }[];
-};
-
-type LndHubUserInvoice = {
- payment_request?: string;
- pay_req?: string;
- r_hash?: LndHubBytes;
- payment_hash?: LndHubBytes;
- description?: string;
- memo?: string;
- ispaid?: boolean;
- /** satoshis */
- amt?: number | string;
- amt_paid_sat?: number | string;
- amt_paid_msat?: number | string;
- /** seconds of validity, relative to `timestamp` */
- expire_time?: number;
- /** unix seconds */
- timestamp?: number | string;
- settled_at?: number;
- type?: string;
-};
-
-/** `/gettxs` interleaves outgoing lightning payments and imported on-chain deposits. */
-type LndHubTx = {
- type?: string;
- // paid_invoice
- payment_preimage?: LndHubBytes;
- payment_hash?: LndHubBytes;
- payment_request?: string;
- /** satoshis, and LNDHub folds `fee` into it (User.getTxs) */
- value?: number | string;
- /** satoshis */
- fee?: number | string;
- memo?: string;
- description?: string;
- timestamp?: number | string;
- // bitcoind_tx
- txid?: string;
- /** BTC, float, straight from bitcoind */
- amount?: number;
- confirmations?: number;
- address?: string;
- category?: string;
- time?: number;
- blockheight?: number;
-};
-
-type LndHubAddress = { address?: string };
-
-type LndHubDecoded = {
- destination?: string;
- payment_hash?: string;
- num_satoshis?: string | number;
- num_msat?: string | number;
- timestamp?: string | number;
- expiry?: string | number;
- description?: string;
- cltv_expiry?: string | number;
- route_hints?: unknown[];
- features?: Record;
-};
-
-/** `/payinvoice` passes LND's sendPaymentSync response through, mostly. */
-type LndHubPayResult = {
- payment_error?: string;
- payment_preimage?: LndHubBytes;
- payment_hash?: LndHubBytes;
- payment_route?: {
- total_amt?: number | string;
- total_fees?: number | string;
- total_amt_msat?: number | string;
- total_fees_msat?: number | string;
- };
- decoded?: LndHubDecoded;
- /** some forks answer a zero-amount pay with the amount they chose */
- num_satoshis?: number | string;
-};
-
-type LndHubCall = {
- path: string;
- method?: 'GET' | 'POST';
- body?: unknown;
- query?: Record;
-};
-
-// ── helpers ──────────────────────────────────────────────────────────────────────────────────────
-
-const HEX32 = /^[0-9a-f]{64}$/i;
-
-/** LNDHub returns a 32-byte field as hex, base64, url-safe base64 or a stringified Buffer. */
-function bytesToHex(value: LndHubBytes | undefined | null): string {
- if (!value) return '';
- if (typeof value === 'string') {
- if (HEX32.test(value)) return value.toLowerCase();
- return base64ToHex(value.replace(/-/g, '+').replace(/_/g, '/'));
- }
- if (Array.isArray(value.data)) return Buffer.from(value.data).toString('hex');
- return '';
-}
-
-const num = (value: number | string | undefined | null): number => {
- const n = typeof value === 'string' ? Number(value) : value;
- return typeof n === 'number' && Number.isFinite(n) ? n : 0;
-};
-
-const satsToMsat = (sats: number): string => (BigInt(Math.round(sats)) * 1000n).toString();
-
-/** msat string → whole satoshis. LNDHub cannot express sub-satoshi amounts anywhere. */
-function msatToSats(msat: string, field: string): number {
- const value = BigInt(msat);
- if (value % 1000n !== 0n) {
- throw new BackendError(`lndhub cannot express sub-satoshi amounts (${field}=${msat}msat)`, 400, 'BAD_AMOUNT');
- }
- return Number(value / 1000n);
-}
-
-/** LNDHub tells us nothing about the address it hands out, so classify it by prefix. */
-function addressType(address: string): AddressType {
- const a = address.toLowerCase();
- if (a.startsWith('bc1p') || a.startsWith('tb1p') || a.startsWith('bcrt1p')) return 'p2tr';
- if (a.startsWith('bc1') || a.startsWith('tb1') || a.startsWith('bcrt1')) return 'p2wpkh';
- if (a.startsWith('3') || a.startsWith('2')) return 'p2sh-p2wpkh';
- return 'p2pkh';
-}
-
-// ── backend ──────────────────────────────────────────────────────────────────────────────────────
-
-export class LndHubBackend extends BaseBackend {
- readonly kind: BackendKind = 'lndhub';
-
- // Custodial: receive and send over lightning, plus a deposit address on deployments that expose
- // /getbtc. No on-chain send, no coin control, no PSBT, no channels, no peers, no message signing —
- // the wallet does not hold the keys those would need.
- protected readonly capabilities: ReadonlySet = new Set([
- 'lightningReceive',
- 'lightningSend',
- 'onchainReceive',
- ]);
-
- private accessToken: string | null = null;
- /** In-flight login, shared by every caller that needs a token — the single-flight refresh. */
- private pendingLogin: Promise | null = null;
-
- constructor(private readonly config: LndHubConfig) {
- super();
- }
-
- // ── auth ───────────────────────────────────────────────────────────────────────────────────────
-
- /**
- * `POST /auth?type=auth {login, password}` → `{access_token, refresh_token}`. The refresh_token
- * grant (`type=refresh_token`) is deliberately not used: we hold the password, so a fresh login is
- * one round-trip either way and has one failure mode instead of two.
- */
- private async login(): Promise {
- const res = await httpJson({
- base: this.config.url,
- path: '/auth',
- method: 'POST',
- query: { type: 'auth' },
- body: { login: this.config.login, password: this.config.password },
- allowSelfSigned: this.config.allowSelfSigned,
- });
- if (res?.error || !res?.access_token) {
- const message = res?.message ?? (typeof res?.error === 'string' ? res.error : 'lndhub rejected the login');
- throw new BackendError(message, 401, 'LNDHUB_AUTH_FAILED');
- }
- this.accessToken = res.access_token;
- return res.access_token;
- }
-
- private async token(force = false): Promise {
- if (!force && this.accessToken) return this.accessToken;
- // Concurrent 401s all await the same login; whoever loses the race gets the winner's token.
- this.pendingLogin ??= this.login().finally(() => {
- this.pendingLogin = null;
- });
- return this.pendingLogin;
- }
-
- /** LNDHub's 200-with-`{error}` channel, folded back into the exception path. */
- private unwrap(payload: T): T {
- const body = payload as LndHubErrorBody | null;
- if (body && typeof body === 'object' && !Array.isArray(body) && body.error) {
- const message = body.message || (typeof body.error === 'string' ? body.error : 'lndhub returned an error');
- // code 1 is LNDHub's "bad auth"; some forks only put the phrase in the message.
- if (body.code === 1 || /bad auth/i.test(message)) {
- throw new BackendError(message, 401, 'LNDHUB_BAD_AUTH');
- }
- throw new BackendError(message, 502, body.code != null ? `LNDHUB_${body.code}` : undefined);
- }
- return payload;
- }
-
- private async call(req: LndHubCall): Promise {
- const send = async (token: string): Promise =>
- this.unwrap(
- await httpJson({
- base: this.config.url,
- path: req.path,
- method: req.method ?? 'GET',
- body: req.body,
- query: req.query,
- headers: { Authorization: `Bearer ${token}` },
- allowSelfSigned: this.config.allowSelfSigned,
- }),
- );
-
- try {
- return await send(await this.token());
- } catch (err) {
- // One retry, and only for auth — a second 401 with a token minted seconds ago is a real failure.
- if (!(err instanceof BackendError) || err.status !== 401) throw err;
- this.accessToken = null;
- return send(await this.token(true));
- }
- }
-
- // ── node / balances ────────────────────────────────────────────────────────────────────────────
-
- /**
- * Best-effort. `/getinfo` exists on BlueWallet-derived servers but not on every fork (Alby, LNbits),
- * so a failure degrades to an anonymous descriptor rather than breaking connect. Zeus sidesteps this
- * by reporting `supportsNodeInfo() = false` and never calling it.
- */
- override async getInfo(): Promise {
- let info: LndHubGetInfo | null = null;
- try {
- info = await this.call({ path: '/getinfo' });
- } catch {
- info = null;
- }
-
- const chain = info?.chains?.[0]?.network;
- const network: BitcoinNetwork =
- chain === 'testnet' || chain === 'signet' || chain === 'regtest'
- ? chain
- : info?.testnet === true
- ? 'testnet'
- : 'bitcoin';
-
- return {
- kind: this.kind,
- // The account is custodial — the pubkey, if any, belongs to the operator's node, not to us.
- pubkey: info?.identity_pubkey ?? null,
- alias: info?.alias ?? null,
- version: info?.version ?? null,
- network,
- blockHeight: info?.block_height ?? null,
- synced: info?.synced_to_chain ?? true,
- };
- }
-
- override async getBalances(): Promise {
- const res = await this.call({ path: '/balance' });
- return {
- // A custodial account has no on-chain balance of its own; deposits land in the lightning balance.
- onchainConfirmed: 0,
- onchainFrozen: 0,
- onchainUnconfirmed: 0,
- lightningBalance: num(res?.BTC?.AvailableBalance),
- // Inbound liquidity is the operator's problem and is never reported.
- lightningInbound: null,
- };
- }
-
- // ── on-chain ───────────────────────────────────────────────────────────────────────────────────
-
- /**
- * `/gettxs` mixes `paid_invoice` (lightning, outgoing) with `bitcoind_tx` (on-chain deposits copied
- * out of bitcoind's listtransactions). Only the latter belong here.
- */
- override async getTransactions(opts?: { limit?: number }): Promise {
- const txs = await this.fetchTxs(opts?.limit);
- return txs
- .filter((tx) => tx.type === 'bitcoind_tx' || (!!tx.txid && tx.payment_preimage === undefined))
- .map((tx) => ({
- txid: tx.txid ?? '',
- // `amount` here is BTC as a float, not sats. Round after scaling — 0.1 BTC is not exact.
- amount: Math.round(num(tx.amount) * 1e8),
- feeSats: null,
- blockHeight: tx.blockheight ?? null,
- timestamp: tx.time ?? (tx.timestamp != null ? num(tx.timestamp) : null),
- confirmations: tx.confirmations ?? 0,
- label: null,
- destAddresses: tx.address ? [tx.address] : [],
- rawHex: null,
- }));
- }
-
- /**
- * `/getbtc` returns the account's single deposit address as a one-element array (Zeus reads
- * `data[0].address`, InvoicesStore.ts:620). It is static per account, so `peek` is meaningless and
- * the requested address type is ignored — the operator chose it. On the deployments that hand back an
- * empty array until an address has been allocated, `/newbtc` allocates one.
- */
- override async getNewAddress(_req?: NewAddressRequest): Promise<{ address: string; type: AddressType }> {
- let address = await this.fetchBtcAddress();
- if (!address) {
- await this.call({ path: '/newbtc', method: 'POST', body: {} });
- address = await this.fetchBtcAddress();
- }
- if (!address) {
- throw new BackendError('lndhub server does not offer on-chain deposits', 501, 'NOT_SUPPORTED');
- }
- return { address, type: addressType(address) };
- }
-
- private async fetchBtcAddress(): Promise {
- const res = await this.call({ path: '/getbtc' });
- if (Array.isArray(res)) return res[0]?.address ?? '';
- return res?.address ?? '';
- }
-
- // ── lightning ──────────────────────────────────────────────────────────────────────────────────
-
- override async getInvoices(opts?: { limit?: number }): Promise {
- const res = await this.call({
- path: '/getuserinvoices',
- query: { limit: opts?.limit },
- });
- return (Array.isArray(res) ? res : []).map((inv) => this.toInvoice(inv));
- }
-
- override async createInvoice(req: CreateInvoiceRequest): Promise {
- if (req.preimage) return this.notSupported('custom preimages');
- if (req.isAmp) return this.notSupported('AMP invoices');
- // LNDHub answers a zero-amount invoice request with "Bad arguments" (Zeus special-cases the string
- // in InvoicesStore.ts:425); reject it here with something legible instead.
- if (!req.amountMsat || req.amountMsat === '0') {
- throw new BackendError('lndhub requires an invoice amount', 400, 'AMOUNT_REQUIRED');
- }
- const sats = msatToSats(req.amountMsat, 'amountMsat');
- // `expirySeconds` and `private` have no equivalent — the server picks both (Zeus:
- // supportsSettingInvoiceExpiration() = false).
- const res = await this.call({
- path: '/addinvoice',
- method: 'POST',
- body: { amt: String(sats), memo: req.memo ?? '' },
- });
-
- const bolt11 = res.payment_request ?? res.pay_req ?? '';
- let paymentHash = bytesToHex(res.r_hash ?? res.payment_hash);
- // A few forks omit r_hash on /addinvoice. The hash is already in the invoice we were just handed, so
- // read it locally rather than spending a second authenticated round-trip — and a second failure mode
- // — on `/decodeinvoice`, which those same forks are the least likely to implement.
- if (!paymentHash && bolt11) {
- paymentHash = decodeBolt11(bolt11).paymentHash;
- }
-
- const createdAt = res.timestamp != null ? num(res.timestamp) : Math.floor(Date.now() / 1000);
- return {
- paymentHash,
- bolt11,
- amountMsat: satsToMsat(sats),
- amountPaidMsat: null,
- memo: req.memo ?? res.description ?? null,
- state: 'open',
- createdAt,
- expiresAt: res.expire_time ? createdAt + res.expire_time : null,
- settledAt: null,
- preimage: null,
- isKeysend: false,
- isAmp: false,
- };
- }
-
- /**
- * LNDHub has no lookup endpoint — Zeus inherits LND's `/v1/invoice/:r_hash`, which 404s here. Scan
- * the invoice list instead. Bounded at 200 entries: an older invoice reports as not found rather
- * than paging the whole history on every poll.
- */
- override async lookupInvoice(paymentHash: string): Promise {
- const wanted = paymentHash.toLowerCase();
- const res = await this.call({ path: '/getuserinvoices', query: { limit: 200 } });
- const found = (Array.isArray(res) ? res : []).find((inv) => bytesToHex(inv.r_hash ?? inv.payment_hash) === wanted);
- return found ? this.toInvoice(found) : null;
- }
-
- /**
- * Zeus decodes BOLT11 client-side (Bolt11Utils) and never calls this endpoint. The sidecar has no
- * decoder, and the server's `/decodeinvoice?invoice=` answers with LND's payreq shape, which maps
- * onto DecodedInvoice one-for-one.
- */
- override async decodeInvoice(bolt11: string): Promise {
- const res = await this.call({ path: '/decodeinvoice', query: { invoice: bolt11 } });
- const msat = res.num_msat != null ? String(num(res.num_msat)) : null;
- return {
- bolt11,
- paymentHash: res.payment_hash ?? '',
- amountMsat: msat ?? (res.num_satoshis != null ? satsToMsat(num(res.num_satoshis)) : null),
- description: res.description ?? null,
- destination: res.destination ?? '',
- timestamp: num(res.timestamp),
- expiry: res.expiry != null ? num(res.expiry) : 3600,
- cltvExpiry: res.cltv_expiry != null ? num(res.cltv_expiry) : null,
- routeHints: Array.isArray(res.route_hints) && res.route_hints.length > 0,
- features: Object.values(res.features ?? {}).map((f) => f?.name ?? ''),
- };
- }
-
- override async getPayments(opts?: { limit?: number }): Promise {
- const txs = await this.fetchTxs(opts?.limit);
- return txs
- .filter((tx) => tx.type === 'paid_invoice' || tx.payment_preimage !== undefined)
- .map((tx) => {
- // LNDHub's User.getTxs() sets `value = payment_route.total_amt + payment_route.total_fees`,
- // so the destination amount is `value - fee`. Both are satoshis.
- const feeSats = num(tx.fee);
- const amountSats = Math.max(num(tx.value) - feeSats, 0);
- return {
- paymentHash: bytesToHex(tx.payment_hash),
- preimage: bytesToHex(tx.payment_preimage) || null,
- amountMsat: satsToMsat(amountSats),
- feeMsat: satsToMsat(feeSats),
- // /gettxs only records payments that went through; failures are never persisted.
- status: 'succeeded' as const,
- createdAt: num(tx.timestamp ?? tx.time),
- destination: null,
- memo: tx.memo ?? tx.description ?? null,
- failureReason: null,
- };
- });
- }
-
- /**
- * `POST /payinvoice {invoice, amount}` — `amount` is satoshis and only consulted for a zero-amount
- * invoice. Fee limits and timeouts are the operator's policy (Zeus: supportsCustomFeeLimit() =
- * false), so feeLimitMsat / feeLimitPercent / timeoutSeconds are accepted and ignored.
- */
- override async payInvoice(req: PayInvoiceRequest): Promise {
- const amountSats = req.amountMsat ? msatToSats(req.amountMsat, 'amountMsat') : undefined;
- const res = await this.call({
- path: '/payinvoice',
- method: 'POST',
- body: { invoice: req.bolt11, amount: amountSats },
- });
-
- const route = res.payment_route ?? {};
- const feeMsat =
- route.total_fees_msat != null ? String(num(route.total_fees_msat)) : satsToMsat(num(route.total_fees));
- // Prefer the invoice's own amount: `total_amt` is ambiguous across forks about whether fees are
- // included, whereas the decoded payreq is not.
- const decodedMsat =
- res.decoded?.num_msat != null
- ? String(num(res.decoded.num_msat))
- : res.decoded?.num_satoshis != null
- ? satsToMsat(num(res.decoded.num_satoshis))
- : null;
- const routedMsat =
- route.total_amt_msat != null ? String(num(route.total_amt_msat)) : satsToMsat(num(route.total_amt));
-
- const preimage = bytesToHex(res.payment_preimage) || null;
- // Hard failures arrive as `{error, message}` and have already thrown in unwrap(). `payment_error`
- // is LND's soft channel — a routing failure, reported as a failed Payment rather than an exception.
- const failed = !!res.payment_error;
-
- return {
- paymentHash: bytesToHex(res.payment_hash) || res.decoded?.payment_hash || '',
- preimage,
- amountMsat: decodedMsat ?? req.amountMsat ?? routedMsat,
- feeMsat,
- status: failed ? 'failed' : 'succeeded',
- createdAt: Math.floor(Date.now() / 1000),
- destination: res.decoded?.destination ?? null,
- memo: res.decoded?.description ?? null,
- failureReason: failed ? (res.payment_error ?? null) : null,
- };
- }
-
- // ── shared ─────────────────────────────────────────────────────────────────────────────────────
-
- private async fetchTxs(limit?: number): Promise {
- const res = await this.call({ path: '/gettxs', query: { limit } });
- return Array.isArray(res) ? res : [];
- }
-
- private toInvoice(inv: LndHubUserInvoice): Invoice {
- const createdAt = num(inv.timestamp);
- const expiresAt = inv.expire_time ? createdAt + inv.expire_time : null;
- const paid = inv.ispaid === true;
- // LNDHub has no cancel and no hold invoices, so 'canceled' and 'accepted' are unreachable; an
- // unpaid invoice past its expiry is reported as expired rather than left open.
- const state: InvoiceState = paid
- ? 'settled'
- : expiresAt != null && expiresAt < Math.floor(Date.now() / 1000)
- ? 'expired'
- : 'open';
-
- const amountMsat = inv.amt != null ? satsToMsat(num(inv.amt)) : null;
- const paidMsat =
- inv.amt_paid_msat != null
- ? String(num(inv.amt_paid_msat))
- : inv.amt_paid_sat != null
- ? satsToMsat(num(inv.amt_paid_sat))
- : paid
- ? amountMsat
- : null;
-
- return {
- paymentHash: bytesToHex(inv.r_hash ?? inv.payment_hash),
- bolt11: inv.payment_request ?? inv.pay_req ?? '',
- amountMsat,
- amountPaidMsat: paidMsat,
- memo: inv.description ?? inv.memo ?? null,
- state,
- createdAt,
- expiresAt,
- // The settle time is not recorded upstream; only the ispaid flag is.
- settledAt: inv.settled_at ?? null,
- // Preimages of received payments stay with the custodian.
- preimage: null,
- isKeysend: false,
- isAmp: false,
- };
- }
-}
diff --git a/src/servers/sidecar/wallet/backends/nwc.ts b/src/servers/sidecar/wallet/backends/nwc.ts
deleted file mode 100644
index 478443f3..00000000
--- a/src/servers/sidecar/wallet/backends/nwc.ts
+++ /dev/null
@@ -1,408 +0,0 @@
-// Nostr Wallet Connect (NIP-47) — port of Zeus's backends/NostrWalletConnect.ts.
-//
-// A NWC connection is a capability grant, not a node: a `nostr+walletconnect://` URI carries a wallet
-// service pubkey, one or more relays and a shared secret. Every operation is an encrypted nostr event
-// round-tripped through a relay, so the whole surface is lightning-only and the wallet decides which
-// commands it will honour.
-//
-// CAPABILITIES ARE DYNAMIC. This is the one backend whose `capabilities` set is not a constant: the
-// wallet advertises its methods in the `get_info` response (falling back to the kind-13194 info event),
-// and the set is rebuilt from that list on connect. Zeus hardcodes `supportsKeysend() = false` even
-// though plenty of NWC wallets do keysend; here `keysend` appears iff the wallet lists `pay_keysend`.
-// Before the first connect the set holds the NIP-47 baseline (make_invoice + pay_invoice), because
-// `supports()` is synchronous and cannot await the handshake.
-//
-// Differences from Zeus, all deliberate:
-//
-// 1. TRANSPORT. Zeus drives `NostrWebLNProvider` from `@getalby/sdk`, a WebLN shim that silently
-// converts sats↔msats. This uses `NWCClient` from the same package (v8), which speaks raw NIP-47
-// — every amount in and out is millisatoshis, matching this contract's msat-as-string rule with
-// no lossy hop through sats. Bun/Node 22 both provide the global WebSocket that nostr-tools needs.
-// 2. lookupInvoice. Zeus passes `Base64Utils.hexToBase64(r_hash)` (NostrWalletConnect.ts:78) — NIP-47
-// specifies payment_hash as **hex**, so that call cannot match. Hex is sent here.
-// 3. INVOICE/PAYMENT SPLIT. Zeus calls `list_transactions` and filters `type` client-side, twice.
-// NIP-47 takes `type` as a request parameter; the filter is pushed to the wallet, with the
-// client-side filter kept as a guard for wallets that ignore it.
-// 4. payInvoice. NIP-47 answers a payment with `{preimage, fees_paid}` and nothing else, so Zeus
-// returns a Payment with no hash. The payment hash is sha256(preimage) by definition, so it is
-// computed locally; the amount is filled from a best-effort `lookup_invoice` when the wallet
-// supports it, otherwise from the request.
-// 5. decodeInvoice is LOCAL. NIP-47 has no decode command, so this is the one operation that never
-// touches the relay: `../bolt11` (ported from Zeus's Bolt11Utils) decodes in-process. On-chain,
-// channels, peers and message signing do stay at BaseBackend's 501 — NIP-47 `sign_message` signs
-// with the node key, which is not what the contract's signMessage means.
-
-import { createHash } from 'node:crypto';
-import { Nip47Error, Nip47TimeoutError, NWCClient, type Nip47Method, type Nip47Transaction } from '@getalby/sdk/nwc';
-import { decodeBolt11 } from '../bolt11';
-import {
- BackendError,
- type Balances,
- type BackendKind,
- type BitcoinNetwork,
- type Capability,
- type CreateInvoiceRequest,
- type DecodedInvoice,
- type Invoice,
- type InvoiceState,
- type KeysendRequest,
- type NodeInfo,
- type PayInvoiceRequest,
- type Payment,
- type PaymentStatus,
-} from '../types';
-import { BaseBackend } from './base';
-
-export type NwcConfig = {
- /** A `nostr+walletconnect://?relay=…&secret=…` URI. */
- connectionUri: string;
-};
-
-// ── upstream wire shapes ─────────────────────────────────────────────────────────────────────────
-
-/**
- * The SDK types `state` as required, but it was added late to NIP-47 and pre-1.0 wallets omit it —
- * their only settlement signal is a non-zero `settled_at`. Amounts are millisatoshis throughout.
- */
-type NwcTransaction = Omit & { state?: Nip47Transaction['state'] };
-
-/** NIP-47 error codes, mapped onto HTTP so routes.ts can answer honestly. */
-const ERROR_STATUS: Record = {
- NOT_IMPLEMENTED: 501,
- UNSUPPORTED_ENCRYPTION: 501,
- UNAUTHORIZED: 403,
- RESTRICTED: 403,
- INSUFFICIENT_BALANCE: 402,
- QUOTA_EXCEEDED: 402,
- PAYMENT_FAILED: 502,
- NOT_FOUND: 404,
- RATE_LIMITED: 429,
- INTERNAL: 502,
- OTHER: 502,
-};
-
-/** The keysend TLV that carries a human-readable message (the de-facto standard record). */
-const KEYSEND_MESSAGE_TLV = 34349334;
-
-// ── helpers ──────────────────────────────────────────────────────────────────────────────────────
-
-const now = (): number => Math.floor(Date.now() / 1000);
-
-/** payment_hash = sha256(preimage) — how NIP-47 lets us recover a hash it never sends back. */
-function hashFromPreimage(preimage: string | undefined): string {
- if (!preimage) return '';
- return createHash('sha256').update(Buffer.from(preimage, 'hex')).digest('hex');
-}
-
-/** msat decimal string → the integer msats NIP-47 wants, with the JS-safe range enforced. */
-function toMsatNumber(msat: string, field: string): number {
- const value = BigInt(msat);
- if (value < 0n || value > BigInt(Number.MAX_SAFE_INTEGER)) {
- throw new BackendError(`${field}=${msat}msat is out of range for NIP-47`, 400, 'BAD_AMOUNT');
- }
- return Number(value);
-}
-
-function toBackendError(err: unknown, op: string): BackendError {
- if (err instanceof BackendError) return err;
- if (err instanceof Nip47TimeoutError) {
- return new BackendError(`nwc ${op} timed out: ${err.message}`, 504, err.code);
- }
- if (err instanceof Nip47Error) {
- return new BackendError(`nwc ${op} failed: ${err.message}`, ERROR_STATUS[err.code] ?? 502, err.code);
- }
- return new BackendError(`nwc ${op} failed: ${String(err)}`, 502, 'NWC_ERROR');
-}
-
-function toInvoiceState(tx: NwcTransaction): InvoiceState {
- if (tx.state === 'settled') return 'settled';
- if (tx.state === 'accepted') return 'accepted';
- // NIP-47 has no explicit cancel; a hold invoice that was released comes back as failed.
- if (tx.state === 'failed') return 'canceled';
- if (tx.settled_at) return 'settled';
- if (tx.expires_at && tx.expires_at < now()) return 'expired';
- return 'open';
-}
-
-function toPaymentStatus(tx: NwcTransaction): PaymentStatus {
- if (tx.state === 'settled') return 'succeeded';
- if (tx.state === 'failed') return 'failed';
- if (tx.state) return 'pending';
- return tx.settled_at ? 'succeeded' : 'pending';
-}
-
-function toInvoice(tx: NwcTransaction): Invoice {
- const amountMsat = tx.amount != null ? String(tx.amount) : null;
- const state = toInvoiceState(tx);
- return {
- paymentHash: tx.payment_hash ?? '',
- bolt11: tx.invoice ?? '',
- amountMsat,
- amountPaidMsat: state === 'settled' ? amountMsat : null,
- memo: tx.description || null,
- state,
- createdAt: tx.created_at ?? now(),
- expiresAt: tx.expires_at || null,
- settledAt: tx.settled_at || null,
- preimage: tx.preimage || null,
- // An incoming payment with no BOLT11 attached to it can only have been a keysend.
- isKeysend: !tx.invoice && !!tx.payment_hash,
- // NIP-47 has no AMP concept.
- isAmp: false,
- };
-}
-
-function toPayment(tx: NwcTransaction): Payment {
- return {
- paymentHash: tx.payment_hash ?? '',
- preimage: tx.preimage || null,
- amountMsat: String(tx.amount ?? 0),
- feeMsat: String(tx.fees_paid ?? 0),
- status: toPaymentStatus(tx),
- createdAt: tx.created_at ?? now(),
- // The wallet never names the payee; only the invoice it paid.
- destination: null,
- memo: tx.description || null,
- failureReason: null,
- };
-}
-
-// ── backend ──────────────────────────────────────────────────────────────────────────────────────
-
-export class NwcBackend extends BaseBackend {
- readonly kind: BackendKind = 'nwc';
-
- /**
- * Mutable behind a ReadonlySet view — `capabilities` and `caps` are the same object, so rebuilding
- * the set after the get_info handshake is visible through `supports()` without reassigning a
- * readonly field. Seeded with the NIP-47 baseline until the wallet says otherwise.
- */
- private readonly caps = new Set(['lightningReceive', 'lightningSend']);
- protected readonly capabilities: ReadonlySet = this.caps;
-
- private client: NWCClient | null = null;
- private connecting: Promise | null = null;
- private methods: ReadonlySet = new Set();
-
- constructor(private readonly config: NwcConfig) {
- super();
- }
-
- // ── connection ─────────────────────────────────────────────────────────────────────────────────
-
- /** Single-flight connect: the relay subscription and the get_info handshake happen exactly once. */
- private async connect(): Promise {
- if (this.client) return this.client;
- this.connecting ??= this.open().finally(() => {
- this.connecting = null;
- });
- return this.connecting;
- }
-
- private async open(): Promise {
- let client: NWCClient;
- try {
- client = new NWCClient({ nostrWalletConnectUrl: this.config.connectionUri });
- } catch (err) {
- throw new BackendError(`invalid NWC connection URI: ${String(err)}`, 400, 'BAD_CONFIG');
- }
-
- try {
- const info = await client.getInfo();
- this.applyMethods(info.methods);
- } catch (err) {
- // Wallets that do not implement get_info still publish a kind-13194 info event listing their
- // capabilities. If neither is reachable the connection itself is broken — surface that.
- try {
- const service = await client.getWalletServiceInfo();
- this.applyMethods(service.capabilities.filter((cap): cap is Nip47Method => cap !== 'notifications'));
- } catch {
- client.close();
- throw toBackendError(err, 'connect');
- }
- }
-
- this.client = client;
- return client;
- }
-
- /** Capability negotiation: the whole point of NWC's get_info. */
- private applyMethods(methods: Nip47Method[] | undefined): void {
- if (!methods?.length) return;
- this.methods = new Set(methods);
- this.caps.clear();
- if (this.methods.has('make_invoice')) this.caps.add('lightningReceive');
- if (this.methods.has('pay_invoice')) this.caps.add('lightningSend');
- if (this.methods.has('pay_keysend')) this.caps.add('keysend');
- }
-
- private async run(op: string, fn: (client: NWCClient) => Promise): Promise {
- const client = await this.connect();
- try {
- return await fn(client);
- } catch (err) {
- throw toBackendError(err, op);
- }
- }
-
- /** Drop the relay subscription. Not part of WalletBackend; the factory calls it on teardown. */
- close(): void {
- this.client?.close();
- this.client = null;
- this.methods = new Set();
- }
-
- // ── node / balances ────────────────────────────────────────────────────────────────────────────
-
- override async getInfo(): Promise {
- const info = await this.run('get_info', (client) => client.getInfo());
- const network = info.network === 'mainnet' || !info.network ? 'bitcoin' : info.network;
- return {
- kind: this.kind,
- // The pubkey belongs to the wallet service's node, not to this connection.
- pubkey: info.pubkey || null,
- alias: info.alias || null,
- // NIP-47 carries no implementation version.
- version: null,
- network: (['bitcoin', 'testnet', 'signet', 'regtest'] as const).includes(network as BitcoinNetwork)
- ? (network as BitcoinNetwork)
- : 'bitcoin',
- blockHeight: info.block_height ?? null,
- // A wallet that answers at all is by definition usable; there is no sync flag in NIP-47.
- synced: true,
- };
- }
-
- override async getBalances(): Promise {
- const res = await this.run('get_balance', (client) => client.getBalance());
- return {
- // NWC is lightning-only; there is no on-chain side to report.
- onchainConfirmed: 0,
- onchainFrozen: 0,
- onchainUnconfirmed: 0,
- // `balance` is msats (the WebLN shim Zeus uses divides by 1000 before the UI ever sees it).
- lightningBalance: Math.floor((res.balance ?? 0) / 1000),
- lightningInbound: null,
- };
- }
-
- // ── lightning ──────────────────────────────────────────────────────────────────────────────────
-
- override async getInvoices(opts?: { limit?: number }): Promise {
- const res = await this.run('list_transactions', (client) =>
- client.listTransactions({ type: 'incoming', limit: opts?.limit, unpaid: true }),
- );
- // The `type` filter is a request parameter, but older wallets ignore it — filter again.
- return (res.transactions ?? []).filter((tx) => tx.type !== 'outgoing').map(toInvoice);
- }
-
- override async createInvoice(req: CreateInvoiceRequest): Promise {
- if (!this.caps.has('lightningReceive')) return this.notSupported('lightning receive');
- // No NIP-47 wallet accepts a caller-supplied preimage or an AMP invoice, and `private` has no
- // equivalent — the wallet picks its own route hints.
- if (req.preimage) return this.notSupported('custom preimages');
- if (req.isAmp) return this.notSupported('AMP invoices');
- if (!req.amountMsat || req.amountMsat === '0') {
- throw new BackendError('nwc requires an invoice amount', 400, 'AMOUNT_REQUIRED');
- }
- const amount = toMsatNumber(req.amountMsat, 'amountMsat');
-
- const tx = await this.run('make_invoice', (client) =>
- client.makeInvoice({ amount, description: req.memo, expiry: req.expirySeconds }),
- );
- return toInvoice(tx);
- }
-
- override async lookupInvoice(paymentHash: string): Promise {
- if (!this.methods.size || this.methods.has('lookup_invoice')) {
- const tx = await this.lookup({ payment_hash: paymentHash });
- return tx ? toInvoice(tx) : null;
- }
- return this.notSupported('invoice lookup');
- }
-
- /**
- * Purely local — no relay round-trip, and it works while the wallet is unreachable. The invoice is
- * self-describing, so there is nothing the wallet service could add beyond what the bytes already say.
- */
- override async decodeInvoice(bolt11: string): Promise {
- return decodeBolt11(bolt11);
- }
-
- override async getPayments(opts?: { limit?: number }): Promise {
- const res = await this.run('list_transactions', (client) =>
- client.listTransactions({ type: 'outgoing', limit: opts?.limit, unpaid_outgoing: true }),
- );
- return (res.transactions ?? []).filter((tx) => tx.type !== 'incoming').map(toPayment);
- }
-
- override async payInvoice(req: PayInvoiceRequest): Promise {
- if (!this.caps.has('lightningSend')) return this.notSupported('lightning send');
- // Fee limits and timeouts are the wallet's own budget policy; NIP-47 has no field for either.
- const amount = req.amountMsat ? toMsatNumber(req.amountMsat, 'amountMsat') : undefined;
- const res = await this.run('pay_invoice', (client) => client.payInvoice({ invoice: req.bolt11, amount }));
-
- const paymentHash = hashFromPreimage(res.preimage);
- // pay_invoice returns only {preimage, fees_paid}. Recover the rest from the wallet's own record
- // when it keeps one — best effort, never fatal, since the payment has already settled.
- const record = paymentHash ? await this.lookupQuietly({ payment_hash: paymentHash }) : null;
-
- return {
- paymentHash,
- preimage: res.preimage || null,
- amountMsat: record?.amount != null ? String(record.amount) : (req.amountMsat ?? '0'),
- feeMsat: String(res.fees_paid ?? record?.fees_paid ?? 0),
- // A NIP-47 pay_invoice that resolves has succeeded; a failure arrives as a Nip47WalletError.
- status: 'succeeded',
- createdAt: record?.created_at ?? now(),
- destination: null,
- memo: record?.description || null,
- failureReason: null,
- };
- }
-
- override async sendKeysend(req: KeysendRequest): Promise {
- if (!this.caps.has('keysend')) return this.notSupported('keysend');
- const amount = toMsatNumber(req.amountMsat, 'amountMsat');
- // NIP-47 carries TLV values as hex.
- const tlvRecords = req.message
- ? [{ type: KEYSEND_MESSAGE_TLV, value: Buffer.from(req.message, 'utf8').toString('hex') }]
- : undefined;
-
- const res = await this.run('pay_keysend', (client) =>
- client.payKeysend({ pubkey: req.destination, amount, tlv_records: tlvRecords }),
- );
- return {
- paymentHash: hashFromPreimage(res.preimage),
- preimage: res.preimage || null,
- amountMsat: req.amountMsat,
- feeMsat: String(res.fees_paid ?? 0),
- status: 'succeeded',
- createdAt: now(),
- destination: req.destination,
- memo: req.message ?? null,
- failureReason: null,
- };
- }
-
- // ── shared ─────────────────────────────────────────────────────────────────────────────────────
-
- private async lookup(request: { payment_hash?: string; invoice?: string }): Promise {
- try {
- return await this.run('lookup_invoice', (client) => client.lookupInvoice(request));
- } catch (err) {
- // A wallet that has never seen the hash answers NOT_FOUND; that is an absence, not a failure.
- if (err instanceof BackendError && err.status === 404) return null;
- throw err;
- }
- }
-
- private async lookupQuietly(request: { payment_hash?: string; invoice?: string }): Promise {
- if (this.methods.size && !this.methods.has('lookup_invoice')) return null;
- try {
- return await this.lookup(request);
- } catch {
- return null;
- }
- }
-}
diff --git a/src/servers/sidecar/wallet/backends/onchain.ts b/src/servers/sidecar/wallet/backends/onchain.ts
deleted file mode 100644
index 1f86e329..00000000
--- a/src/servers/sidecar/wallet/backends/onchain.ts
+++ /dev/null
@@ -1,822 +0,0 @@
-// The native on-chain wallet backend.
-//
-// This is the server-side replacement for Zeus's two embedded backends. EmbeddedLND
-// (backends/EmbeddedLND.ts) and LdkNode (backends/LdkNode.ts) are thin JS shims over React Native
-// native modules — `lndmobile`, `ldk-node-rn` — that bundle an actual node into the app process.
-// Neither exists off a phone, so neither can be ported into a Bun sidecar. Instead this backend is a
-// real wallet in its own right: it derives addresses from a BIP32 account xpub, reads the chain through
-// an injected WalletChainSource (chain-source.ts), and builds/signs its own transactions with
-// bitcoinjs-lib (psbt.ts).
-//
-// It owns the KEYS and the MONEY: derivation, the snapshot cache, coin selection, PSBT construction,
-// signing. It owns no HTTP at all. Which indexer answers — a public Esplora, the owner's own node behind
-// NBXplorer — is a constructor argument, and nothing below this line knows the difference.
-//
-// WATCH-ONLY WHILE LOCKED is the load-bearing design property. Everything a UI polls —
-// getInfo / getBalances / getTransactions / getNewAddress / getUtxos / estimateFees — is derived from
-// the account XPUB and public chain data, so it works with the wallet locked and no key material in
-// memory. `signer.withRoot` is reached from exactly two methods, sendCoins and signMessage, and both
-// fail fast with WalletLockedError before doing any work. Nothing else in this file touches the signer.
-//
-// There is no lightning here at all: the capability set omits every lightning flag, so invoices,
-// payments, channels and peers all fall through to BaseBackend's 501.
-
-import type { WalletChainSnapshot } from 'officerdb';
-import { HDKey } from '@scure/bip32';
-import * as bitcoin from 'bitcoinjs-lib';
-import { toXOnly } from 'bitcoinjs-lib/src/psbt/bip371';
-import * as ecc from '@bitcoinerlab/secp256k1';
-import {
- mapLimit,
- MAX_SCAN_INDEX,
- REQUEST_CONCURRENCY,
- type AddressEntry,
- type ChainIndex,
- type ScanContext,
- type ScannedAddress,
- type WalletChainSource,
-} from '../chain-source';
-import {
- buildPsbt,
- coinTypeFor,
- initEcc,
- networkFor,
- outputScriptFor,
- scriptType,
- selectCoins,
- signAndFinalize,
- type PsbtInputSource,
- type PsbtOutputSpec,
- type SpendableUtxo,
-} from '../psbt';
-import {
- BackendError,
- WalletLockedError,
- type AddressType,
- type Balances,
- type BackendKind,
- type BitcoinNetwork,
- type Capability,
- type FeeEstimates,
- type NewAddressRequest,
- type NodeInfo,
- type OnchainTx,
- type RescanOptions,
- type RescanState,
- type SendCoinsRequest,
- type SendCoinsResult,
- type SignMessageResult,
- type SyncState,
- type Utxo,
- type VerifyMessageResult,
-} from '../types';
-import { BaseBackend } from './base';
-
-// ── the signer boundary ──────────────────────────────────────────────────────────────────────────
-
-/**
- * The wallet's key custodian, implemented by keys.ts and injected here.
- *
- * This backend never sees a seed, a mnemonic, a passphrase or a file path. It receives a root HDKey for
- * the duration of one synchronous callback and nothing more, which is what keeps the watch-only path
- * genuinely key-free rather than key-free by convention.
- *
- * `withRoot` MUST throw `WalletLockedError` when the wallet is locked, and MUST NOT be async — an async
- * borrow would pin the root in memory across arbitrary awaits.
- */
-export interface WalletSigner {
- isUnlocked(): boolean;
- withRoot(fn: (root: HDKey) => T): T;
-}
-
-// ── the persistence boundary ─────────────────────────────────────────────────────────────────────
-
-/**
- * Durable storage for the last snapshot this backend read off the chain. Injected the same way the
- * signer is, and for the same reason: this file stays a pure wallet with no idea which database it is
- * attached to, or that it has a wallet id at all. resolve.ts binds the real implementation.
- *
- * Every method is best-effort by contract. A cache that is unreachable, corrupt or empty must degrade
- * to today's behaviour — a slow first load — and must never fail a wallet request.
- */
-export interface ChainCacheStore {
- load(): Promise<{ snapshot: WalletChainSnapshot | null; syncedAt: Date | null; lastError: string | null } | null>;
- save(snapshot: WalletChainSnapshot): Promise;
- recordError(message: string): Promise;
-}
-
-// ── extended key parsing ─────────────────────────────────────────────────────────────────────────
-
-/**
- * SLIP-132 version bytes. @scure/bip32 refuses an extended key whose version does not match the
- * `versions` it was handed, so the prefix has to be recognised before the key can be imported. Wallets
- * export the purpose-tagged forms (zpub for BIP84, ypub for BIP49, vpub/upub on testnet) as often as
- * they export a plain xpub, and all of them are the same key with different four leading bytes.
- */
-const XPUB_VERSIONS: Record = {
- xpub: { public: 0x0488b21e, private: 0x0488ade4 },
- ypub: { public: 0x049d7cb2, private: 0x049d7878 },
- zpub: { public: 0x04b24746, private: 0x04b2430c },
- tpub: { public: 0x043587cf, private: 0x04358394 },
- upub: { public: 0x044a5262, private: 0x044a4e28 },
- vpub: { public: 0x045f1cf6, private: 0x045f18bc },
-};
-
-function parseAccountXpub(key: string): HDKey {
- const prefix = key.slice(0, 4).toLowerCase();
- const versions = XPUB_VERSIONS[prefix];
- if (!versions) throw new BackendError(`unrecognised extended key prefix '${prefix}'`, 400, 'BAD_XPUB');
- try {
- return HDKey.fromExtendedKey(key, versions);
- } catch (err) {
- throw new BackendError(`could not parse the account extended key: ${String(err)}`, 400, 'BAD_XPUB');
- }
-}
-
-// ── derivation ───────────────────────────────────────────────────────────────────────────────────
-
-/** BIP44 purpose per script type: 44' legacy, 49' wrapped segwit, 84' native segwit, 86' taproot. */
-const PURPOSE: Record = {
- p2pkh: 44,
- 'p2sh-p2wpkh': 49,
- p2wpkh: 84,
- p2tr: 86,
-};
-
-/** Preference order when the caller does not name a script type. Native segwit first. */
-const TYPE_PREFERENCE: readonly AddressType[] = ['p2wpkh', 'p2tr', 'p2sh-p2wpkh', 'p2pkh'];
-
-type Account = {
- type: AddressType;
- node: HDKey;
- /** The extended key exactly as it was given. Wallet-level chain sources index by this string. */
- accountXpub: string;
- /** Account-level path from the wallet root, e.g. `m/84'/0'/0'`. */
- basePath: string;
-};
-
-/**
- * One coherent read of the chain: the address scan and everything derived from it, taken together.
- *
- * Balances, UTXOs and history used to be fetched by three separate endpoints on top of a shared scan,
- * which meant the three queries a wallet screen fires on mount could each observe a different moment.
- * Building them as one snapshot costs the same requests — collectUtxos only asks about funded addresses
- * and collectTxs only about touched ones — and makes the whole thing a single unit to cache, serve stale
- * and persist.
- */
-type Snapshot = {
- /** Unix ms the chain was read. Survives a restart: a restored snapshot carries its original time. */
- at: number;
- tipHeight: number;
- addresses: ScannedAddress[];
- utxos: SpendableUtxo[];
- txs: OnchainTx[];
-};
-
-// ── tuning ───────────────────────────────────────────────────────────────────────────────────────
-
-/** How long a snapshot is served without kicking off a refresh behind it. */
-const SCAN_TTL_MS = 30_000;
-
-const DEFAULT_TX_LIMIT = 100;
-
-// ── the backend ──────────────────────────────────────────────────────────────────────────────────
-
-export type OnchainBackendOptions = {
- chain: WalletChainSource;
- network: BitcoinNetwork;
- /**
- * The account-level extended public key. A bare string is taken as the BIP84 (p2wpkh) account; pass a
- * map to enable more than one script type, e.g. `{ p2wpkh: 'zpub…', p2tr: 'xpub…' }`.
- */
- accountXpub: string | Partial>;
- signer: WalletSigner;
- /** Omit for a backend that should hold its chain view in memory only — tests do. */
- cache?: ChainCacheStore;
-};
-
-export class OnchainBackend extends BaseBackend {
- readonly kind: BackendKind = 'onchain';
-
- protected readonly capabilities: ReadonlySet = new Set([
- 'onchainReceive',
- 'onchainSend',
- 'coinControl',
- 'psbt',
- 'sweep',
- 'signMessage',
- ]);
-
- private readonly chain: WalletChainSource;
- private readonly network: BitcoinNetwork;
- private readonly btcNetwork: bitcoin.Network;
- private readonly signer: WalletSigner;
- private readonly accounts: Map;
- private readonly defaultType: AddressType;
-
- /** Derivation is pure EC math over a fixed xpub, so every address is derived at most once. */
- private readonly derived = new Map();
-
- /** In-memory issuance high-water mark per `type:chain`, so consecutive getNewAddress calls advance.
- * Deliberately not persisted: after a restart the first unused address is recomputed from the chain,
- * which is correct as soon as an issued address has actually been paid. */
- private readonly issued = new Map();
-
- private readonly cache: ChainCacheStore | null;
-
- private current: Snapshot | null = null;
- private inflight: Promise | null = null;
- /** Memoised so concurrent first reads do one cache load between them, not one each. */
- private hydration: Promise | null = null;
- private lastError: string | null = null;
-
- constructor(opts: OnchainBackendOptions) {
- super();
- initEcc();
- this.chain = opts.chain;
- this.network = opts.network;
- this.btcNetwork = networkFor(opts.network);
- this.signer = opts.signer;
- this.cache = opts.cache ?? null;
-
- const coin = coinTypeFor(opts.network);
- const raw = typeof opts.accountXpub === 'string' ? { p2wpkh: opts.accountXpub } : opts.accountXpub;
-
- this.accounts = new Map();
- for (const type of TYPE_PREFERENCE) {
- const xpub = raw[type];
- if (!xpub) continue;
- this.accounts.set(type, {
- type,
- node: parseAccountXpub(xpub),
- accountXpub: xpub,
- basePath: `m/${PURPOSE[type]}'/${coin}'/0'`,
- });
- }
-
- const first = TYPE_PREFERENCE.find((t) => this.accounts.has(t));
- if (!first) throw new BackendError('the on-chain backend needs at least one account xpub', 400, 'BAD_XPUB');
- this.defaultType = first;
- }
-
- // ── derivation helpers ─────────────────────────────────────────────────────────────────────────
-
- private accountFor(type: AddressType): Account {
- const account = this.accounts.get(type);
- if (!account) {
- const have = [...this.accounts.keys()].join(', ') || 'none';
- throw new BackendError(`no ${type} account is configured (have: ${have})`, 400, 'NO_ACCOUNT');
- }
- return account;
- }
-
- private derive(type: AddressType, chain: ChainIndex, index: number): AddressEntry {
- const cacheKey = `${type}:${chain}:${index}`;
- const hit = this.derived.get(cacheKey);
- if (hit) return hit;
-
- const account = this.accountFor(type);
- const node = account.node.derive(`m/${chain}/${index}`);
- const pub = node.publicKey;
- if (!pub) throw new BackendError(`failed to derive ${type} ${chain}/${index}`, 500);
- const pubkey = Buffer.from(pub);
- const network = this.btcNetwork;
-
- const payment =
- type === 'p2wpkh'
- ? bitcoin.payments.p2wpkh({ pubkey, network })
- : type === 'p2tr'
- ? bitcoin.payments.p2tr({ internalPubkey: toXOnly(pubkey), network })
- : type === 'p2sh-p2wpkh'
- ? bitcoin.payments.p2sh({ redeem: bitcoin.payments.p2wpkh({ pubkey, network }), network })
- : bitcoin.payments.p2pkh({ pubkey, network });
-
- if (!payment.address || !payment.output) throw new BackendError(`failed to build a ${type} address`, 500);
-
- const entry: AddressEntry = {
- type,
- chain,
- index,
- address: payment.address,
- pubkeyHex: pubkey.toString('hex'),
- scriptPubKeyHex: payment.output.toString('hex'),
- path: `${account.basePath}/${chain}/${index}`,
- relPath: `${chain}/${index}`,
- };
- this.derived.set(cacheKey, entry);
- return entry;
- }
-
- // ── the snapshot: cache, refresh, persist ──────────────────────────────────────────────────────
-
- getSyncState(): SyncState {
- return {
- syncedAt: this.current?.at ?? null,
- stale: this.current !== null && Date.now() - this.current.at >= SCAN_TTL_MS,
- lastError: this.lastError,
- canRescan: this.chain.startRescan !== undefined,
- rescan: this.chain.rescanState?.() ?? null,
- };
- }
-
- /**
- * Ask the chain source to go looking for this wallet's coins from scratch.
- *
- * Returns as soon as the search is queued — it takes minutes, and the caller is an HTTP route. The
- * refresh chained onto its completion is the part that matters: a rescan that found coins has changed
- * nothing visible until the snapshot in front of it is rebuilt, and without this the owner would be
- * staring at the same zero until the TTL happened to expire.
- */
- async startRescan(opts: RescanOptions = {}): Promise {
- const start = this.chain.startRescan?.bind(this.chain);
- if (!start) this.notSupported('rescanning the chain');
- const { state, done } = start(this.scanContext().accounts, opts);
- void done
- .then(() => this.refresh())
- // The rescan's own failure is already on its state and reported through getSyncState; a failed
- // refresh behind it lands on lastError the same way. Neither should surface as an unhandled
- // rejection in the sidecar's log.
- .catch(() => {});
- return state;
- }
-
- /**
- * Re-attach to a rescan that outlived this process, and put the refresh back on the end of it.
- *
- * Read-only with respect to the upstream: it never starts a scan, so calling it when nothing is running
- * costs one request per account and answers null.
- */
- async adoptRescan(): Promise {
- const adopt = this.chain.adoptRescan?.bind(this.chain);
- if (!adopt) return null;
- const handle = await adopt(this.scanContext().accounts);
- if (!handle) return null;
- // The same chaining startRescan does, and for the same reason: coins recovered by a scan are invisible
- // until the snapshot in front of them is rebuilt.
- void handle.done.then(() => this.refresh()).catch(() => {});
- return handle.state;
- }
-
- /**
- * The wallet's view of the chain, stale-while-revalidate.
- *
- * A snapshot within SCAN_TTL_MS is served as-is. An older one is served IMMEDIATELY with a refresh
- * started behind it — that is the property the persistence exists for: after a restart, or while the
- * Esplora upstream is slow or unreachable, the screen shows the last real numbers with their age
- * rather than a blank wallet. Only a wallet that has genuinely never been read blocks on the network,
- * and only that case can surface an error to the caller.
- *
- * `fresh` opts out for the two paths where stale data would be wrong rather than merely old.
- */
- private async snapshot(opts?: { fresh?: boolean }): Promise {
- if (opts?.fresh) return this.refresh();
-
- await this.hydrate();
-
- const have = this.current;
- if (have && Date.now() - have.at < SCAN_TTL_MS) return have;
-
- const running = this.refresh();
- if (!have) return running;
-
- // The refresh outlives this response. Its failure is recorded on `lastError` and reported through
- // getSyncState, so it is handled here only to keep it from surfacing as an unhandled rejection.
- void running.catch(() => {});
- return have;
- }
-
- /** Load the persisted snapshot into memory. Runs at most once, and never throws. */
- private hydrate(): Promise {
- this.hydration ??= (async () => {
- const store = this.cache;
- if (!store || this.current) return;
- try {
- const row = await store.load();
- if (!row) return;
- this.lastError = row.lastError;
- // A refresh may have completed while this load was in flight; live data always wins. A snapshot
- // written by an older shape is ignored, not migrated — it is a cache, and the next refresh
- // replaces it for free.
- if (row.snapshot?.v === 1 && row.syncedAt && !this.current) {
- this.current = this.fromPersisted(row.snapshot, row.syncedAt.getTime());
- }
- } catch (err) {
- // A cache failure costs a slow load, nothing more. It must not become a wallet failure.
- console.error('[wallet] chain cache load failed:', err instanceof Error ? err.message : err);
- }
- })();
- return this.hydration;
- }
-
- /** Read the chain. Concurrent callers share one walk rather than each starting their own. */
- private refresh(): Promise {
- this.inflight ??= this.buildSnapshot().then(
- (snap) => {
- this.inflight = null;
- this.current = snap;
- this.lastError = null;
- void this.persist(snap);
- return snap;
- },
- (err: unknown) => {
- this.inflight = null;
- const message = err instanceof Error ? err.message : String(err);
- this.lastError = message;
- void this.cache?.recordError(message).catch((e: unknown) => {
- console.error('[wallet] chain cache error write failed:', e instanceof Error ? e.message : e);
- });
- throw err;
- },
- );
- return this.inflight;
- }
-
- private async persist(snap: Snapshot): Promise {
- if (!this.cache) return;
- try {
- await this.cache.save(toPersisted(snap));
- } catch (err) {
- console.error('[wallet] chain cache write failed:', err instanceof Error ? err.message : err);
- }
- }
-
- /**
- * Rebuild a snapshot from what was stored. Only the chain's own facts were persisted; every address,
- * script and pubkey is re-derived here from the account xpub, so a restored snapshot cannot disagree
- * with the wallet's actual keys. An entry naming a script type this wallet no longer has an xpub for
- * is dropped rather than faked.
- */
- private fromPersisted(stored: WalletChainSnapshot, at: number): Snapshot {
- const addresses: ScannedAddress[] = [];
- for (const a of stored.addresses) {
- const entry = this.tryDerive(a.type, a.chain, a.index);
- if (!entry) continue;
- addresses.push({
- ...entry,
- confirmedSats: a.confirmed,
- unconfirmedSats: a.unconfirmed,
- txCount: a.txCount,
- used: a.txCount > 0,
- });
- }
-
- const utxos: SpendableUtxo[] = [];
- for (const u of stored.utxos) {
- const entry = this.tryDerive(u.type, u.chain, u.index);
- if (!entry) continue;
- utxos.push({
- txid: u.txid,
- vout: u.vout,
- amountSats: u.value,
- address: entry.address,
- addressType: entry.type,
- confirmations: u.blockHeight === null ? 0 : Math.max(0, stored.tipHeight - u.blockHeight + 1),
- derivationPath: entry.path,
- frozen: false,
- scriptPubKeyHex: entry.scriptPubKeyHex,
- pubkeyHex: entry.pubkeyHex,
- });
- }
-
- return { at, tipHeight: stored.tipHeight, addresses, utxos, txs: stored.transactions };
- }
-
- /** Derive from untrusted stored coordinates — returns null rather than throwing on anything unusable. */
- private tryDerive(type: string, chain: number, index: number): AddressEntry | null {
- if (!isAddressType(type) || (chain !== 0 && chain !== 1)) return null;
- if (!Number.isInteger(index) || index < 0 || index >= MAX_SCAN_INDEX) return null;
- if (!this.accounts.has(type)) return null;
- try {
- return this.derive(type, chain, index);
- } catch {
- return null;
- }
- }
-
- /**
- * What the source is allowed to know: the account keys, which type is ours, and how to derive.
- *
- * `derive` is bound to this backend on purpose — a source that derived addresses itself could disagree
- * with the wallet about which addresses are the wallet's, and the resulting bug would lose coins rather
- * than fail loudly.
- */
- private scanContext(): ScanContext {
- return {
- accounts: [...this.accounts.values()].map((a) => ({ type: a.type, accountXpub: a.accountXpub })),
- defaultType: this.defaultType,
- derive: (type, chain, index) => this.derive(type, chain, index),
- };
- }
-
- /** One full read of the chain, stamped with the moment it was taken. */
- private async buildSnapshot(): Promise {
- const scan = await this.chain.scan(this.scanContext());
- return { at: Date.now(), ...scan };
- }
-
- /** Drop everything after a send, so the spent coins cannot reappear from cache on the next read. */
- private invalidateScan(): void {
- this.current = null;
- }
-
- // ── watch-only reads (no key material required) ────────────────────────────────────────────────
-
- async getInfo(): Promise {
- // Deliberately does not force a scan: this is the cheapest liveness probe the wallet has.
- const blockHeight = await this.chain.getTipHeight();
- return {
- kind: 'onchain',
- // An Esplora-backed wallet has no node identity, no alias and no upstream version to report.
- pubkey: null,
- alias: null,
- version: null,
- network: this.network,
- blockHeight,
- synced: true,
- };
- }
-
- override async getBalances(): Promise {
- const snap = await this.snapshot();
- let confirmed = 0;
- let unconfirmed = 0;
- for (const entry of snap.addresses) {
- confirmed += entry.confirmedSats;
- unconfirmed += entry.unconfirmedSats;
- }
- return {
- onchainConfirmed: confirmed,
- // Filled in by the route, which is the only layer that knows what the owner froze.
- onchainFrozen: 0,
- onchainUnconfirmed: unconfirmed,
- // No channels exist, and null is the contract's "this backend has no lightning" value.
- lightningBalance: null,
- lightningInbound: null,
- };
- }
-
- override async estimateFees(): Promise {
- return this.chain.getFeeEstimates();
- }
-
- override async getUtxos(): Promise {
- const snap = await this.snapshot();
- return snap.utxos.map((u) => ({
- txid: u.txid,
- vout: u.vout,
- amountSats: u.amountSats,
- address: u.address,
- addressType: u.addressType,
- confirmations: u.confirmations,
- // The public contract wants the path relative to the account xpub, not the absolute one the
- // signer uses, so it is recomputed from the tail of the full path.
- derivationPath: u.derivationPath.split('/').slice(-2).join('/'),
- // Freezing is a policy layer above this backend; nothing on-chain marks a coin frozen.
- frozen: false,
- }));
- }
-
- override async getNewAddress(req?: NewAddressRequest): Promise<{ address: string; type: AddressType }> {
- const type = req?.type ?? this.defaultType;
- this.accountFor(type);
- const entry = await this.nextUnused(type, 0, req?.peek === true);
- return { address: entry.address, type };
- }
-
- override async getTransactions(opts?: { limit?: number }): Promise {
- const snap = await this.snapshot();
- return snap.txs.slice(0, opts?.limit ?? DEFAULT_TX_LIMIT);
- }
-
- /** History for every address the scan found had been touched. Only those can appear in it. */
- // ── spending (requires the root key) ───────────────────────────────────────────────────────────
-
- override async sendCoins(req: SendCoinsRequest): Promise {
- // Fail before any network work rather than after building a PSBT we cannot sign.
- if (!this.signer.isUnlocked()) throw new WalletLockedError();
- if (!Number.isFinite(req.satPerVbyte) || req.satPerVbyte <= 0) {
- throw new BackendError('satPerVbyte must be a positive number', 400, 'INVALID_FEE_RATE');
- }
-
- const recipientScript = outputScriptFor(req.address, this.btcNetwork);
- const recipientType = scriptType(recipientScript);
-
- // Never stale. Selecting coins from a cached UTXO set would build a transaction spending outputs
- // that may already be gone, and the failure would arrive as a broadcast rejection after signing.
- const snap = await this.snapshot({ fresh: true });
-
- // The snapshot comes off the chain, which knows nothing about freezing, so every UTXO in it claims
- // `frozen: false`. selectCoins has always honoured the flag — nothing ever set it, which is what made
- // a plain send happily spend a coin the owner had frozen, and made "send everything" sweep it.
- const frozen = new Set(req.frozenOutpoints ?? []);
- const utxos = frozen.size
- ? snap.utxos.map((u) => (frozen.has(`${u.txid}:${u.vout}`) ? { ...u, frozen: true } : u))
- : snap.utxos;
-
- const selection = selectCoins({
- utxos,
- targetSats: req.amountSats ?? 0,
- sendAll: req.sendAll === true,
- satPerVbyte: req.satPerVbyte,
- recipientType,
- changeType: this.defaultType,
- outpoints: req.outpoints,
- spendUnconfirmed: req.spendUnconfirmed,
- });
-
- // Legacy inputs commit to the whole previous transaction, so it has to be fetched; segwit inputs
- // carry their own value and script in the PSBT and need nothing extra.
- const inputs = await mapLimit(selection.inputs, REQUEST_CONCURRENCY, async (u) => ({
- txid: u.txid,
- vout: u.vout,
- amountSats: u.amountSats,
- addressType: u.addressType,
- scriptPubKeyHex: u.scriptPubKeyHex,
- pubkeyHex: u.pubkeyHex,
- derivationPath: u.derivationPath,
- prevTxHex: u.addressType === 'p2pkh' ? await this.chain.getTxHex(u.txid) : undefined,
- }));
-
- const outputs: PsbtOutputSpec[] = [{ address: req.address, amountSats: selection.outputSats }];
- if (selection.changeSats !== null) {
- const change = await this.nextUnused(this.defaultType, 1, false);
- outputs.push({ address: change.address, amountSats: selection.changeSats });
- // Change-is-always-last is a well-known chain-analysis heuristic. One shuffle removes it.
- if (Math.random() < 0.5) outputs.reverse();
- }
-
- const { psbt, inputPaths } = buildPsbt({
- network: this.btcNetwork,
- inputs,
- outputs,
- rbf: req.rbf,
- });
-
- // The only place a root key enters this file. Synchronous, so the key is not held across an await.
- const signed = this.signer.withRoot((root) => signAndFinalize(psbt, root, inputPaths));
-
- const txid = await this.chain.broadcast(signed.rawHex);
- this.invalidateScan();
- return { txid, feeSats: signed.feeSats, rawHex: signed.rawHex };
- }
-
- override async signMessage(message: string): Promise {
- if (!this.signer.isUnlocked()) throw new WalletLockedError();
- // BIP137-style: the identity key is the first receive key of the default account, which is what
- // every other wallet that signs with a derived key uses.
- const entry = this.derive(this.defaultType, 0, 0);
- const hash = bitcoinMessageHash(message, this.btcNetwork);
-
- const signature = this.signer.withRoot((root) => {
- const node = root.derive(entry.path.replace(/[hH]/g, "'"));
- const priv = node.privateKey;
- if (!priv) throw new BackendError('derived node has no private key', 500);
- const { signature: sig, recoveryId } = ecc.signRecoverable(hash, priv);
- // Header byte: 27 + recovery id, +4 because the key is compressed.
- const header = Buffer.from([27 + recoveryId + 4]);
- return Buffer.concat([header, Buffer.from(sig)]).toString('base64');
- });
-
- return { signature };
- }
-
- /**
- * Verification needs no key material — only the xpub — so it stays available while locked.
- *
- * The contract takes no claimed address, and a recoverable signature *always* recovers some pubkey,
- * so "did this recover" is not a meaningful answer: a tampered message would still report valid.
- * `valid` therefore means "this wallet signed this message" — the recovered key is compared against
- * the identity key `signMessage` uses. The recovered pubkey is returned either way, so a caller
- * verifying a third party's signature can do its own comparison.
- */
- override async verifyMessage(message: string, signature: string): Promise {
- const sig = Buffer.from(signature, 'base64');
- if (sig.length !== 65) return { valid: false, pubkey: null };
-
- const header = sig[0];
- if (header === undefined || header < 27 || header > 42) return { valid: false, pubkey: null };
- const recoveryId = ((header - 27) & 3) as 0 | 1 | 2 | 3;
- const compressed = ((header - 27) & 4) !== 0;
- const compact = sig.subarray(1);
- const hash = bitcoinMessageHash(message, this.btcNetwork);
-
- try {
- const recovered = ecc.recover(hash, compact, recoveryId, compressed);
- if (!recovered || !ecc.verify(hash, recovered, compact)) return { valid: false, pubkey: null };
- const pubkey = Buffer.from(recovered).toString('hex');
- return { valid: pubkey === this.derive(this.defaultType, 0, 0).pubkeyHex, pubkey };
- } catch {
- return { valid: false, pubkey: null };
- }
- }
-
- // ── shared internals ───────────────────────────────────────────────────────────────────────────
-
- /** Fetch UTXOs for every scanned address that still holds a balance. */
- /**
- * First address on a chain that the blockchain has never seen, at or beyond the in-memory issuance
- * mark. `peek` reads without consuming; otherwise the mark advances so the next call hands out a
- * different address even before the current one is paid.
- */
- private async nextUnused(type: AddressType, chain: ChainIndex, peek: boolean): Promise {
- // Deliberately never served from cache. Handing out an address whose stale record says "unused" but
- // which has been paid since is silent address reuse — a privacy leak the owner cannot see and cannot
- // undo. Failing loudly while the upstream is down is the better of the two, so this is the one read
- // that stops working offline, and on purpose.
- const snap = await this.snapshot({ fresh: true });
- const key = `${type}:${chain}`;
- const hint = this.issued.get(key) ?? 0;
-
- const used = new Set();
- let highest = -1;
- for (const entry of snap.addresses) {
- if (entry.type !== type || entry.chain !== chain) continue;
- highest = Math.max(highest, entry.index);
- if (entry.used) used.add(entry.index);
- }
-
- let index = hint;
- // Anything past the scanned window is unused by definition — the gap limit is what ended the scan.
- while (index <= highest && used.has(index)) index++;
-
- // ...but "unused" is not the same as "findable". The mark advances on every issuance, paid or not,
- // so twenty unpaid addresses walk it past the end of the window the next scan covers, and a payment
- // to the twenty-first would never be seen again. Rather than hand out an address the wallet could
- // lose money on, stop and re-offer the last safe one: every index in that run is still virgin, so
- // repeating one is not address reuse in the sense that matters — nothing was ever received on it.
- // The floor of 0 covers a wallet the chain has never seen: Esplora short-circuits an account with no
- // history and returns no addresses at all, leaving `highest` at -1, and index 0 is then the only one
- // it will look at. Handing that out until it is paid is exactly right.
- const ceiling = Math.max(0, highest + this.chain.issueAhead);
- if (index > ceiling) index = ceiling;
-
- if (!peek) this.issued.set(key, index + 1);
- return this.derive(type, chain, index);
- }
-}
-
-// ── helpers ──────────────────────────────────────────────────────────────────────────────────────
-
-function isAddressType(value: string): value is AddressType {
- return value === 'p2wpkh' || value === 'p2tr' || value === 'p2sh-p2wpkh' || value === 'p2pkh';
-}
-
-/**
- * Reduce a snapshot to the chain facts worth storing. Addresses, scripts and pubkeys are dropped: they
- * are pure derivation from the account xpub, so re-deriving them on load is both cheaper than storing
- * them and the only way a restored snapshot is guaranteed to match the wallet's real keys.
- */
-function toPersisted(snap: Snapshot): WalletChainSnapshot {
- return {
- v: 1,
- tipHeight: snap.tipHeight,
- addresses: snap.addresses.map((a) => ({
- type: a.type,
- chain: a.chain,
- index: a.index,
- confirmed: a.confirmedSats,
- unconfirmed: a.unconfirmedSats,
- txCount: a.txCount,
- })),
- utxos: snap.utxos.map((u) => {
- // The last two path elements are the BIP44 chain and address index — the same tail getUtxos
- // reports as the relative path.
- const tail = u.derivationPath.split('/');
- return {
- txid: u.txid,
- vout: u.vout,
- value: u.amountSats,
- type: u.addressType,
- chain: Number(tail.at(-2)),
- index: Number(tail.at(-1)),
- // Stored as a height, not a count, so confirmations stay correct as the tip moves on.
- blockHeight: u.confirmations > 0 ? snap.tipHeight - u.confirmations + 1 : null,
- };
- }),
- transactions: snap.txs,
- };
-}
-
-/** Varint, for the length prefix in the Bitcoin signed-message preimage. */
-function varint(n: number): Buffer {
- if (n < 0xfd) return Buffer.from([n]);
- if (n <= 0xffff) {
- const b = Buffer.alloc(3);
- b[0] = 0xfd;
- b.writeUInt16LE(n, 1);
- return b;
- }
- const b = Buffer.alloc(5);
- b[0] = 0xfe;
- b.writeUInt32LE(n, 1);
- return b;
-}
-
-/** sha256d(messagePrefix || varint(len) || message) — the standard signed-message preimage. */
-function bitcoinMessageHash(message: string, network: bitcoin.Network): Buffer {
- const prefix = Buffer.isBuffer(network.messagePrefix)
- ? network.messagePrefix
- : Buffer.from(network.messagePrefix, 'utf8');
- const body = Buffer.from(message, 'utf8');
- return bitcoin.crypto.hash256(Buffer.concat([prefix, varint(body.length), body]));
-}
diff --git a/src/servers/sidecar/wallet/bolt11.test.ts b/src/servers/sidecar/wallet/bolt11.test.ts
deleted file mode 100644
index d6219013..00000000
--- a/src/servers/sidecar/wallet/bolt11.test.ts
+++ /dev/null
@@ -1,301 +0,0 @@
-// Vectors: the BOLT 11 spec examples (lightning/bolts, 11-payment-encoding.md § Examples), plus the
-// regtest and signet invoices Zeus uses in its own utils/Bolt11Utils.test.ts. Every spec invoice below is
-// signed with priv_key e126f68f7eafcc8b74f54d269fe206be715000f94dac067d1c04a8ca3b2db734.
-
-import { describe, expect, it } from 'bun:test';
-import { clearBolt11Cache, decodeBolt11, decodeBolt11Invoice } from './bolt11';
-import { BackendError } from './types';
-
-// ── spec vectors ─────────────────────────────────────────────────────────────────────────────────
-
-/** no amount, description "Please consider supporting this project" */
-const NO_AMOUNT =
- 'lnbc1pvjluezsp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygspp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdpl2pkx2ctnv5sxxmmwwd5kgetjypeh2ursdae8g6twvus8g6rfwvs8qun0dfjkxaq9qrsgq357wnc5r2ueh7ck6q93dj32dlqnls087fxdwk8qakdyafkq3yap9us6v52vjjsrvywa6rt52cm9r9zqt8r2t7mlcwspyetp5h2tztugp9lfyql';
-
-/** 2500u, description "1 cup coffee", expiry 60 */
-const COFFEE_250U =
- 'lnbc2500u1pvjluezsp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygspp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdq5xysxxatsyp3k7enxv4jsxqzpu9qrsgquk0rl77nj30yxdy8j9vdx85fkpmdla2087ne0xh8nhedh8w27kyke0lp53ut353s06fv3qfegext0eh0ymjpf39tuven09sam30g4vgpfna3rh';
-
-/** 2500u, UTF-8 description, expiry 60 */
-const NONSENSE_250U =
- 'lnbc2500u1pvjluezsp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygspp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdpquwpc4curk03c9wlrswe78q4eyqc7d8d0xqzpu9qrsgqhtjpauu9ur7fw2thcl4y9vfvh4m9wlfyz2gem29g5ghe2aak2pm3ps8fdhtceqsaagty2vph7utlgj48u0ged6a337aewvraedendscp573dxr';
-
-/** 20m, description_hash instead of a description */
-const HASHED_20M =
- 'lnbc20m1pvjluezsp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygspp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqhp58yjmdan79s6qqdhdzgynm4zwqd5d7xmw5fk98klysy043l2ahrqs9qrsgq7ea976txfraylvgzuxs8kgcw23ezlrszfnh8r6qtfpr6cxga50aj6txm9rxrydzd06dfeawfk6swupvz4erwnyutnjq7x39ymw6j38gp7ynn44';
-
-/** the same on testnet, with a P2PKH fallback address */
-const TESTNET_20M_FALLBACK =
- 'lntb20m1pvjluezsp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygshp58yjmdan79s6qqdhdzgynm4zwqd5d7xmw5fk98klysy043l2ahrqspp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqfpp3x9et2e20v6pu37c5d9vax37wxq72un989qrsgqdj545axuxtnfemtpwkc45hx9d2ft7x04mt8q7y6t0k2dge9e7h8kpy9p34ytyslj3yu569aalz2xdk8xkd7ltxqld94u8h2esmsmacgpghe9k8';
-
-/** 20m with a fallback address and a two-hop route hint */
-const MAINNET_20M_ROUTES =
- 'lnbc20m1pvjluezsp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygspp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqhp58yjmdan79s6qqdhdzgynm4zwqd5d7xmw5fk98klysy043l2ahrqsfpp3qjmp7lwpagxun9pygexvgpjdc4jdj85fr9yq20q82gphp2nflc7jtzrcazrra7wwgzxqc8u7754cdlpfrmccae92qgzqvzq2ps8pqqqqqqpqqqqq9qqqvpeuqafqxu92d8lr6fvg0r5gv0heeeqgcrqlnm6jhphu9y00rrhy4grqszsvpcgpy9qqqqqqgqqqqq7qqzq9qrsgqdfjcdk6w3ak5pca9hwfwfh63zrrz06wwfya0ydlzpgzxkn5xagsqz7x9j4jwe7yj7vaf2k9lqsdk45kts2fd0fkr28am0u4w95tt2nsq76cqw0';
-
-/** 9678785340p — a msat amount that is not a whole number of sats */
-const PICO_9678785340P =
- 'lnbc9678785340p1pwmna7lpp5gc3xfm08u9qy06djf8dfflhugl6p7lgza6dsjxq454gxhj9t7a0sd8dgfkx7cmtwd68yetpd5s9xar0wfjn5gpc8qhrsdfq24f5ggrxdaezqsnvda3kkum5wfjkzmfqf3jkgem9wgsyuctwdus9xgrcyqcjcgpzgfskx6eqf9hzqnteypzxz7fzypfhg6trddjhygrcyqezcgpzfysywmm5ypxxjemgw3hxjmn8yptk7untd9hxwg3q2d6xjcmtv4ezq7pqxgsxzmnyyqcjqmt0wfjjq6t5v4khxsp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygsxqyjw5qcqp2rzjq0gxwkzc8w6323m55m4jyxcjwmy7stt9hwkwe2qxmy8zpsgg7jcuwz87fcqqeuqqqyqqqqlgqqqqn3qq9q9qrsgqrvgkpnmps664wgkp43l22qsgdw4ve24aca4nymnxddlnp8vh9v2sdxlu5ywdxefsfvm0fq3sesf08uf6q9a2ke0hc9j6z6wlxg5z5kqpu2v9wz';
-
-/** 25m advertising features 8, 14 and 99 */
-const FEATURES_25M =
- 'lnbc25m1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdq5vdhkven9v5sxyetpdeessp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygs9q5sqqqqqqqqqqqqqqqqsgq2a25dxl5hrntdtn6zvydt7d66hyzsyhqs4wdynavys42xgl6sgx9c4g7me86a27t07mdtfry458rtjr0v92cnmswpsjscgt2vcse3sgpz3uapa';
-
-/** the same invoice in the all-uppercase QR form */
-const FEATURES_25M_UPPER =
- 'LNBC25M1PVJLUEZPP5QQQSYQCYQ5RQWZQFQQQSYQCYQ5RQWZQFQQQSYQCYQ5RQWZQFQYPQDQ5VDHKVEN9V5SXYETPDEESSP5ZYG3ZYG3ZYG3ZYG3ZYG3ZYG3ZYG3ZYG3ZYG3ZYG3ZYG3ZYG3ZYGS9Q5SQQQQQQQQQQQQQQQQSGQ2A25DXL5HRNTDTN6ZVYDT7D66HYZSYHQS4WDYNAVYS42XGL6SGX9C4G7ME86A27T07MDTFRY458RTJR0V92CNMSWPSJSCGT2VCSE3SGPZ3UAPA';
-
-/** 10m carrying payment metadata 0x01fafaf0 */
-const METADATA_10M =
- 'lnbc10m1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdp9wpshjmt9de6zqmt9w3skgct5vysxjmnnd9jx2mq8q8a04uqsp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygs9q2gqqqqqqsgq7hf8he7ecf7n4ffphs6awl9t6676rrclv9ckg3d3ncn7fct63p6s365duk5wrk202cfy3aj5xnnp5gs3vrdvruverwwq7yzhkf5a3xqpd05wjc';
-
-/** a valid invoice whose signature is high-S */
-const HIGH_S_SIGNATURE =
- 'lnbc1pvjluezsp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygspp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdpl2pkx2ctnv5sxxmmwwd5kgetjypeh2ursdae8g6twvus8g6rfwvs8qun0dfjkxaq9qrsgq357wnc5r2ueh7ck6q93dj32dlqnls087fxdwk8qakdyafkq3yap2r09nt4ndd0unm3z9u5t48y6ucv4r5sg7lk98c77ctvjczkspk5qprc90gx';
-
-/** a high-S signature that does not match the invoice's own `n` payee field */
-const PAYEE_MISMATCH =
- 'lnbc25m1p70xwfzpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdpl2pkx2ctnv5sxxmmwwd5kgetjypeh2ursdae8g6twvus8g6rfwvs8qun0dfjkxaqnp4q0n326hr8v9zprg8gsvezcch06gfaqqhde2aj730yg0durunfhv66sp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygs9qrsgqsp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygsp5cfzp9ugllvk03rltd6hvndxj26ux6gcxc5azyxk060rj9tzghct5zvjlps76gx8wpq5yuu79688k8gnm2c0al6v608s96l0xzrrlqqwnzxmu';
-
-/** bech32 checksum is invalid */
-const BAD_CHECKSUM =
- 'lnbc2500u1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdpquwpc4curk03c9wlrswe78q4eyqc7d8d0xqzpuyk0sg5g70me25alkluzd2x62aysf2pyy8edtjeevuv4p2d5p76r4zkmneet7uvyakky2zr4cusd45tftc9c5fh0nnqpnl2jfll544esqchsrnt';
-
-/** signature is not recoverable */
-const UNRECOVERABLE_SIGNATURE =
- 'lnbc2500u1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdq5xysxxatsyp3k7enxv4jsxqzpusp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygs9qrsgqwgt7mcn5yqw3yx0w94pswkpq6j9uh6xfqqqtsk4tnarugeektd4hg5975x9am52rz4qskukxdmjemg92vvqz8nvmsye63r5ykel43pgz7zq0g2';
-
-/** string is too short */
-const TOO_SHORT =
- 'lnbc1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdpl2pkx2ctnv5sxxmmwwd5kgetjypeh2ursdae8g6na6hlh';
-
-/** invalid amount multiplier */
-const BAD_MULTIPLIER =
- 'lnbc2500x1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdq5xysxxatsyp3k7enxv4jsxqzpusp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygs9qrsgqrrzc4cvfue4zp3hggxp47ag7xnrlr8vgcmkjxk3j5jqethnumgkpqp23z9jclu3v0a7e0aruz366e9wqdykw6dxhdzcjjhldxq0w6wgqcnu43j';
-
-/** invalid sub-millisatoshi precision */
-const SUB_MSAT_PRECISION =
- 'lnbc2500000001p1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdq5xysxxatsyp3k7enxv4jsxqzpusp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygs9qrsgq0lzc236j96a95uv0m3umg28gclm5lqxtqqwk32uuk4k6673k6n5kfvx3d2h8s295fad45fdhmusm8sjudfhlf6dcsxmfvkeywmjdkxcp99202x';
-
-// ── Zeus fixtures (utils/Bolt11Utils.test.ts) ────────────────────────────────────────────────────
-
-/** regtest, 1230n = 123 sat, no expiry field */
-const REGTEST_1230N =
- 'lnbcrt1230n1pj429x7pp57t97q4awqj3f529snr0pa6senk83sq5pp760qf5a4jzvd7xgwcksdqqcqzzsxqrrsssp57eqtv7vxr46arupna3w4ct0lkf2mqmz9wt044cwkks0rwlnhfr5s9qyyssqragwpwav7nfwv2xyuuamxxj4pnnpzv2hlw7j473repd3sq7st698ta9kmzmygt0w7tmncl56a6mnma0w7e5dlpqd0wy6x3v35rssldspjhh8p0';
-
-/** signet, 567780n = 56778 sat */
-const SIGNET_567780N =
- 'lntbs567780n1pnqr26ypp5c0wcrpzwxwqnwu2nld5q36dfc9yjrfdp87nn9d5y093jjncvqresdq0w3jhxar8v3n8xeccqzpuxqrrsssp5r94e3nwnw63gjaxc8wex38ufv2m6442vnrw49m7dad9jdum3tdsq9qyyssqk4dvvuk7zhhju8ztf7nfc2hzqq9gqtzuyc0ljz8nl93laxwv4869lt9fsxkxacje6eh4ur5ymg83hvakn4tfpzdu6fq49705sar7fxspga8qjp';
-
-/** Every spec vector shares this payee, payment hash and timestamp. */
-const SPEC_PAYEE = '03e7156ae33b0a208d0744199163177e909e80176e55d97a2f221ede0f934dd9ad';
-const SPEC_PAYMENT_HASH = '0001020304050607080900010203040506070809000102030405060708090102';
-const SPEC_TIMESTAMP = 1496314658;
-// ── amounts ──────────────────────────────────────────────────────────────────────────────────────
-
-describe('decodeBolt11 amounts', () => {
- it('returns null for a zero-amount invoice', () => {
- expect(decodeBolt11(NO_AMOUNT).amountMsat).toBeNull();
- });
-
- it('parses every multiplier as an exact msat string', () => {
- // 20m = 0.02 BTC, 2500u = 0.0025 BTC, 1230n = 123 sat, 9678785340p = 967878534 msat.
- expect(decodeBolt11(HASHED_20M).amountMsat).toBe('2000000000');
- expect(decodeBolt11(COFFEE_250U).amountMsat).toBe('250000000');
- expect(decodeBolt11(REGTEST_1230N).amountMsat).toBe('123000');
- expect(decodeBolt11(PICO_9678785340P).amountMsat).toBe('967878534');
- });
-
- it('keeps amountMsat a string and never widens it to a number', () => {
- const amount = decodeBolt11(PICO_9678785340P).amountMsat;
- expect(typeof amount).toBe('string');
- // A pico amount need not be a whole sat: the msat string is exact where `satoshis` cannot be.
- expect(decodeBolt11Invoice(PICO_9678785340P).satoshis).toBeNull();
- expect(decodeBolt11Invoice(REGTEST_1230N).satoshis).toBe(123);
- });
-
- it('rejects an unknown multiplier', () => {
- expect(() => decodeBolt11(BAD_MULTIPLIER)).toThrow(BackendError);
- });
-
- it('rejects sub-millisatoshi precision instead of rounding it', () => {
- expect(() => decodeBolt11(SUB_MSAT_PRECISION)).toThrow(BackendError);
- });
-});
-
-// ── fields ───────────────────────────────────────────────────────────────────────────────────────
-
-describe('decodeBolt11 fields', () => {
- it('extracts the payment hash, destination and timestamp', () => {
- const decoded = decodeBolt11(NO_AMOUNT);
- expect(decoded.paymentHash).toBe(SPEC_PAYMENT_HASH);
- expect(decoded.destination).toBe(SPEC_PAYEE);
- expect(decoded.timestamp).toBe(SPEC_TIMESTAMP);
- });
-
- it('recovers a key from a high-S signature instead of rejecting it', () => {
- // The spec's high-S vector is the donation invoice re-signed with s negated while keeping recovery
- // flag 1, so it recovers a *different* (valid) key. What matters is that recovery runs at all —
- // implementations that enforce low-S during recovery fail here.
- expect(decodeBolt11(HIGH_S_SIGNATURE).destination).toMatch(/^0[23][0-9a-f]{64}$/);
- expect(decodeBolt11(HIGH_S_SIGNATURE).destination).not.toBe(SPEC_PAYEE);
- expect(decodeBolt11(HIGH_S_SIGNATURE).paymentHash).toBe(SPEC_PAYMENT_HASH);
- });
-
- it('returns the description for a `d` invoice and null for an `h` one', () => {
- expect(decodeBolt11(NO_AMOUNT).description).toBe('Please consider supporting this project');
- expect(decodeBolt11(COFFEE_250U).description).toBe('1 cup coffee');
- expect(decodeBolt11(NONSENSE_250U).description).toBe('ナンセンス 1杯');
-
- const hashed = decodeBolt11Invoice(HASHED_20M);
- expect(decodeBolt11(HASHED_20M).description).toBeNull();
- expect(hashed.descriptionHash).toBe('3925b6f67e2c340036ed12093dd44e0368df1b6ea26c53dbe4811f58fd5db8c1');
- });
-
- it('defaults expiry to 3600 when there is no `x` field', () => {
- expect(decodeBolt11(NO_AMOUNT).expiry).toBe(3600);
- expect(decodeBolt11Invoice(NO_AMOUNT).expiry).toBeNull();
- expect(decodeBolt11(REGTEST_1230N).expiry).toBe(3600);
- });
-
- it('reads an explicit expiry', () => {
- expect(decodeBolt11(COFFEE_250U).expiry).toBe(60);
- expect(decodeBolt11(PICO_9678785340P).expiry).toBe(604800);
- expect(decodeBolt11Invoice(COFFEE_250U).expiresAt).toBe(SPEC_TIMESTAMP + 60);
- });
-
- it('expands the feature bitmap to the indices of the set bits', () => {
- expect(decodeBolt11(NO_AMOUNT).features).toEqual(['8', '14']);
- expect(decodeBolt11(FEATURES_25M).features).toEqual(['8', '14', '99']);
- });
-
- it('reports route hints and parses their hops', () => {
- expect(decodeBolt11(NO_AMOUNT).routeHints).toBe(false);
-
- const decoded = decodeBolt11Invoice(MAINNET_20M_ROUTES);
- expect(decodeBolt11(MAINNET_20M_ROUTES).routeHints).toBe(true);
- expect(decoded.routes).toHaveLength(1);
- expect(decoded.routes[0]).toEqual([
- {
- pubkey: '029e03a901b85534ff1e92c43c74431f7ce72046060fcf7a95c37e148f78c77255',
- shortChannelId: '66051x263430x1800',
- feeBaseMsat: 1,
- feeProportionalMillionths: 20,
- cltvExpiryDelta: 3,
- },
- {
- pubkey: '039e03a901b85534ff1e92c43c74431f7ce72046060fcf7a95c37e148f78c77255',
- shortChannelId: '197637x395016x2314',
- feeBaseMsat: 2,
- feeProportionalMillionths: 30,
- cltvExpiryDelta: 4,
- },
- ]);
- });
-
- it('parses payment secret, metadata and fallback addresses', () => {
- expect(decodeBolt11Invoice(NO_AMOUNT).paymentSecret).toBe(
- '1111111111111111111111111111111111111111111111111111111111111111',
- );
- expect(decodeBolt11Invoice(METADATA_10M).metadata).toBe('01fafaf0');
-
- const fallback = decodeBolt11Invoice(TESTNET_20M_FALLBACK).fallbacks[0];
- // 17 is the P2PKH marker; the program is the 20-byte hash160 of mk2QpYatsKicvFVuTAQLBryyccRXMUaGHP.
- expect(fallback?.version).toBe(17);
- expect(fallback?.programHex).toHaveLength(40);
- });
-
- it('leaves cltvExpiry null when the invoice omits `c`', () => {
- expect(decodeBolt11(NO_AMOUNT).cltvExpiry).toBeNull();
- });
-});
-
-// ── networks ─────────────────────────────────────────────────────────────────────────────────────
-
-describe('decodeBolt11 networks', () => {
- it('resolves every bech32 network prefix', () => {
- expect(decodeBolt11Invoice(NO_AMOUNT).network).toBe('bitcoin');
- expect(decodeBolt11Invoice(TESTNET_20M_FALLBACK).network).toBe('testnet');
- expect(decodeBolt11Invoice(SIGNET_567780N).network).toBe('signet');
- expect(decodeBolt11Invoice(REGTEST_1230N).network).toBe('regtest');
- });
-
- it('parses the amount out of a multi-letter network prefix', () => {
- // `lnbcrt1230n` and `lntbs567780n` are the cases where a greedy hrp match eats the amount.
- expect(decodeBolt11(REGTEST_1230N).amountMsat).toBe('123000');
- expect(decodeBolt11(SIGNET_567780N).amountMsat).toBe('56778000');
- });
-
- it('rejects an unknown network prefix', () => {
- expect(() => decodeBolt11(NO_AMOUNT.replace(/^lnbc/, 'lnxyz'))).toThrow(BackendError);
- });
-});
-
-// ── malformed input ──────────────────────────────────────────────────────────────────────────────
-
-describe('decodeBolt11 rejections', () => {
- const expectBadInvoice = (invoice: string) => {
- let caught: unknown;
- try {
- decodeBolt11(invoice);
- } catch (err) {
- caught = err;
- }
- expect(caught).toBeInstanceOf(BackendError);
- expect((caught as BackendError).status).toBe(400);
- expect((caught as BackendError).code).toBe('BAD_INVOICE');
- };
-
- it('throws BackendError(400, BAD_INVOICE) on a corrupted checksum', () => {
- expectBadInvoice(BAD_CHECKSUM);
- // The same invoice with one data character flipped.
- expectBadInvoice(`${COFFEE_250U.slice(0, -1)}${COFFEE_250U.endsWith('h') ? 'w' : 'h'}`);
- });
-
- it('throws on a signature that cannot be recovered', () => {
- expectBadInvoice(UNRECOVERABLE_SIGNATURE);
- });
-
- it('throws when the recovered key contradicts an explicit `n` payee field', () => {
- expectBadInvoice(PAYEE_MISMATCH);
- });
-
- it('throws on a truncated payment request', () => {
- expectBadInvoice(TOO_SHORT);
- });
-
- it('throws on input that is not a payment request at all', () => {
- expectBadInvoice('');
- expectBadInvoice('not an invoice');
- expectBadInvoice(NO_AMOUNT.replace(/^ln/, ''));
- });
-
- it('throws on a mixed-case payment request but accepts the uppercase QR form', () => {
- expectBadInvoice(`LNBC${NO_AMOUNT.slice(4)}`);
- expect(decodeBolt11(FEATURES_25M_UPPER)).toEqual(decodeBolt11(FEATURES_25M));
- // The contract's `bolt11` is always the canonical lowercase form.
- expect(decodeBolt11(FEATURES_25M_UPPER).bolt11).toBe(FEATURES_25M);
- });
-});
-
-// ── cache ────────────────────────────────────────────────────────────────────────────────────────
-
-describe('the LRU cache', () => {
- it('returns the same object for a repeat decode and survives a clear', () => {
- clearBolt11Cache();
- const first = decodeBolt11Invoice(COFFEE_250U);
- expect(decodeBolt11Invoice(COFFEE_250U)).toBe(first);
- expect(decodeBolt11Invoice(COFFEE_250U.toUpperCase())).toBe(first);
-
- clearBolt11Cache();
- const afterClear = decodeBolt11Invoice(COFFEE_250U);
- expect(afterClear).not.toBe(first);
- expect(afterClear).toEqual(first);
- });
-
- it('hands every decodeBolt11 caller its own object', () => {
- const first = decodeBolt11(COFFEE_250U);
- const second = decodeBolt11(COFFEE_250U);
- expect(second).not.toBe(first);
- expect(second).toEqual(first);
- });
-});
diff --git a/src/servers/sidecar/wallet/bolt11.ts b/src/servers/sidecar/wallet/bolt11.ts
deleted file mode 100644
index 43f4cc8b..00000000
--- a/src/servers/sidecar/wallet/bolt11.ts
+++ /dev/null
@@ -1,516 +0,0 @@
-// BOLT11 invoice decoding, in-process — no node round-trip.
-//
-// Ported from Zeus's `utils/Bolt11Utils.ts`, which is itself derived from **light-bolt11-decoder**:
-// Copyright (c) 2021 bitcoinjs contributors, fiatjaf. MIT licence.
-// The bech32 walk, the human-readable-part amount grammar and the signature preimage construction are
-// that upstream's work and are preserved verbatim in behaviour.
-//
-// INTENTIONAL DIFFERENCES from Zeus's port:
-//
-// 1. ERRORS. Zeus mixes `throw new Error(...)` with silent `undefined` returns (a bad multiplier sets
-// `satoshis = null` and carries on; a `fromWordsUnsafe` failure yields `undefined`). Every failure
-// here is a `BackendError(msg, 400, 'BAD_INVOICE')`, so routes.ts answers 400 rather than leaking a
-// half-decoded invoice with null amounts into a payment flow.
-// 2. NO bignumber.js. All amount arithmetic is BigInt: msat tops out at 2.1e18, which a double cannot
-// hold, and BigInt does the same job exactly with one less dependency.
-// 3. NO @noble/hashes. The single sha256 comes from `node:crypto`, which Bun provides natively.
-// 4. EAGER signature recovery. Zeus installs lazy getters for `destination`/`signature` because its
-// Activity list decodes hundreds of invoices to read only the timestamp. Here `DecodedInvoice`
-// requires a non-null `destination` on every call, so laziness would never pay off; the LRU cache
-// (which is what actually collapses repeat recoveries) is kept and sized for a server.
-// 5. NO `sections` array. Zeus keeps light-bolt11-decoder's positional `{name, letters, value?: any}`
-// list for back-compat. Nothing here consumes it, and it was the source of the `any`. Every tag is
-// exposed as a named, typed field instead, with anything unrecognised in `unknownTags`.
-// 6. MORE TAGS PARSED. Zeus leaves `r` (route hints), `9` (features) and `f` (fallback address) as
-// unknown tags. All three are parsed, because the contract's `routeHints` and `features` fields need
-// them. Feature bits are expanded to the indices of the set bits, matching how backends/clnrest.ts
-// renders CLN's bitmap.
-// 7. SPEC-CONFORMANT LENIENCY/STRICTNESS. Known tags whose `data_length` is wrong are skipped and
-// unknown tags ignored (BOLT 11 requires both). An all-uppercase invoice — the QR form — is accepted
-// and lowercased; a MIXED-case one is rejected, as the spec requires and Zeus's blanket
-// `.toLowerCase()` did not. An explicit `n` payee is checked against the recovered key rather than
-// trusted blindly, which is the check Zeus skips.
-// 8. NO SIMNET. Zeus carries the btcd-only `sb` prefix; `BitcoinNetwork` has no member for it.
-
-import { createHash } from 'node:crypto';
-import { bech32 } from 'bech32';
-import { recoverPublicKey } from '@noble/secp256k1';
-import { BackendError, type BitcoinNetwork, type DecodedInvoice } from './types';
-
-// ── shape ────────────────────────────────────────────────────────────────────────────────────────
-
-export type Bolt11NetworkParams = {
- /** The bech32 human-readable part that follows `ln`. */
- readonly bech32: string;
- readonly network: BitcoinNetwork;
- readonly pubKeyHash: number;
- readonly scriptHash: number;
- readonly validWitnessVersions: readonly number[];
-};
-
-/** One hop of an `r` field. Multiple `r` fields each describe a separate route. */
-export type Bolt11RouteHop = {
- readonly pubkey: string;
- /** `block x tx x output`, the standard short_channel_id rendering. */
- readonly shortChannelId: string;
- readonly feeBaseMsat: number;
- readonly feeProportionalMillionths: number;
- readonly cltvExpiryDelta: number;
-};
-
-/** An `f` field. Left as witness-version + program rather than re-encoded to an address string. */
-export type Bolt11Fallback = {
- /** 0-16 are segwit witness versions; 17 is P2PKH and 18 is P2SH. */
- readonly version: number;
- readonly programHex: string;
-};
-
-export type Bolt11UnknownTag = { readonly tagCode: number; readonly words: readonly number[] };
-
-/** The full decode. `decodeBolt11` projects this onto the narrower `DecodedInvoice` contract. */
-export type Bolt11Invoice = {
- /** The invoice, lowercased. */
- readonly paymentRequest: string;
- /** The whole human-readable part, e.g. `lnbc2500u`. */
- readonly prefix: string;
- readonly network: BitcoinNetwork;
- readonly networkParams: Bolt11NetworkParams;
- readonly timestamp: number;
- /** Decimal msat string, or null for a zero-amount ("any amount") invoice. Never a number. */
- readonly millisatoshis: string | null;
- /** Convenience only, and null whenever the amount is not a whole number of sats. */
- readonly satoshis: number | null;
- readonly paymentHash: string;
- readonly paymentSecret: string | null;
- readonly description: string | null;
- readonly descriptionHash: string | null;
- /** The explicit `n` payee field, when the invoice carries one. */
- readonly payee: string | null;
- /** `payee` when present, else recovered from the signature. 33-byte compressed pubkey, hex. */
- readonly destination: string;
- /** The raw `x` field; null when absent. `expirySeconds` applies the spec's 3600 default. */
- readonly expiry: number | null;
- readonly expirySeconds: number;
- readonly expiresAt: number;
- readonly cltvExpiry: number | null;
- readonly metadata: string | null;
- /** Indices of the set feature bits, as decimal strings. */
- readonly featureBits: readonly string[];
- readonly routes: readonly (readonly Bolt11RouteHop[])[];
- readonly fallbacks: readonly Bolt11Fallback[];
- /** 64-byte compact signature, hex. */
- readonly signature: string;
- readonly recoveryFlag: number;
- readonly unknownTags: readonly Bolt11UnknownTag[];
-};
-
-// ── constants ────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * Zeus caches 256 entries for a phone's Activity list. A server decodes the same invoice from several
- * call sites (list → detail → pay), so the cache earns its keep the same way; 1024 entries of a few
- * hundred bytes each is a rounding error against a Bun heap.
- */
-const CACHE_LIMIT = 1024;
-const cache = new Map();
-
-const MSAT_PER_BTC = 100_000_000_000n;
-const MAX_MSAT = 2_100_000_000_000_000_000n;
-const DIVISORS: Readonly> = {
- m: 1_000n,
- u: 1_000_000n,
- n: 1_000_000_000n,
- p: 1_000_000_000_000n,
-};
-
-const NETWORKS: readonly Bolt11NetworkParams[] = [
- { bech32: 'bc', network: 'bitcoin', pubKeyHash: 0x00, scriptHash: 0x05, validWitnessVersions: [0, 1] },
- { bech32: 'tb', network: 'testnet', pubKeyHash: 0x6f, scriptHash: 0xc4, validWitnessVersions: [0, 1] },
- { bech32: 'tbs', network: 'signet', pubKeyHash: 0x6f, scriptHash: 0xc4, validWitnessVersions: [0, 1] },
- { bech32: 'bcrt', network: 'regtest', pubKeyHash: 0x6f, scriptHash: 0xc4, validWitnessVersions: [0, 1] },
-];
-
-const TAG_NAMES = {
- 1: 'payment_hash',
- 3: 'route_hint',
- 5: 'feature_bits',
- 6: 'expiry',
- 9: 'fallback_address',
- 13: 'description',
- 16: 'payment_secret',
- 19: 'payee',
- 23: 'description_hash',
- 24: 'min_final_cltv_expiry',
- 27: 'metadata',
-} as const satisfies Record;
-
-/** BOLT 11: a reader MUST skip a `p`, `s`, `h` or `n` field whose data_length is not the fixed size. */
-const FIXED_TAG_WORDS: Readonly> = { 1: 52, 16: 52, 23: 52, 19: 53 };
-
-/** The signature occupies the last 104 words — 65 bytes: 64-byte compact sig + 1 recovery byte. */
-const SIGNATURE_WORDS = 104;
-const TIMESTAMP_WORDS = 7;
-
-/** BOLT 11 default when no `x` field is present. */
-const DEFAULT_EXPIRY_SECONDS = 3600;
-
-const ROUTE_HOP_BYTES = 51;
-
-// ── helpers ──────────────────────────────────────────────────────────────────────────────────────
-
-function badInvoice(message: string): never {
- throw new BackendError(`invalid bolt11 invoice: ${message}`, 400, 'BAD_INVOICE');
-}
-
-/** Big-endian base-32. BigInt because a hostile tag can claim far more than 53 bits. */
-function wordsToInt(words: readonly number[]): number {
- let value = 0n;
- for (const word of words) value = value * 32n + BigInt(word);
- if (value > BigInt(Number.MAX_SAFE_INTEGER)) badInvoice('a numeric field is out of range');
- return Number(value);
-}
-
-function wordsToBytes(words: readonly number[]): Uint8Array {
- const bytes = bech32.fromWordsUnsafe(words);
- if (bytes == null) badInvoice('a field is not a whole number of bytes');
- return Uint8Array.from(bytes);
-}
-
-const wordsToHex = (words: readonly number[]): string => Buffer.from(wordsToBytes(words)).toString('hex');
-
-const wordsToUtf8 = (words: readonly number[]): string => Buffer.from(wordsToBytes(words)).toString('utf8');
-
-/**
- * The `9` field is a big-endian bit vector whose LAST bit is feature 0, so a word's position from the
- * end fixes the base index. Rendered as decimal strings to match backends/clnrest.ts's `featureBits`.
- */
-function wordsToFeatureBits(words: readonly number[]): string[] {
- const bits: string[] = [];
- for (let i = words.length - 1; i >= 0; i--) {
- const word = words[i] ?? 0;
- const base = (words.length - 1 - i) * 5;
- for (let bit = 0; bit < 5; bit++) {
- if (word & (1 << bit)) bits.push(String(base + bit));
- }
- }
- return bits.sort((a, b) => Number(a) - Number(b));
-}
-
-function wordsToRoute(words: readonly number[]): Bolt11RouteHop[] {
- const bytes = Buffer.from(wordsToBytes(words));
- if (bytes.length === 0 || bytes.length % ROUTE_HOP_BYTES !== 0) badInvoice('a route hint is malformed');
-
- const hops: Bolt11RouteHop[] = [];
- for (let offset = 0; offset < bytes.length; offset += ROUTE_HOP_BYTES) {
- const hop = bytes.subarray(offset, offset + ROUTE_HOP_BYTES);
- const scid = hop.subarray(33, 41);
- const block = scid.readUIntBE(0, 3);
- const tx = scid.readUIntBE(3, 3);
- const output = scid.readUInt16BE(6);
- hops.push({
- pubkey: hop.subarray(0, 33).toString('hex'),
- shortChannelId: `${block}x${tx}x${output}`,
- feeBaseMsat: hop.readUInt32BE(41),
- feeProportionalMillionths: hop.readUInt32BE(45),
- cltvExpiryDelta: hop.readUInt16BE(49),
- });
- }
- return hops;
-}
-
-function wordsToFallback(words: readonly number[]): Bolt11Fallback | null {
- const version = words[0];
- // A fallback with no program is meaningless; the spec says to ignore an unparseable one.
- if (version === undefined || words.length < 2) return null;
- return { version, programHex: wordsToHex(words.slice(1)) };
-}
-
-/**
- * The amount grammar from the human-readable part: ``, where the multiplier
- * divides one bitcoin. Integer arithmetic throughout — a `p` amount that is not a multiple of 10 would
- * be sub-millisatoshi and is invalid rather than rounded.
- */
-function hrpToMsat(amount: string, multiplier: string): string {
- if (!/^\d+$/.test(amount)) badInvoice(`"${amount}" is not a valid amount`);
- if (multiplier && !(multiplier in DIVISORS)) badInvoice(`"${multiplier}" is not a valid amount multiplier`);
-
- const value = BigInt(amount);
- const divisor = multiplier ? DIVISORS[multiplier] : undefined;
- const msat = divisor === undefined ? value * MSAT_PER_BTC : (value * MSAT_PER_BTC) / divisor;
-
- if (multiplier === 'p' && value % 10n !== 0n) badInvoice('amount has sub-millisatoshi precision');
- if (msat > MAX_MSAT) badInvoice('amount is outside of valid range');
- return msat.toString();
-}
-
-/** 5-bit → 8-bit, right-padded with zeros: the preimage the signature covers. */
-function convertBits(words: readonly number[]): Uint8Array {
- let value = 0;
- let bits = 0;
- const result: number[] = [];
- for (const word of words) {
- value = (value << 5) | word;
- bits += 5;
- while (bits >= 8) {
- bits -= 8;
- result.push((value >> bits) & 0xff);
- }
- }
- if (bits > 0) result.push((value << (8 - bits)) & 0xff);
- return Uint8Array.from(result);
-}
-
-type Recovered = { destination: string; signature: string; recoveryFlag: number };
-
-/** The signed message is sha256( utf8(prefix) || convertBits(dataWords) ). SEC1 recovery from there. */
-function recoverPayee(prefix: string, sigWords: readonly number[], signedWords: readonly number[]): Recovered {
- const sigBytes = wordsToBytes(sigWords);
- const recoveryFlag = sigBytes[64];
- if (sigBytes.length !== 65 || recoveryFlag === undefined || recoveryFlag > 3) {
- badInvoice('signature is malformed');
- }
-
- const preimage = Buffer.concat([Buffer.from(prefix, 'utf8'), Buffer.from(convertBits(signedWords))]);
- const hash = createHash('sha256').update(preimage).digest();
-
- // @noble/secp256k1 v3 wants the recovery byte FIRST; bech32 carries it last.
- const recoverable = Buffer.concat([Buffer.from([recoveryFlag]), Buffer.from(sigBytes.subarray(0, 64))]);
-
- let pubkey: Uint8Array;
- try {
- pubkey = recoverPublicKey(recoverable, hash, { prehash: false });
- } catch {
- badInvoice('signature is not recoverable');
- }
-
- return {
- destination: Buffer.from(pubkey).toString('hex'),
- signature: Buffer.from(sigBytes.subarray(0, 64)).toString('hex'),
- recoveryFlag,
- };
-}
-
-/** `lnbc2500u` → the network params and the amount. */
-function parsePrefix(prefix: string): { params: Bolt11NetworkParams; millisatoshis: string | null } {
- // Non-greedy on the hrp so the trailing digits+multiplier win: `lnbcrt500u` → bcrt / 500 / u. A prefix
- // with no amount ends in a letter the first pattern would eat, hence the amount-less second attempt.
- let matches = /^ln(\S+?)(\d+)([a-z]?)$/.exec(prefix);
- let amount = matches?.[2] ?? '';
- let multiplier = matches?.[3] ?? '';
- if (!matches) {
- matches = /^ln(\S+)$/.exec(prefix);
- amount = '';
- multiplier = '';
- }
-
- const hrp = matches?.[1];
- if (!hrp) badInvoice('not a lightning payment request');
-
- const params = NETWORKS.find((candidate) => candidate.bech32 === hrp);
- if (!params) badInvoice(`unknown network prefix "ln${hrp}"`);
-
- return { params, millisatoshis: amount ? hrpToMsat(amount, multiplier) : null };
-}
-
-type Tags = {
- paymentHash: string | null;
- paymentSecret: string | null;
- description: string | null;
- descriptionHash: string | null;
- payee: string | null;
- expiry: number | null;
- cltvExpiry: number | null;
- metadata: string | null;
- featureBits: string[];
- routes: Bolt11RouteHop[][];
- fallbacks: Bolt11Fallback[];
- unknownTags: Bolt11UnknownTag[];
-};
-
-/** Walks the tagged fields. First occurrence of a field wins; unknown and wrong-length fields are skipped. */
-function parseTags(dataWords: readonly number[]): Tags {
- const tags: Tags = {
- paymentHash: null,
- paymentSecret: null,
- description: null,
- descriptionHash: null,
- payee: null,
- expiry: null,
- cltvExpiry: null,
- metadata: null,
- featureBits: [],
- routes: [],
- fallbacks: [],
- unknownTags: [],
- };
-
- let words = dataWords;
- while (words.length > 0) {
- const tagCode = words[0];
- if (tagCode === undefined) break;
- if (words.length < 3) badInvoice('a tagged field is truncated');
-
- const length = wordsToInt(words.slice(1, 3));
- words = words.slice(3);
- if (length > words.length) badInvoice('a tagged field overruns the invoice');
- const tagWords = words.slice(0, length);
- words = words.slice(length);
-
- const expected = FIXED_TAG_WORDS[tagCode];
- if (expected !== undefined && length !== expected) continue;
-
- const name: string | undefined = TAG_NAMES[tagCode as keyof typeof TAG_NAMES];
- switch (name) {
- case 'payment_hash':
- tags.paymentHash ??= wordsToHex(tagWords);
- break;
- case 'payment_secret':
- tags.paymentSecret ??= wordsToHex(tagWords);
- break;
- case 'description':
- tags.description ??= wordsToUtf8(tagWords);
- break;
- case 'description_hash':
- tags.descriptionHash ??= wordsToHex(tagWords);
- break;
- case 'payee':
- tags.payee ??= wordsToHex(tagWords);
- break;
- case 'expiry':
- tags.expiry ??= wordsToInt(tagWords);
- break;
- case 'min_final_cltv_expiry':
- tags.cltvExpiry ??= wordsToInt(tagWords);
- break;
- case 'metadata':
- tags.metadata ??= wordsToHex(tagWords);
- break;
- case 'feature_bits':
- if (tags.featureBits.length === 0) tags.featureBits = wordsToFeatureBits(tagWords);
- break;
- case 'route_hint':
- tags.routes.push(wordsToRoute(tagWords));
- break;
- case 'fallback_address': {
- const fallback = wordsToFallback(tagWords);
- if (fallback) tags.fallbacks.push(fallback);
- break;
- }
- default:
- tags.unknownTags.push({ tagCode, words: tagWords });
- }
- }
-
- return tags;
-}
-
-// ── the decoder ──────────────────────────────────────────────────────────────────────────────────
-
-/**
- * Full decode, cached. The returned object is shared with every other caller for the same invoice and is
- * typed readonly throughout — treat it as frozen.
- */
-export function decodeBolt11Invoice(paymentRequest: string): Bolt11Invoice {
- if (typeof paymentRequest !== 'string') badInvoice('expected a string');
-
- const trimmed = paymentRequest.trim();
- // The QR form is all-uppercase and legal; a mixed-case string is not (BOLT 11 / BIP-173).
- if (/[a-z]/.test(trimmed) && /[A-Z]/.test(trimmed)) badInvoice('mixed-case payment request');
- const normalized = trimmed.toLowerCase();
-
- const cached = cache.get(normalized);
- if (cached) {
- // Re-insert to move to the MRU end of the Map's insertion order.
- cache.delete(normalized);
- cache.set(normalized, cached);
- return cached;
- }
-
- if (!normalized.startsWith('ln')) badInvoice('not a lightning payment request');
-
- let decoded: { prefix: string; words: number[] };
- try {
- decoded = bech32.decode(normalized, Number.MAX_SAFE_INTEGER);
- } catch (err) {
- badInvoice(err instanceof Error ? err.message.toLowerCase() : 'bech32 decode failed');
- }
-
- if (decoded.words.length < SIGNATURE_WORDS + TIMESTAMP_WORDS) badInvoice('payment request is too short');
-
- const { params, millisatoshis } = parsePrefix(decoded.prefix);
-
- const signedWords = decoded.words.slice(0, -SIGNATURE_WORDS);
- const sigWords = decoded.words.slice(-SIGNATURE_WORDS);
- const timestamp = wordsToInt(signedWords.slice(0, TIMESTAMP_WORDS));
- const tags = parseTags(signedWords.slice(TIMESTAMP_WORDS));
-
- if (!tags.paymentHash) badInvoice('no payment hash');
-
- const recovered = recoverPayee(decoded.prefix, sigWords, signedWords);
- // BOLT 11: when an `n` field is present a reader MUST still check the signature against it. A correct
- // signer always recovers to its own key, so a mismatch means the invoice was tampered with.
- if (tags.payee && tags.payee !== recovered.destination) badInvoice('signature does not match the payee');
-
- const msat = millisatoshis === null ? null : BigInt(millisatoshis);
- const expirySeconds = tags.expiry ?? DEFAULT_EXPIRY_SECONDS;
-
- const invoice: Bolt11Invoice = {
- paymentRequest: normalized,
- prefix: decoded.prefix,
- network: params.network,
- networkParams: params,
- timestamp,
- millisatoshis,
- satoshis: msat !== null && msat % 1000n === 0n ? Number(msat / 1000n) : null,
- paymentHash: tags.paymentHash,
- paymentSecret: tags.paymentSecret,
- description: tags.description,
- descriptionHash: tags.descriptionHash,
- payee: tags.payee,
- destination: tags.payee ?? recovered.destination,
- expiry: tags.expiry,
- expirySeconds,
- expiresAt: timestamp + expirySeconds,
- cltvExpiry: tags.cltvExpiry,
- metadata: tags.metadata,
- featureBits: tags.featureBits,
- routes: tags.routes,
- fallbacks: tags.fallbacks,
- signature: recovered.signature,
- recoveryFlag: recovered.recoveryFlag,
- unknownTags: tags.unknownTags,
- };
-
- if (cache.size >= CACHE_LIMIT) {
- const oldest = cache.keys().next();
- if (!oldest.done) cache.delete(oldest.value);
- }
- cache.set(normalized, invoice);
-
- return invoice;
-}
-
-/**
- * The contract surface: a BOLT11 payment request as the backends report it. Throws
- * `BackendError(…, 400, 'BAD_INVOICE')` for anything that does not decode.
- */
-export function decodeBolt11(bolt11: string): DecodedInvoice {
- const invoice = decodeBolt11Invoice(bolt11);
- return {
- bolt11: invoice.paymentRequest,
- paymentHash: invoice.paymentHash,
- amountMsat: invoice.millisatoshis,
- description: invoice.description,
- destination: invoice.destination,
- timestamp: invoice.timestamp,
- expiry: invoice.expirySeconds,
- cltvExpiry: invoice.cltvExpiry,
- routeHints: invoice.routes.length > 0,
- features: [...invoice.featureBits],
- };
-}
-
-/** Test seam: the LRU is process-global, so a test that measures recovery cost needs to reset it. */
-export function clearBolt11Cache(): void {
- cache.clear();
-}
diff --git a/src/servers/sidecar/wallet/chain-source-esplora.test.ts b/src/servers/sidecar/wallet/chain-source-esplora.test.ts
deleted file mode 100644
index add5d585..00000000
--- a/src/servers/sidecar/wallet/chain-source-esplora.test.ts
+++ /dev/null
@@ -1,336 +0,0 @@
-// Behavioural pins for the Esplora chain source, driven through a real OnchainBackend.
-//
-// These exist because the scan used to live inside the backend and was moved out wholesale; nothing in
-// the suite covered it before, so a silent behaviour change during the move would have shipped. The stub
-// below is a full stand-in for the HTTP client, which means the whole path — gap-limit walk, balance
-// summation, UTXO mapping, transaction scoring, address issuance — runs with no network at all.
-
-import { describe, expect, test } from 'bun:test';
-import { HDKey } from '@scure/bip32';
-import { mnemonicToSeedSync } from '@scure/bip39';
-import * as bitcoin from 'bitcoinjs-lib';
-import type { EsploraAddress, EsploraChain, EsploraTx, EsploraUtxo } from './chain';
-import { EsploraChainSource } from './chain-source-esplora';
-import { OnchainBackend, type WalletSigner } from './backends/onchain';
-import { initEcc } from './psbt';
-
-initEcc();
-
-// NEVER PUT A REAL ACCOUNT KEY IN A TEST. An xpub cannot spend, but it reveals every address a wallet
-// will ever use and its entire history, permanently and irrevocably — and a test file is the easiest
-// place in a repo for one to hide, because it looks like a fixture. This one is derived here, in the
-// open, from the BIP84 specification's own published mnemonic, so its provenance is checkable rather
-// than asserted. If you need a different fixture, derive it the same way; do not paste one in.
-const PUBLIC_TEST_MNEMONIC =
- 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
-
-const ACCOUNT_XPUB = HDKey.fromMasterSeed(mnemonicToSeedSync(PUBLIC_TEST_MNEMONIC)).derive(
- "m/84'/0'/0'",
-).publicExtendedKey;
-
-/** Derive the same p2wpkh address the backend will, independently of the backend. */
-function addressAt(chain: 0 | 1, index: number): string {
- const node = HDKey.fromExtendedKey(ACCOUNT_XPUB).deriveChild(chain).deriveChild(index);
- const pubkey = Buffer.from(node.publicKey!);
- return bitcoin.payments.p2wpkh({ pubkey, network: bitcoin.networks.bitcoin }).address!;
-}
-
-function scriptAt(chain: 0 | 1, index: number): string {
- const node = HDKey.fromExtendedKey(ACCOUNT_XPUB).deriveChild(chain).deriveChild(index);
- const pubkey = Buffer.from(node.publicKey!);
- return bitcoin.payments.p2wpkh({ pubkey, network: bitcoin.networks.bitcoin }).output!.toString('hex');
-}
-
-const EMPTY_STATS = { funded_txo_count: 0, funded_txo_sum: 0, spent_txo_count: 0, spent_txo_sum: 0, tx_count: 0 };
-
-type Funding = { confirmed?: number; spent?: number; mempool?: number; txCount?: number };
-
-/**
- * A stand-in for EsploraChain that serves a fixed world: a map of address → what the chain says about it,
- * and everything else derived from that. Also counts requests, because the request count IS the behaviour
- * under test for the gap-limit walk.
- */
-class StubEsplora {
- readonly calls: string[] = [];
- constructor(
- private readonly world: Map,
- private readonly tip = 800_000,
- ) {}
-
- async getTipHeight(): Promise {
- this.calls.push('tip');
- return this.tip;
- }
-
- async getAddress(address: string): Promise {
- this.calls.push(`addr:${address}`);
- const f = this.world.get(address);
- if (!f) return { address, chain_stats: { ...EMPTY_STATS }, mempool_stats: { ...EMPTY_STATS } };
- return {
- address,
- chain_stats: {
- ...EMPTY_STATS,
- funded_txo_sum: f.confirmed ?? 0,
- spent_txo_sum: f.spent ?? 0,
- tx_count: f.txCount ?? 1,
- },
- mempool_stats: { ...EMPTY_STATS, funded_txo_sum: f.mempool ?? 0, tx_count: f.mempool ? 1 : 0 },
- };
- }
-
- async getAddressUtxos(address: string): Promise {
- this.calls.push(`utxo:${address}`);
- const f = this.world.get(address);
- const value = (f?.confirmed ?? 0) - (f?.spent ?? 0);
- if (!f || value <= 0) return [];
- return [{ txid: 'a'.repeat(64), vout: 0, value, status: { confirmed: true, block_height: this.tip - 5 } }];
- }
-
- async getAddressTxs(address: string): Promise {
- this.calls.push(`txs:${address}`);
- const f = this.world.get(address);
- if (!f) return [];
- const idx = [...this.world.keys()].indexOf(address);
- return [
- {
- txid: String(idx).padStart(64, 'b'),
- version: 2,
- locktime: 0,
- fee: 200,
- vin: [{ txid: 'c'.repeat(64), vout: 0, prevout: null, scriptsig: '', sequence: 0xffffffff, witness: [] }],
- vout: [
- { scriptpubkey: scriptFor(address), scriptpubkey_asm: '', scriptpubkey_type: 'v0_p2wpkh', value: 50_000 },
- ],
- status: { confirmed: true, block_height: this.tip - 5, block_time: 1_700_000_000 },
- } as unknown as EsploraTx,
- ];
- }
-
- async getFeeEstimates() {
- return { fastestFee: 10, halfHourFee: 8, hourFee: 5, economyFee: 2, minimumFee: 1 };
- }
-
- async getTxHex(): Promise {
- throw new Error('not needed');
- }
-
- /** Accepts anything and reports a fixed txid — the spend tests care what got selected, not what got sent. */
- async broadcast(): Promise {
- this.calls.push('broadcast');
- return 'd'.repeat(64);
- }
-}
-
-/** Reverse-lookup the script for an address the stub was configured with. */
-function scriptFor(address: string): string {
- for (const chain of [0, 1] as const) {
- for (let i = 0; i < 40; i++) if (addressAt(chain, i) === address) return scriptAt(chain, i);
- }
- return 'ff';
-}
-
-const LOCKED_SIGNER: WalletSigner = {
- isUnlocked: () => false,
- withRoot: () => {
- throw new Error('locked');
- },
-};
-
-/**
- * A signer holding the fixture's own root key. Only the spend tests need one — everything else runs
- * locked, which is the state the wallet is in almost all of the time.
- */
-const UNLOCKED_SIGNER: WalletSigner = {
- isUnlocked: () => true,
- withRoot: (fn: (root: HDKey) => T): T => fn(HDKey.fromMasterSeed(mnemonicToSeedSync(PUBLIC_TEST_MNEMONIC))),
-};
-
-function backendFor(world: Map, signer: WalletSigner = LOCKED_SIGNER) {
- const stub = new StubEsplora(world);
- const source = new EsploraChainSource({
- chain: stub as unknown as EsploraChain,
- label: 'esplora(stub)',
- });
- const backend = new OnchainBackend({
- chain: source,
- network: 'bitcoin',
- accountXpub: { p2wpkh: ACCOUNT_XPUB },
- signer,
- });
- return { backend, stub };
-}
-
-describe('EsploraChainSource through OnchainBackend', () => {
- test('the fixture key really is the published BIP84 vector, not somebody’s wallet', () => {
- // The spec's own first receive address. If this fails, the mnemonic above is not what it claims and
- // whatever replaced it must be treated as live key material until proven otherwise.
- expect(addressAt(0, 0)).toBe('bc1qcr8te4kr609gcawutmrza0j4xv80jy8z306fyu');
- });
-
- test('an empty wallet costs one gap-limit window per chain and reports zero', async () => {
- const { backend, stub } = backendFor(new Map());
-
- expect(await backend.getBalances()).toEqual({
- onchainConfirmed: 0,
- onchainUnconfirmed: 0,
- onchainFrozen: 0,
- lightningBalance: null,
- lightningInbound: null,
- });
- expect(await backend.getUtxos()).toEqual([]);
- expect(await backend.getTransactions()).toEqual([]);
-
- // One script type, two chains, one gap-limit window each: exactly 40 address lookups and no more.
- expect(stub.calls.filter((c) => c.startsWith('addr:'))).toHaveLength(40);
- // Nothing held a balance, so not a single UTXO call was worth making.
- expect(stub.calls.filter((c) => c.startsWith('utxo:'))).toHaveLength(0);
- });
-
- test('unused script types cost one probe each, not a full walk', async () => {
- // The same xpub under four script types: every one derives valid addresses, and only the default
- // (p2wpkh) should be walked. This is the optimisation that keeps a scan at 43 requests instead of 160.
- const stub = new StubEsplora(new Map());
- const backend = new OnchainBackend({
- chain: new EsploraChainSource({ chain: stub as unknown as EsploraChain, label: 'esplora(stub)' }),
- network: 'bitcoin',
- accountXpub: {
- p2wpkh: ACCOUNT_XPUB,
- p2tr: ACCOUNT_XPUB,
- 'p2sh-p2wpkh': ACCOUNT_XPUB,
- p2pkh: ACCOUNT_XPUB,
- },
- signer: LOCKED_SIGNER,
- });
-
- await backend.getBalances();
- // 40 for the walked default + 1 probe each for the three that have never been used.
- expect(stub.calls.filter((c) => c.startsWith('addr:'))).toHaveLength(43);
- });
-
- test('balances sum the confirmed and mempool deltas across the scan', async () => {
- const world = new Map([
- [addressAt(0, 0), { confirmed: 100_000, spent: 40_000 }],
- [addressAt(0, 3), { confirmed: 25_000 }],
- [addressAt(1, 0), { confirmed: 0, mempool: 7_000 }],
- ]);
- const { backend } = backendFor(world);
-
- const balances = await backend.getBalances();
- expect(balances.onchainConfirmed).toBe(85_000);
- expect(balances.onchainUnconfirmed).toBe(7_000);
-
- const utxos = await backend.getUtxos();
- expect(utxos.map((u) => u.amountSats).sort((a, b) => a - b)).toEqual([25_000, 60_000]);
- // The public contract reports the path relative to the account xpub, not the absolute one.
- expect(utxos.every((u) => /^[01]\/\d+$/.test(u.derivationPath ?? ''))).toBe(true);
- expect(utxos.every((u) => u.confirmations === 6)).toBe(true);
- });
-
- test('a used address resets the gap, so funds past the first window are still found', async () => {
- // Index 25 is beyond the initial 20-address window: it is only reachable if a hit at 19 reset the gap.
- const world = new Map