@kaleidorg/wallet-engine 1.0.0-beta.38 → 1.0.0-beta.41

package/dist/adapters/wdk/SparkWdkAdapter.js

@@ -1,26 +1,22 @@
 /**
  * SparkWdkAdapter
  * ---------------
- * Thin adapter mapping the WDK Spark module (@tetherto/wdk-wallet-spark) onto the
+ * Adapter mapping the WDK Spark module (@tetherto/wdk-wallet-spark) onto the
  * stable `IProtocolAdapter` contract. This is the reference implementation of the
  * "wrap a WDK module behind the contract" pattern (see docs/WDK_INTEGRATION_PLAN.md).
  *
  * Discipline rules enforced here:
  *  - NO WDK/SDK types cross the contract boundary — everything returned is a domain
  *    type from ../types/base. The WDK objects are held as `any` internally.
- *  - Protocol quirks (zero-fee, static address) live in the capability manifest,
- *    not in this interface.
- *
- * WDK Spark account surface (captured via Spike A, 2026-06-03):
- *   manager: getAccount, getAccountByPath, getFeeRates
- *   account: getAddress, getBalance, sendTransaction, transfer,
- *            getStaticDepositAddress, getSingleUseDepositAddress, quoteWithdraw,
- *            withdraw, createLightningInvoice, payLightningInvoice,
- *            createSparkSatsInvoice, createSparkTokensInvoice, paySparkInvoice,
- *            syncWalletBalance, dispose, cleanupConnections
- *
- * Status: skeleton — core receive/balance/invoice/send wired to the real WDK calls;
- * remaining contract methods stubbed with explicit ProtocolError until Phase 2.
+ *  - The WDK **account** surface is the primary path (getAddress, getBalance,
+ *    payLightningInvoice, sendTransaction, getTransfers, createLightningInvoice, …).
+ *  - The raw `SparkWallet` the account wraps (`account._wallet`) is reached ONLY for
+ *    the rich paths the WDK surface does not expose directly — token send + outbox,
+ *    token history, L1 deposit claiming, and on-chain (cooperative-exit) withdrawal —
+ *    ported verbatim from the mature native SparkAdapter (identical behaviour).
+ *  - The sub-path stays free of a *static* `@buildonspark/spark-sdk` import: the SDK
+ *    address helpers are lazy-loaded in `connect()`, and the one SDK-coupled lib
+ *    (spark-converters, used for token-history mapping) is dynamic-imported on demand.
  */
 import { ProtocolError, } from '../../types/base.js';
 import { getCapabilities } from '../../capabilities/index.js';
@@ -28,6 +24,13 @@ import { PROTOCOL_OPERATIONS } from '../../capabilities/operations.js';
 import { loadWdkModule } from './moduleLoader.js';
 import { decodeBolt11, isBolt11 } from '../../lib/bolt11.js';
 import { BaseWdkAdapter } from './BaseWdkAdapter.js';
+import { formatAmount, mapTransferStatus, parseSdkExpiryMs, rawTokenIdFromBech32mTokenId, rawTokenIdFromBytes, tokenRefsMatch, txHashFromBytes, } from '../../lib/spark-helpers.js';
+import { getSparkBalanceCached, invalidateSparkBalanceCache } from '../../lib/spark-balance-cache.js';
+import { loadSentTokenRecords, normalizeTxHash, saveSentTokenRecord, } from '../../lib/spark-sent-token-records.js';
+import { signLnMessage, verifyLnMessage } from '../../lib/ln-message-sign.js';
+import { resolveWalletSeed } from '../../lib/wallet-seed.js';
+/** Default maximum fee for Lightning payments (sats) — mirrors the native adapter. */
+const DEFAULT_MAX_FEE_SATS = 1000;
 /** Lower-case hex string for a Uint8Array / Buffer / hex string (for identity-key compare). */
 function toHexLower(bytes) {
     if (!bytes)
@@ -75,6 +78,19 @@ export class SparkWdkAdapter extends BaseWdkAdapter {
         // since the spark-sdk Transfer proto exposes sender/receiver identity keys
         // rather than an explicit direction flag.
         this.identityPubKeyHex = null;
+        /** BIP-39 mnemonic — retained for message/PSBT signing (derives its own keys). */
+        this.mnemonic = null;
+        /** Lazily-loaded `@buildonspark/spark-sdk` address helpers (kept off the static import graph). */
+        this.sdk = null;
+        /** Maps a created Lightning invoice string → its receive-request id (for status polling). */
+        this.invoiceRequestIds = new Map();
+    }
+    /** The raw SparkWallet the WDK account wraps — proven surface for token/deposit/withdrawal ops. */
+    get rawWallet() {
+        const w = this.account?._wallet;
+        if (!w)
+            throw new ProtocolError('Spark wallet unavailable', 'SPARK', 'NOT_CONNECTED');
+        return w;
     }
     // --- Connection ---------------------------------------------------------
     async connect(config) {
@@ -82,12 +98,15 @@ export class SparkWdkAdapter extends BaseWdkAdapter {
         if (!cfg.mnemonic) {
             throw new ProtocolError('SparkWdkAdapter requires a mnemonic', 'SPARK', 'CONFIG');
         }
+        this.mnemonic = cfg.mnemonic;
         this.network = cfg.network ?? 'mainnet';
         // Injectable loader (RN injects a static require; Node/Vite use the import fallback).
         // @ts-ignore — declared as a workspace/optional dep; resolved at runtime.
         const mod = await loadWdkModule('@tetherto/wdk-wallet-spark', () => import('@tetherto/wdk-wallet-spark'));
         const WalletManagerSpark = mod.default ?? mod;
-        this.manager = new WalletManagerSpark(cfg.mnemonic, {
+        // Resolve to seed bytes so nsec/hex-rooted wallets bypass the WDK base's
+        // BIP-39 string validation (which throws "The seed phrase is invalid").
+        this.manager = new WalletManagerSpark(resolveWalletSeed(cfg.mnemonic), {
             network: SPARK_NETWORK_MAP[this.network] ?? 'MAINNET',
         });
         this.account = await this.manager.getAccount(cfg.accountIndex ?? 0);
@@ -97,45 +116,82 @@ export class SparkWdkAdapter extends BaseWdkAdapter {
         catch {
             this.identityPubKeyHex = null;
         }
+        // Lazy-load the SDK address helpers used to classify send destinations. Kept
+        // out of the static import graph so this sub-path stays SDK-free until used.
+        // @ts-ignore — resolved at runtime; a transitive dep of the WDK Spark module.
+        this.sdk = await loadWdkModule('@buildonspark/spark-sdk', () => import('@buildonspark/spark-sdk'));
+        // Back the native sparkClientManager singleton with this adapter's underlying
+        // SparkWallet, so host glue that reads Spark through it (Flashnet AMM, the
+        // Orchestra bridge) keeps working under the WDK backend — no second wallet, no
+        // derivation drift. Lazy-imported so spark-client-manager (which statically
+        // imports spark-sdk) never enters this sub-path's static graph.
+        try {
+            const { sparkClientManager } = await import('../../lib/spark-client-manager.js');
+            sparkClientManager.adoptExternalWallet(this.account?._wallet, this.network);
+        }
+        catch {
+            /* flashnet/bridge glue is optional — never block connect on it */
+        }
         this.connected = true;
     }
     async getConnectionInfo() {
-        return { protocol: 'SPARK', connected: this.connected, network: this.network };
+        this.assertConnected();
+        // Warm the balance cache so the dashboard's first read is coalesced.
+        await getSparkBalanceCached(this.rawWallet).catch(() => { });
+        return {
+            protocol: 'SPARK',
+            connected: this.connected,
+            network: this.network,
+            syncStatus: { synced: true, progress: 100 },
+        };
     }
     // --- Address / receive --------------------------------------------------
-    async getReceiveAddress() {
+    async getReceiveAddress(assetId) {
         this.assertConnected();
-        const address = await this.account.getAddress();
-        return { address, format: 'SPARK_ADDRESS' };
+        // Spark-to-Spark native address.
+        if (assetId === 'SPARK') {
+            const address = await this.account.getAddress();
+            return { address, format: 'SPARK_ADDRESS', asset: 'BTC' };
+        }
+        // BTC on-chain deposit address (default).
+        if (!assetId || assetId.toLowerCase() === 'btc') {
+            const address = await this.account.getSingleUseDepositAddress();
+            return { address, format: 'BTC_ADDRESS', asset: 'BTC' };
+        }
+        throw new ProtocolError('Spark only supports BTC', 'SPARK', 'UNSUPPORTED_ASSET');
     }
     // --- Balance ------------------------------------------------------------
     async getBtcBalance() {
         this.assertConnected();
-        // WDK: getBalance(): Promise<bigint> — sats, settled balance.
-        const bal = await this.account.getBalance();
-        const total = Number(bal);
+        const { balance } = await getSparkBalanceCached(this.rawWallet);
+        const total = Number(balance);
         return { confirmed: total, unconfirmed: 0, total };
     }
     async refreshBalances() {
         this.assertConnected();
-        await this.account.syncWalletBalance?.();
+        // Drop the short-TTL coalescing cache so the next read hits the gateway,
+        // then reconcile server-side state (best-effort).
+        invalidateSparkBalanceCache();
+        await this.account.syncWalletBalance?.().catch(() => { });
     }
     async listAssets() {
         this.assertConnected();
-        const { total } = await this.getBtcBalance();
+        const { balance, tokenBalances } = await getSparkBalanceCached(this.rawWallet);
+        const balanceSats = Number(balance);
         const btc = {
             id: 'BTC',
             name: 'Bitcoin',
             ticker: 'BTC',
             precision: 8,
             protocol: 'SPARK',
-            layer: 'BTC_SPARK',
+            layer: 'SPARK_SPARK',
             balance: {
-                total,
-                available: total,
+                total: balanceSats,
+                available: balanceSats,
                 pending: 0,
-                totalDisplay: String(total),
-                availableDisplay: String(total),
+                locked: 0,
+                totalDisplay: formatAmount(balanceSats, 8),
+                availableDisplay: formatAmount(balanceSats, 8),
             },
             capabilities: {
                 canSend: true,
@@ -145,90 +201,73 @@ export class SparkWdkAdapter extends BaseWdkAdapter {
                 supportsOnchain: true,
             },
         };
-        const out = [btc];
-        // Spark tokens. The WDK account wraps a SparkWallet whose `getBalance()`
-        // returns `{ satsBalance, tokenBalances }`, where tokenBalances is a
-        // Map<bech32m identifier, { balance, tokenMetadata|tokenInfo }>. Token
-        // enumeration is best-effort: never let it break the BTC listing.
-        try {
-            const wallet = this.account?._wallet;
-            const full = wallet?.getBalance ? await wallet.getBalance() : null;
-            const tokenBalances = full?.tokenBalances;
-            if (tokenBalances && typeof tokenBalances.forEach === 'function') {
-                // TokenBalanceMap value = { ownedBalance, availableToSendBalance, tokenMetadata }
-                // (UserTokenMetadata: tokenName/tokenTicker/decimals). There is NO `balance`
-                // field — reading it returned 0. The Map key is the bech32m token identifier.
-                tokenBalances.forEach((entry, key) => {
-                    const meta = entry?.tokenMetadata ?? entry?.tokenInfo ?? {};
-                    const id = String(key);
-                    if (!id)
-                        return;
-                    const owned = Number(entry?.ownedBalance ?? entry?.balance ?? 0);
-                    const available = Number(entry?.availableToSendBalance ?? entry?.ownedBalance ?? 0);
-                    const decimals = Number(meta.decimals ?? meta.tokenDecimals ?? 0);
-                    const ticker = meta.tokenTicker ?? meta.tokenSymbol ?? meta.symbol ?? id.slice(0, 6);
-                    out.push({
-                        id,
-                        name: meta.tokenName ?? meta.name ?? ticker,
-                        ticker,
-                        precision: decimals,
-                        protocol: 'SPARK',
-                        layer: 'SPARK_SPARK',
-                        balance: {
-                            total: owned,
-                            available,
-                            pending: 0,
-                            totalDisplay: String(owned),
-                            availableDisplay: String(available),
-                        },
-                        capabilities: {
-                            canSend: true,
-                            canReceive: true,
-                            canSwap: true,
-                            supportsLightning: false,
-                            supportsOnchain: false,
-                        },
-                    });
+        const assets = [btc];
+        if (tokenBalances && tokenBalances.size > 0) {
+            for (const [tokenId, info] of tokenBalances) {
+                const meta = info.tokenMetadata;
+                const owned = Number(info.ownedBalance);
+                const available = Number(info.availableToSendBalance);
+                const precision = meta.decimals ?? 8;
+                assets.push({
+                    id: tokenId,
+                    name: meta.tokenName,
+                    ticker: meta.tokenTicker,
+                    icon: meta.tokenImageUrl,
+                    precision,
+                    protocol: 'SPARK',
+                    layer: 'SPARK_SPARK',
+                    balance: {
+                        total: owned,
+                        available,
+                        pending: 0,
+                        locked: owned - available,
+                        totalDisplay: formatAmount(owned, precision),
+                        availableDisplay: formatAmount(available, precision),
+                    },
+                    capabilities: {
+                        canSend: true,
+                        canReceive: true,
+                        canSwap: false,
+                        supportsLightning: false,
+                        supportsOnchain: false,
+                    },
                 });
             }
         }
-        catch {
-            // tokens are best-effort — keep BTC even if the token map is unavailable
-        }
-        return out;
-    }
-    async getAssetBalance(assetId) {
-        const assets = await this.listAssets();
-        const found = assets.find((a) => a.id === assetId);
-        if (!found)
-            throw new ProtocolError(`Unknown asset ${assetId}`, 'SPARK', 'NO_ASSET');
-        return found.balance;
+        return assets;
     }
     async getAsset(assetId) {
         const assets = await this.listAssets();
-        const found = assets.find((a) => a.id === assetId);
+        const found = assets.find((a) => a.id === assetId || a.ticker === assetId);
         if (!found)
-            throw new ProtocolError(`Unknown asset ${assetId}`, 'SPARK', 'NO_ASSET');
+            throw new ProtocolError(`Asset not found: ${assetId}`, 'SPARK', 'ASSET_NOT_FOUND');
         return found;
     }
+    async getAssetBalance(assetId) {
+        const found = await this.getAsset(assetId);
+        return found.balance;
+    }
     // --- Invoices / receive amounts ----------------------------------------
     async createInvoice(request) {
         this.assertConnected();
         const expiresAt = Date.now() + (request.expirySeconds ?? 3600) * 1000;
         // 1) Lightning receive (BOLT11) — when the caller targets the LN layer.
         if (request.layer === 'BTC_LN') {
-            // WDK createLightningInvoice({ amountSats, memo, expirySeconds }): LightningReceiveRequest
             const r = await this.account.createLightningInvoice({
                 amountSats: request.amount ?? 0,
                 memo: request.description,
                 expirySeconds: request.expirySeconds,
             });
-            const encoded = r?.invoice?.encodedInvoice ?? r?.encodedInvoice ?? r?.invoice ?? '';
+            const inv = r?.invoice ?? {};
+            const encoded = inv?.encodedInvoice ?? r?.encodedInvoice ?? r?.invoice ?? '';
+            // Track the receive-request id so getInvoiceStatus can poll it later.
+            if (r?.id && encoded)
+                this.invoiceRequestIds.set(encoded, r.id);
             return {
                 invoice: encoded,
-                paymentHash: r?.invoice?.paymentHash ?? r?.id ?? '',
+                paymentHash: inv?.paymentHash ?? r?.id ?? '',
                 amount: request.amount,
-                expiresAt,
+                expiresAt: parseSdkExpiryMs(inv?.expiryTime ?? inv?.expiresAt) ?? expiresAt,
                 description: request.description,
             };
         }
@@ -243,65 +282,27 @@ export class SparkWdkAdapter extends BaseWdkAdapter {
         }
         // 3) Default: native Spark sats invoice — returns a SparkAddressFormat string.
         const invoice = await this.account.createSparkSatsInvoice({
-            amount: request.amount,
+            amount: request.amount || undefined,
             memo: request.description,
         });
         return { invoice, paymentHash: '', amount: request.amount, expiresAt, description: request.description };
     }
-    // --- Send ---------------------------------------------------------------
-    async sendPayment(request) {
+    /** Optional: explicit native Spark sats invoice (used by the receive UI). */
+    async createSparkInvoice(request) {
         this.assertConnected();
-        const dest = request.invoice.trim();
-        const isBolt11 = /^ln(bc|tb|bcrt)/i.test(dest);
-        const timestamp = Date.now();
-        // 1) Lightning send — WDK requires a maxFeeSats cap.
-        if (isBolt11) {
-            const r = await this.account.payLightningInvoice({
-                invoice: dest,
-                maxFeeSats: request.maxFeeSats ?? this.defaultMaxFeeSats(request.amount),
-                // Required by the underlying Spark SDK for 0-amount (amountless) invoices;
-                // for invoices that already carry an amount this must be omitted. The WDK
-                // module forwards these options verbatim to spark-sdk's payLightningInvoice.
-                ...(request.amount && request.amount > 0 ? { amountSatsToSend: request.amount } : {}),
-            });
-            return {
-                paymentHash: r?.paymentHash ?? r?.id ?? '',
-                preimage: r?.preimage,
-                amount: Number(r?.amountSats ?? request.amount ?? 0),
-                fee: Number(r?.feeSats ?? 0),
-                status: 'confirmed',
-                timestamp,
-            };
-        }
-        // 2) Plain Spark address + explicit amount → direct transfer (zero-fee).
-        if (request.amount != null) {
-            const r = await this.account.sendTransaction({ to: dest, value: request.amount });
-            return {
-                paymentHash: r?.id ?? r?.transferId ?? '',
-                amount: request.amount,
-                fee: 0, // Spark transfers are zero-fee (capability flag)
-                status: 'confirmed',
-                timestamp,
-            };
-        }
-        // 3) Encoded Spark invoice (amount embedded) → fulfill. Takes an ARRAY.
-        const res = await this.account.paySparkInvoice([{ invoice: dest }]);
-        const ok = res?.satsTransactionSuccess?.[0];
+        const invoice = await this.account.createSparkSatsInvoice({
+            amount: request.amount || undefined,
+            memo: request.description,
+            expiryTime: request.expirySeconds ? new Date(Date.now() + request.expirySeconds * 1000) : undefined,
+        });
         return {
-            paymentHash: ok?.transferResponse?.id ?? '',
-            amount: Number(request.amount ?? 0),
-            fee: 0,
-            status: ok ? 'confirmed' : 'failed',
-            timestamp,
+            invoice,
+            paymentHash: '',
+            amount: request.amount,
+            expiresAt: Date.now() + (request.expirySeconds ?? 3600) * 1000,
+            description: request.description,
         };
     }
-    /** Conservative default LN fee cap: 0.5% of amount, min 5 sats. */
-    defaultMaxFeeSats(amount) {
-        if (!amount || amount <= 0)
-            return 10;
-        return Math.max(5, Math.ceil(amount * 0.005));
-    }
-    // --- Transactions -------------------------------------------------------
     async decodeInvoice(invoice) {
         const dest = invoice.trim();
         if (isBolt11(dest)) {
@@ -311,46 +312,253 @@ export class SparkWdkAdapter extends BaseWdkAdapter {
         // Spark invoice/address — no on-device decode; surface the raw value.
         return { paymentHash: '', expiresAt: 0, destination: dest };
     }
-    async getPaymentStatus(paymentHash) {
+    // --- Send ---------------------------------------------------------------
+    async sendPayment(request) {
+        this.assertConnected();
+        const destination = request.invoice.trim();
+        const timestamp = Date.now();
+        try {
+            // 1) Lightning send (WDK account). Settles atomically — a clean return
+            //    means dispatched; its id is not queryable via getTransfer, so we
+            //    treat a non-failed return as confirmed.
+            if (isBolt11(destination)) {
+                const maxFee = request.maxFeeSats ?? request.maxFee ?? DEFAULT_MAX_FEE_SATS;
+                const result = await this.account.payLightningInvoice({
+                    invoice: destination,
+                    maxFeeSats: maxFee,
+                    // Amountless (0-sat) invoices require an explicit amount; omit otherwise.
+                    ...(request.amount && request.amount > 0 ? { amountSatsToSend: request.amount } : {}),
+                });
+                const raw = mapTransferStatus(result?.status);
+                return {
+                    paymentHash: String(result?.paymentHash ?? result?.id ?? ''),
+                    amount: Number(result?.amountSats ?? result?.totalValue ?? request.amount ?? 0),
+                    fee: Number(result?.feeSats ?? 0),
+                    status: raw === 'failed' ? 'failed' : 'confirmed',
+                    timestamp: result?.createdTime instanceof Date ? result.createdTime.getTime() : timestamp,
+                };
+            }
+            // 2) Spark address or Spark invoice (WDK account).
+            if (this.sdk?.isValidSparkAddress?.(destination)) {
+                const network = this.sdk.getNetworkFromSparkAddress(destination);
+                const decoded = this.sdk.decodeSparkAddress(destination, network);
+                if (decoded.sparkInvoiceFields) {
+                    const response = await this.account.paySparkInvoice([
+                        { invoice: destination, amount: request.amount ? BigInt(request.amount) : undefined },
+                    ]);
+                    if (response.satsTransactionErrors?.length > 0) {
+                        throw new Error(response.satsTransactionErrors[0].error.message);
+                    }
+                    const success = response.satsTransactionSuccess?.[0];
+                    if (!success)
+                        throw new Error('Spark invoice payment returned no result');
+                    const transfer = success.transferResponse;
+                    return {
+                        paymentHash: transfer.id,
+                        amount: Number(transfer.totalValue ?? 0),
+                        fee: 0,
+                        status: mapTransferStatus(transfer.status),
+                        timestamp: transfer.createdTime?.getTime() ?? timestamp,
+                    };
+                }
+                // Plain Spark address — zero-fee direct transfer.
+                const transfer = await this.account.sendTransaction({ to: destination, value: request.amount ?? 0 });
+                return {
+                    paymentHash: transfer?.id ?? transfer?.transferId ?? '',
+                    amount: Number(transfer?.totalValue ?? request.amount ?? 0),
+                    fee: 0, // Spark transfers are zero-fee (capability flag)
+                    status: transfer?.status ? mapTransferStatus(transfer.status) : 'confirmed',
+                    timestamp: transfer?.createdTime?.getTime?.() ?? timestamp,
+                };
+            }
+            // 3) On-chain BTC withdrawal (cooperative exit) via the raw wallet — the
+            //    WDK withdraw option shape differs; use the proven native path.
+            const wallet = this.rawWallet;
+            const feeQuote = await wallet.getWithdrawalFeeQuote({
+                amountSats: request.amount ?? 0,
+                withdrawalAddress: destination,
+            });
+            if (!feeQuote)
+                throw new Error('Failed to get withdrawal fee quote for on-chain exit');
+            const feeAmountSats = (feeQuote.l1BroadcastFeeMedium?.originalValue ?? 0) + (feeQuote.userFeeMedium?.originalValue ?? 0);
+            const result = await wallet.withdraw({
+                onchainAddress: destination,
+                amountSats: request.amount ?? 0,
+                exitSpeed: this.sdk?.ExitSpeed?.MEDIUM ?? 'MEDIUM',
+                feeQuoteId: feeQuote.id,
+                feeAmountSats,
+            });
+            return {
+                paymentHash: result?.id ?? '',
+                amount: request.amount ?? 0,
+                fee: result?.fee?.originalValue ?? 0,
+                status: 'pending',
+                timestamp,
+            };
+        }
+        finally {
+            // Any send attempt (success OR failure) makes the cached balance stale.
+            invalidateSparkBalanceCache();
+        }
+    }
+    async getPaymentStatus(paymentId) {
         this.assertConnected();
-        const t = await this.account.getTransactionReceipt(paymentHash).catch(() => null);
-        return { paymentHash, status: mapSparkStatus(t?.status), amount: t ? Number(t.totalValue ?? 0) : undefined };
+        // Spark may return entity ids like "SparkLightningSendRequest:uuid"; getTransactionReceipt wants the uuid.
+        const id = paymentId.includes(':') ? paymentId.split(':').pop() : paymentId;
+        const t = await this.account.getTransactionReceipt(id).catch(() => null);
+        if (!t)
+            return { paymentHash: paymentId, status: 'pending' };
+        return {
+            paymentHash: paymentId,
+            status: mapSparkStatus(t.status),
+            amount: Number(t.totalValue ?? 0),
+            timestamp: t.createdTime?.getTime?.() ?? 0,
+        };
     }
+    // --- Transactions -------------------------------------------------------
     async listTransactions(filter) {
         this.assertConnected();
-        const transfers = await this.account.getTransfers({ limit: filter?.limit ?? 50, skip: filter?.offset ?? 0 });
-        return (transfers ?? []).map((t) => this.toUnifiedTx(t));
+        const limit = filter?.limit ?? 20;
+        const offset = filter?.offset ?? 0;
+        const requestedAsset = filter?.asset?.trim();
+        const shouldFetchBtc = !requestedAsset || requestedAsset === 'BTC';
+        const shouldFetchTokens = !requestedAsset || requestedAsset !== 'BTC';
+        // BTC transfers via the WDK account — best effort; a failure here must not
+        // hide token activity (and especially not the offline send-record fallback).
+        let btcTxs = [];
+        if (shouldFetchBtc) {
+            try {
+                const transfers = await this.account.getTransfers({ limit, skip: offset });
+                btcTxs = (transfers ?? []).map((t) => this.toUnifiedTx(t));
+            }
+            catch {
+                /* isolated */
+            }
+        }
+        // Token transactions via the raw wallet — every RPC below is best-effort and
+        // isolated so a transport failure never hides locally-recorded sends (the only
+        // reliable record of an outgoing token transfer with no change output).
+        const tokenTxs = [];
+        if (shouldFetchTokens) {
+            try {
+                const wallet = this.rawWallet;
+                const requestedTokenRawId = requestedAsset && requestedAsset !== 'BTC' ? rawTokenIdFromBech32mTokenId(requestedAsset) : '';
+                // spark-converters statically imports the SDK — dynamic-import so this
+                // sub-path stays SDK-free until token history is actually requested.
+                const { convertTokenTransactionToUnified, buildSentRecordTransaction } = await import('../../lib/spark-converters.js');
+                const sparkAddress = await wallet.getSparkAddress();
+                const identityPubKey = await wallet.getIdentityPublicKey();
+                let networkType = '';
+                try {
+                    networkType = this.sdk.getNetworkFromSparkAddress(sparkAddress);
+                }
+                catch {
+                    /* non-fatal */
+                }
+                const tokenMetaMap = new Map();
+                const rawTokenMetaMap = new Map();
+                try {
+                    const { tokenBalances } = await wallet.getBalance();
+                    if (tokenBalances) {
+                        for (const [tokenId, info] of tokenBalances) {
+                            const meta = {
+                                name: info.tokenMetadata.tokenName,
+                                ticker: info.tokenMetadata.tokenTicker,
+                                decimals: info.tokenMetadata.decimals,
+                            };
+                            tokenMetaMap.set(tokenId, meta);
+                            const rawTokenId = rawTokenIdFromBytes(info.tokenMetadata.rawTokenIdentifier);
+                            if (rawTokenId)
+                                rawTokenMetaMap.set(rawTokenId, { id: tokenId, meta });
+                        }
+                    }
+                }
+                catch {
+                    /* isolated */
+                }
+                const allSentRecords = await loadSentTokenRecords();
+                const walletSentRecords = allSentRecords.filter((r) => r.senderSparkAddress === sparkAddress);
+                const sentRecords = requestedAsset && requestedAsset !== 'BTC'
+                    ? walletSentRecords.filter((r) => tokenRefsMatch(r.assetId, requestedAsset))
+                    : walletSentRecords;
+                const sentHashSet = new Set(sentRecords.map((r) => normalizeTxHash(r.hash)));
+                const storedRecordMap = new Map(sentRecords.map((r) => [normalizeTxHash(r.hash), r]));
+                const storedAmountMap = new Map(sentRecords.map((r) => [normalizeTxHash(r.hash), BigInt(Math.round(r.amount || 0))]));
+                const txsWithStatus = [];
+                try {
+                    const result = await wallet.queryTokenTransactions({
+                        ownerPublicKeys: [identityPubKey],
+                        tokenIdentifiers: requestedAsset && requestedAsset !== 'BTC' ? [requestedAsset] : undefined,
+                        pageSize: limit,
+                    });
+                    txsWithStatus.push(...(result.tokenTransactionsWithStatus ?? []));
+                }
+                catch {
+                    /* isolated */
+                }
+                // Sends with no change output are invisible to the owner-filtered query — fetch by hash.
+                if (sentRecords.length > 0) {
+                    try {
+                        const sentResult = await wallet.queryTokenTransactionsByTxHashes(sentRecords.map((r) => normalizeTxHash(r.hash)));
+                        const existing = new Set(txsWithStatus.map((t) => txHashFromBytes(t.tokenTransactionHash)));
+                        for (const sentTx of sentResult.tokenTransactionsWithStatus ?? []) {
+                            if (!existing.has(txHashFromBytes(sentTx.tokenTransactionHash)))
+                                txsWithStatus.push(sentTx);
+                        }
+                    }
+                    catch {
+                        /* isolated */
+                    }
+                }
+                const renderedSendHashes = new Set();
+                for (const txWithStatus of txsWithStatus) {
+                    const converted = convertTokenTransactionToUnified(txWithStatus, identityPubKey, tokenMetaMap, rawTokenMetaMap, sentHashSet, storedRecordMap, storedAmountMap, networkType, requestedAsset && requestedAsset !== 'BTC' ? requestedAsset : undefined, requestedTokenRawId);
+                    if (converted) {
+                        tokenTxs.push(converted);
+                        const hash = txHashFromBytes(txWithStatus.tokenTransactionHash);
+                        if (sentHashSet.has(hash))
+                            renderedSendHashes.add(hash);
+                    }
+                }
+                // Offline / failed-fetch fallback: synthesize from any recorded send the gateway did not return.
+                for (const record of sentRecords) {
+                    const hash = normalizeTxHash(record.hash);
+                    if (renderedSendHashes.has(hash))
+                        continue;
+                    tokenTxs.push(buildSentRecordTransaction(record, requestedAsset && requestedAsset !== 'BTC' ? requestedAsset : undefined));
+                }
+            }
+            catch {
+                /* isolated — token history is additive to BTC history */
+            }
+        }
+        const allTxs = [...btcTxs, ...tokenTxs].sort((a, b) => b.timestamp - a.timestamp);
+        return allTxs.filter((tx) => {
+            if (!filter)
+                return true;
+            if (filter.asset &&
+                tx.asset?.id !== filter.asset &&
+                tx.asset?.ticker !== filter.asset &&
+                !tokenRefsMatch(tx.asset?.id, filter.asset))
+                return false;
+            if (filter.type && tx.type !== filter.type)
+                return false;
+            if (filter.status && tx.status !== filter.status)
+                return false;
+            if (filter.fromTimestamp && tx.timestamp < filter.fromTimestamp)
+                return false;
+            if (filter.toTimestamp && tx.timestamp > filter.toTimestamp)
+                return false;
+            return true;
+        });
     }
     async getTransaction(txId) {
         this.assertConnected();
         const t = await this.account.getTransactionReceipt(txId);
         if (!t)
-            throw new ProtocolError(`Unknown tx ${txId}`, 'SPARK', 'NO_TX');
+            throw new ProtocolError(`Transaction not found: ${txId}`, 'SPARK', 'TX_NOT_FOUND');
         return this.toUnifiedTx(t);
     }
-    async getNodeInfo() {
-        return { protocol: 'SPARK', network: this.network };
-    }
-    async listChannels() {
-        return []; // Spark has no LN channels
-    }
-    /**
-     * Escape hatch: the underlying spark-sdk SparkWallet, for integrations that need the
-     * raw client (e.g. the flashnet Spark-DEX, which piggybacks on a SparkWallet). Returns
-     * the same instance this adapter uses (no duplicate wallet). Null if not connected.
-     */
-    getUnderlyingSparkWallet() {
-        return this.account?._wallet ?? null;
-    }
-    async listPayments() {
-        // Outgoing transfers only.
-        const txs = await this.listTransactions();
-        return txs.filter((t) => t.type === 'send');
-    }
-    async listTransfers() {
-        this.assertConnected();
-        return this.account.getTransfers({ limit: 100 });
-    }
     /** Map a spark-sdk Transfer (proto) → domain UnifiedTransaction (fields read defensively). */
     toUnifiedTx(t) {
         // The spark-sdk Transfer proto has no direction flag — direction is whether
@@ -387,5 +595,280 @@ export class SparkWdkAdapter extends BaseWdkAdapter {
             protocolData: t,
         };
     }
+    // --- Node & balance -----------------------------------------------------
+    async getNodeInfo() {
+        this.assertConnected();
+        const { balance } = await getSparkBalanceCached(this.rawWallet);
+        const balanceSats = Number(balance);
+        return {
+            channelsBalanceMsat: balanceSats * 1000,
+            maxPayableMsat: balanceSats * 1000,
+            onchainBalanceMsat: 0,
+            pendingOnchainBalanceMsat: 0,
+            maxReceivableMsat: 0,
+            inboundLiquidityMsats: 0,
+            connectedPeers: [],
+            utxos: 0,
+        };
+    }
+    async listChannels() {
+        return []; // Spark has no LN channels
+    }
+    async listPayments() {
+        // Outgoing transfers only.
+        const txs = await this.listTransactions();
+        return { transfers: txs.filter((t) => t.type === 'send') };
+    }
+    async listTransfers() {
+        // Spark has no RGB-style per-asset transfers.
+        return { transfers: [] };
+    }
+    /**
+     * Escape hatch: the underlying spark-sdk SparkWallet, for integrations that need the
+     * raw client (e.g. the flashnet Spark-DEX, which piggybacks on a SparkWallet). Returns
+     * the same instance this adapter uses. Null if not connected.
+     */
+    getUnderlyingSparkWallet() {
+        return this.account?._wallet ?? null;
+    }
+    // --- Deposits (L1) ------------------------------------------------------
+    async claimSparkL1Deposit(params) {
+        this.assertConnected();
+        const address = params.address?.trim();
+        if (!address)
+            return { status: 'error', error: 'address is required' };
+        const wallet = this.rawWallet;
+        let utxos;
+        try {
+            utxos = await wallet.getUtxosForDepositAddress(address, 10, 0, true);
+        }
+        catch (error) {
+            return { status: 'error', error: error instanceof Error ? error.message : 'utxo lookup failed' };
+        }
+        if (!utxos || utxos.length === 0)
+            return { status: 'awaiting' };
+        const claimedTxids = [];
+        let lastError;
+        for (const utxo of utxos) {
+            try {
+                await wallet.claimDeposit(utxo.txid);
+                claimedTxids.push(utxo.txid);
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : String(error);
+            }
+        }
+        if (claimedTxids.length === 0)
+            return { status: 'error', error: lastError ?? 'no utxos claimed' };
+        invalidateSparkBalanceCache();
+        return { status: 'claimed', txids: claimedTxids };
+    }
+    async sweepSparkL1Deposits() {
+        this.assertConnected();
+        const wallet = this.rawWallet;
+        let unused;
+        try {
+            unused = await wallet.getUnusedDepositAddresses();
+        }
+        catch (error) {
+            return {
+                addressesChecked: 0,
+                claimedTxids: [],
+                errors: [error instanceof Error ? error.message : 'getUnusedDepositAddresses failed'],
+            };
+        }
+        if (!unused || unused.length === 0)
+            return { addressesChecked: 0, claimedTxids: [], errors: [] };
+        const claimedTxids = [];
+        const errors = [];
+        for (const addr of unused) {
+            try {
+                const utxos = await wallet.getUtxosForDepositAddress(addr, 10, 0, true);
+                if (!utxos || utxos.length === 0)
+                    continue;
+                for (const utxo of utxos) {
+                    try {
+                        await wallet.claimDeposit(utxo.txid);
+                        claimedTxids.push(utxo.txid);
+                    }
+                    catch (claimErr) {
+                        errors.push(claimErr instanceof Error ? claimErr.message : String(claimErr));
+                    }
+                }
+            }
+            catch (lookupErr) {
+                errors.push(lookupErr instanceof Error ? lookupErr.message : String(lookupErr));
+            }
+        }
+        if (claimedTxids.length > 0)
+            invalidateSparkBalanceCache();
+        return { addressesChecked: unused.length, claimedTxids, errors };
+    }
+    // --- On-chain / asset send ---------------------------------------------
+    async sendBtcOnchain(params) {
+        this.assertConnected();
+        const wallet = this.rawWallet;
+        try {
+            const feeQuote = await wallet.getWithdrawalFeeQuote({
+                amountSats: params.amount,
+                withdrawalAddress: params.address,
+            });
+            if (!feeQuote)
+                throw new Error('Failed to get withdrawal fee quote');
+            const feeAmountSats = (feeQuote.l1BroadcastFeeMedium?.originalValue ?? 0) + (feeQuote.userFeeMedium?.originalValue ?? 0);
+            const result = await wallet.withdraw({
+                onchainAddress: params.address,
+                amountSats: params.amount,
+                exitSpeed: this.sdk?.ExitSpeed?.MEDIUM ?? 'MEDIUM',
+                feeQuoteId: feeQuote.id,
+                feeAmountSats,
+            });
+            return result;
+        }
+        finally {
+            invalidateSparkBalanceCache();
+        }
+    }
+    async sendAsset(params) {
+        this.assertConnected();
+        const wallet = this.rawWallet;
+        const assignmentAmount = params.assignment?.value;
+        const tokenAmount = typeof assignmentAmount === 'number' && assignmentAmount > 0 ? assignmentAmount : params.amount;
+        if (!Number.isFinite(tokenAmount) || tokenAmount <= 0) {
+            throw new ProtocolError('Spark token amount must be greater than 0', 'SPARK', 'SEND_ASSET_ERROR');
+        }
+        const destination = params.recipientId.trim();
+        const senderSparkAddress = await wallet.getSparkAddress();
+        // Resolve token metadata for the send-record (cached balance is warm from the send UI).
+        let sentMeta = { ticker: 'TOKEN', name: params.assetId, decimals: 0 };
+        try {
+            const { tokenBalances } = await getSparkBalanceCached(wallet);
+            const info = tokenBalances?.get(params.assetId);
+            if (info) {
+                sentMeta = {
+                    ticker: info.tokenMetadata.tokenTicker,
+                    name: info.tokenMetadata.tokenName,
+                    decimals: info.tokenMetadata.decimals,
+                };
+            }
+        }
+        catch {
+            /* non-critical */
+        }
+        try {
+            // Spark token invoice → fulfillSparkInvoice.
+            if (this.sdk?.isValidSparkAddress?.(destination)) {
+                const network = this.sdk.getNetworkFromSparkAddress(destination);
+                const decoded = this.sdk.decodeSparkAddress(destination, network);
+                if (decoded.sparkInvoiceFields) {
+                    const response = await wallet.fulfillSparkInvoice([
+                        { invoice: destination, amount: BigInt(tokenAmount) },
+                    ]);
+                    if (response.tokenTransactionErrors?.length > 0)
+                        throw new Error(response.tokenTransactionErrors[0].error.message);
+                    if (response.invalidInvoices?.length > 0)
+                        throw new Error(response.invalidInvoices[0].error.message);
+                    const success = response.tokenTransactionSuccess?.[0];
+                    if (success) {
+                        await saveSentTokenRecord({
+                            hash: success.txid,
+                            senderSparkAddress,
+                            amount: tokenAmount,
+                            assetId: params.assetId,
+                            ...sentMeta,
+                            timestamp: Date.now(),
+                        });
+                        invalidateSparkBalanceCache();
+                        return { txId: success.txid };
+                    }
+                    const satsSuccess = response.satsTransactionSuccess?.[0];
+                    if (satsSuccess)
+                        return { txId: satsSuccess.transferResponse.id };
+                    throw new Error('Spark invoice payment returned no result');
+                }
+            }
+            // Plain Spark address → transferTokens.
+            const txId = await wallet.transferTokens({
+                tokenIdentifier: params.assetId,
+                tokenAmount: BigInt(tokenAmount),
+                receiverSparkAddress: destination,
+            });
+            await saveSentTokenRecord({
+                hash: txId,
+                senderSparkAddress,
+                amount: tokenAmount,
+                assetId: params.assetId,
+                ...sentMeta,
+                timestamp: Date.now(),
+            });
+            invalidateSparkBalanceCache();
+            return { txId };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            throw new ProtocolError(`Failed to send Spark token: ${msg}`, 'SPARK', 'SEND_ASSET_ERROR', error);
+        }
+    }
+    // --- Invoice status -----------------------------------------------------
+    async getInvoiceStatus(params) {
+        this.assertConnected();
+        const requestId = this.invoiceRequestIds.get(params.invoice);
+        if (!requestId)
+            return { status: 'Pending' }; // untracked (e.g. previous session)
+        try {
+            const request = await this.rawWallet.getLightningReceiveRequest(requestId);
+            if (!request)
+                return { status: 'Pending' };
+            const s = request.status;
+            if (s === 'LIGHTNING_PAYMENT_RECEIVED' || s === 'TRANSFER_COMPLETED' || s === 'PAYMENT_PREIMAGE_RECOVERED') {
+                this.invoiceRequestIds.delete(params.invoice);
+                return { status: 'Succeeded' };
+            }
+            if (s === 'TRANSFER_FAILED' ||
+                s === 'TRANSFER_CREATION_FAILED' ||
+                s === 'REFUND_SIGNING_COMMITMENTS_QUERYING_FAILED' ||
+                s === 'REFUND_SIGNING_FAILED' ||
+                s === 'PAYMENT_PREIMAGE_RECOVERING_FAILED') {
+                this.invoiceRequestIds.delete(params.invoice);
+                return { status: 'Failed' };
+            }
+            return { status: 'Pending' };
+        }
+        catch {
+            return { status: 'Pending' };
+        }
+    }
+    // --- RGB (not supported by Spark) --------------------------------------
+    async createRgbInvoice() {
+        throw new ProtocolError('RGB invoices not supported by Spark', 'SPARK', 'NOT_SUPPORTED');
+    }
+    async decodeRgbInvoice() {
+        throw new ProtocolError('RGB invoice decoding not supported by Spark', 'SPARK', 'NOT_SUPPORTED');
+    }
+    // --- Message / PSBT signing --------------------------------------------
+    async signPsbt(psbtHex) {
+        if (!this.mnemonic)
+            throw new ProtocolError('Wallet mnemonic not available', 'SPARK', 'NOT_CONNECTED');
+        const { signPsbt: doSign } = await import('../../lib/psbt-signer.js');
+        const result = doSign(psbtHex, this.mnemonic);
+        return { psbt: result.psbt, unchanged: result.unchanged };
+    }
+    async signMessage(message) {
+        if (!this.mnemonic)
+            throw new ProtocolError('Wallet mnemonic not available', 'SPARK', 'NOT_CONNECTED');
+        const { mnemonicToSeedSync } = await import('@scure/bip39');
+        const { HDKey } = await import('@scure/bip32');
+        const seed = mnemonicToSeedSync(this.mnemonic);
+        const root = HDKey.fromMasterSeed(seed);
+        // m/138'/1 — wallet-identity message-signing key (distinct from LNURL-auth's m/138'/0).
+        const node = root.derive("m/138'/1");
+        if (!node.privateKey) {
+            throw new ProtocolError('Failed to derive message-signing key', 'SPARK', 'KEY_DERIVATION_ERROR');
+        }
+        return signLnMessage(message, node.privateKey);
+    }
+    async verifyMessage(message, signature) {
+        return verifyLnMessage(message, signature);
+    }
 }
 //# sourceMappingURL=SparkWdkAdapter.js.map