@breeztech/breez-sdk-spark 0.19.2 → 0.20.0-dev1

package/itest/smoke.test.js

@@ -0,0 +1,184 @@
+'use strict'
+
+// Smoke test for the npm package API, exercised the way the reference web
+// app uses it (packages/wasm/examples/web): SdkBuilder + default storage,
+// events, receive, parse, send between two instances, payment listing, and
+// lnurl-pay against the docker LNURL fixture. Deep per-command behavior
+// lives in the shared CLI scenarios; this pins the API surface itself.
+
+require('dotenv').config()
+
+const assert = require('node:assert/strict')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const test = require('node:test')
+
+const { defaultConfig, SdkBuilder } = require('@breeztech/breez-sdk-spark/nodejs')
+
+const { fundAddress } = require('./helpers/faucet')
+const { LnurlFixture, dockerAvailable } = require('./helpers/lnurl-fixture')
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/** Queue-backed event listener with a predicate wait. */
+class EventQueue {
+  constructor() {
+    this.events = []
+  }
+
+  onEvent(event) {
+    this.events.push(event)
+  }
+
+  async waitFor(predicate, timeoutMs) {
+    const deadline = Date.now() + timeoutMs
+    for (;;) {
+      const event = this.events.find(predicate)
+      if (event !== undefined) {
+        return event
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `timed out waiting for event; seen: ${this.events.map((e) => e.type).join(', ')}`
+        )
+      }
+      await sleep(200)
+    }
+  }
+}
+
+async function connectWallet(name, lnurlDomain) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `breez-smoke-${name}-`))
+  let sdk
+  try {
+    const config = defaultConfig('regtest')
+    if (lnurlDomain !== undefined) {
+      config.lnurlDomain = lnurlDomain
+    }
+    const mnemonic = require('bip39').generateMnemonic()
+    let builder = SdkBuilder.new(config, { type: 'mnemonic', mnemonic })
+    builder = await builder.withDefaultStorage(dir)
+    sdk = await builder.build()
+    const events = new EventQueue()
+    await sdk.addEventListener(events)
+    return { sdk, events, dir }
+  } catch (e) {
+    // Partial failure leaves nothing behind: the caller only cleans up
+    // wallets it received.
+    await sdk?.disconnect().catch(() => {})
+    fs.rmSync(dir, { recursive: true, force: true })
+    throw e
+  }
+}
+
+async function waitForBalance(sdk, floorSats, timeoutMs) {
+  const deadline = Date.now() + timeoutMs
+  for (;;) {
+    const info = await sdk.getInfo({ ensureSynced: true })
+    if (info.balanceSats >= floorSats) {
+      return info
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(`balance stayed below ${floorSats} (last: ${info.balanceSats})`)
+    }
+    await sleep(5000)
+  }
+}
+
+test('npm API smoke: connect, receive, parse, pay, list, lnurl-pay', async (t) => {
+  if (!process.env.FAUCET_USERNAME) {
+    t.skip('FAUCET_USERNAME not set')
+    return
+  }
+  const haveDocker = dockerAvailable()
+
+  let lnurl
+  const wallets = []
+  try {
+    if (haveDocker) {
+      lnurl = await LnurlFixture.start()
+    }
+    const alice = await connectWallet('alice')
+    wallets.push(alice)
+    const bob = await connectWallet('bob', lnurl?.httpUrl)
+    wallets.push(bob)
+
+    // Balance and event surface on a fresh wallet.
+    const info = await alice.sdk.getInfo({ ensureSynced: true })
+    assert.equal(info.balanceSats, 0)
+    assert.equal(typeof info.identityPubkey, 'string')
+    await alice.events.waitFor((e) => e.type === 'synced', 30_000)
+
+    // Receive requests and parsing.
+    const bolt11 = await alice.sdk.receivePayment({
+      paymentMethod: { type: 'bolt11Invoice', description: 'smoke test', amountSats: 2500 }
+    })
+    const parsed = await alice.sdk.parse(bolt11.paymentRequest)
+    assert.equal(parsed.type, 'bolt11Invoice')
+    assert.equal(parsed.amountMsat, 2_500_000)
+    assert.equal(parsed.description, 'smoke test')
+
+    const bobAddress = await bob.sdk.receivePayment({ paymentMethod: { type: 'sparkAddress' } })
+    assert.equal((await bob.sdk.parse(bobAddress.paymentRequest)).type, 'sparkAddress')
+
+    // Fund alice through an on-chain deposit and wait for the auto-claim.
+    const deposit = await alice.sdk.receivePayment({ paymentMethod: { type: 'bitcoinAddress' } })
+    await fundAddress(deposit.paymentRequest, 50_000)
+    await waitForBalance(alice.sdk, 40_000, 180_000)
+
+    // Spark payment alice -> bob.
+    const prepared = await alice.sdk.prepareSendPayment({
+      paymentRequest: { type: 'input', input: bobAddress.paymentRequest },
+      amount: 1000n
+    })
+    assert.equal(prepared.paymentMethod.type, 'sparkAddress')
+    const sent = await alice.sdk.sendPayment({ prepareResponse: prepared })
+    assert.equal(sent.payment.status, 'completed')
+    assert.equal(sent.payment.paymentType, 'send')
+
+    const fetched = await alice.sdk.getPayment({ paymentId: sent.payment.id })
+    assert.equal(fetched.payment.id, sent.payment.id)
+    const listed = await alice.sdk.listPayments({})
+    assert.ok(listed.payments.some((p) => p.id === sent.payment.id))
+
+    await waitForBalance(bob.sdk, 1000, 90_000)
+
+    // lnurl-pay against the local LNURL server (docker only).
+    if (haveDocker) {
+      const registered = await bob.sdk.registerLightningAddress({
+        username: 'smoketest',
+        description: 'smoke test address'
+      })
+      const lnAddress = await alice.sdk.parse(registered.lightningAddress)
+      assert.equal(lnAddress.type, 'lightningAddress')
+      const preparedLnurl = await alice.sdk.prepareLnurlPay({
+        amount: 1500n,
+        payRequest: lnAddress.payRequest,
+        comment: 'smoke comment'
+      })
+      // The payment can return pending: completion needs the receiver to
+      // claim, so poll until the preimage is released.
+      const paid = await alice.sdk.lnurlPay({ prepareResponse: preparedLnurl })
+      const deadline = Date.now() + 120_000
+      let status = paid.payment.status
+      while (status !== 'completed') {
+        if (Date.now() >= deadline) {
+          throw new Error(`lnurl payment stayed ${status}`)
+        }
+        await sleep(5000)
+        status = (await alice.sdk.getPayment({ paymentId: paid.payment.id })).payment.status
+      }
+    } else {
+      console.error('skipping lnurl-pay part: docker not available')
+    }
+  } finally {
+    for (const wallet of wallets) {
+      await wallet.sdk.disconnect().catch(() => {})
+      fs.rmSync(wallet.dir, { recursive: true, force: true })
+    }
+    lnurl?.stop()
+  }
+})

package/nodejs/breez_sdk_spark_wasm.d.ts

@@ -511,8 +511,10 @@ export interface BitcoinAddressDetails {
 
 export interface BitcoinChainService {
     getAddressUtxos(address: string): Promise<Utxo[]>;
+    getAddressTxos(address: string): Promise<Utxo[]>;
     getTransactionStatus(txid: string): Promise<TxStatus>;
     getTransactionHex(txid: string): Promise<string>;
+    getOutspend(txid: string, vout: number): Promise<Outspend>;
     broadcastTransaction(tx: string): Promise<void>;
     recommendedFees(): Promise<RecommendedFees>;
 }
@@ -718,6 +720,10 @@ export interface ConversionSide {
     fee: string;
 }
 
+export interface CpfpSigner {
+    signPsbt(psbtBytes: Uint8Array): Promise<Uint8Array>;
+}
+
 export interface CreateIssuerTokenRequest {
     name: string;
     ticker: string;
@@ -955,6 +961,7 @@ export interface ExternalSparkSigner {
     getStaticDepositPublicKey(index: number): Promise<PublicKeyBytes>;
     signAuthenticationChallenge(challenge: Uint8Array): Promise<EcdsaSignatureBytes>;
     signMessage(message: Uint8Array): Promise<EcdsaSignatureBytes>;
+    signLeafRefundSpend(leafId: ExternalTreeNodeId, sighash: Uint8Array): Promise<SchnorrSignatureBytes>;
     signFrost(jobs: ExternalFrostJob[]): Promise<ExternalFrostShareResult[]>;
     prepareTransfer(request: ExternalPrepareTransferRequest): Promise<ExternalPreparedTransfer>;
     prepareClaim(request: ExternalPrepareClaimRequest): Promise<ExternalPreparedClaim>;
@@ -1282,6 +1289,11 @@ export interface PaymentRequestSource {
     bip353Address?: string;
 }
 
+export interface PerBranchFunding {
+    leafId: string;
+    fundingSat: number;
+}
+
 export interface PrepareLnurlPayRequest {
     amount: bigint;
     comment?: string;
@@ -1319,6 +1331,24 @@ export interface PrepareSendPaymentResponse {
     feePolicy: FeePolicy;
 }
 
+export interface PrepareUnilateralExitRequest {
+    feeRateSatPerVbyte: number;
+    fundingKind: CpfpFundingKind;
+    destination: string;
+    selection: ExitLeafSelection;
+}
+
+export interface PrepareUnilateralExitResponse {
+    leaves: UnilateralExitLeaf[];
+    recoverableValueSat: number;
+    totalFeeSat: number;
+    fanoutFeeSat: number;
+    singleUtxoFundingSat: number;
+    perBranchFunding: PerBranchFunding[];
+    feeRateSatPerVbyte: number;
+    destination: string;
+}
+
 export interface ProvisionalPayment {
     paymentId: string;
     amount: bigint;
@@ -1394,6 +1424,12 @@ export interface RefundDepositResponse {
     txHex: string;
 }
 
+export interface RefundPendingConversionsResponse {
+    refunded: number;
+    skipped: number;
+    failed: number;
+}
+
 export interface RegisterLightningAddressRequest {
     username: string;
     description?: string;
@@ -1701,6 +1737,34 @@ export interface UnfreezeIssuerTokenResponse {
     impactedTokenAmount: bigint;
 }
 
+export interface UnilateralExitLeaf {
+    leafId: string;
+    value: number;
+}
+
+export interface UnilateralExitRequest {
+    prepared: PrepareUnilateralExitResponse;
+    fundingInputs: CpfpInput[];
+}
+
+export interface UnilateralExitResponse {
+    recoverableValueSat: number;
+    totalFeeSat: number;
+    leaves: UnilateralExitLeaf[];
+    transactions: UnilateralExitTransaction[];
+}
+
+export interface UnilateralExitTransaction {
+    kind: UnilateralExitTxKind;
+    nodeId?: string;
+    txid: string;
+    txHex: string;
+    cpfpTxHex?: string;
+    csvTimelockBlocks?: number;
+    dependsOn: string[];
+    status: ConfirmationStatus;
+}
+
 export interface UnregisterWebhookRequest {
     webhookId: string;
 }
@@ -1720,6 +1784,7 @@ export interface UpdateContactRequest {
 export interface UpdateUserSettingsRequest {
     sparkPrivateModeEnabled?: boolean;
     stableBalanceActiveLabel?: StableBalanceActiveLabel;
+    sparkMasterIdentityPublicKey?: SparkMasterIdentityPublicKey;
 }
 
 export interface UrlSuccessActionData {
@@ -1731,6 +1796,7 @@ export interface UrlSuccessActionData {
 export interface UserSettings {
     sparkPrivateModeEnabled: boolean;
     stableBalanceActiveLabel?: string;
+    sparkMasterIdentityPublicKey?: string;
 }
 
 export interface Utxo {
@@ -1764,6 +1830,8 @@ export type BuyBitcoinRequest = { type: "moonpay"; lockedAmountSat?: number; red
 
 export type ChainApiType = "esplora" | "mempoolSpace";
 
+export type ConfirmationStatus = "confirmed" | "unconfirmed" | "unverified";
+
 export type ConversionChain = { type: "spark" } | { type: "lightning" } | { type: "external"; name: string; chainId?: string };
 
 export type ConversionFilter = "ammRefundNeeded" | "orchestraPending" | "boltzPending";
@@ -1778,6 +1846,10 @@ export type ConversionStatus = "pending" | "completed" | "failed" | "refundNeede
 
 export type ConversionType = { type: "fromBitcoin" } | { type: "toBitcoin"; fromTokenIdentifier: string };
 
+export type CpfpFundingKind = { type: "p2wpkh" } | { type: "p2tr" } | { type: "custom"; scriptPubkeyHex: string; signedInputWeight: number };
+
+export type CpfpInput = { type: "p2wpkh"; txid: string; vout: number; value: number; pubkey: string } | { type: "p2tr"; txid: string; vout: number; value: number; pubkey: string } | { type: "custom"; txid: string; vout: number; value: number; scriptPubkeyHex: string; signedInputWeight: number };
+
 export type CrossChainAddressFamily = "evm" | "solana" | "tron";
 
 export type CrossChainFeeMode = "feesExcluded" | "feesIncluded";
@@ -1790,6 +1862,8 @@ export type CrossChainRouteFilter = { type: "send"; addressDetails: CrossChainAd
 
 export type DepositClaimError = { type: "maxDepositClaimFeeExceeded"; tx: string; vout: number; maxFee?: Fee; requiredFeeSats: number; requiredFeeRateSatPerVbyte: number } | { type: "missingUtxo"; tx: string; vout: number } | { type: "generic"; message: string };
 
+export type ExitLeafSelection = { type: "auto" } | { type: "specific"; leafIds: string[] };
+
 export type ExternalFrostDerivation = { type: "signingLeaf"; leafId: ExternalTreeNodeId } | { type: "staticDeposit"; index: number } | { type: "htlcPreimage" } | { type: "identity" };
 
 export type ExternalSparkInvoiceKind = "sats" | "tokens";
@@ -1814,6 +1888,8 @@ export type OptimizationMode = "full" | "singleRound";
 
 export type OptimizationOutcome = { type: "completed"; roundsExecuted: number } | { type: "inProgress" };
 
+export type Outspend = { type: "unspent" } | { type: "spent"; txid: string; vin: number; status: TxStatus };
+
 export type PaymentDetails = { type: "spark"; invoiceDetails?: SparkInvoicePaymentDetails; htlcDetails?: SparkHtlcDetails; conversionInfo?: ConversionInfo } | { type: "token"; metadata: TokenMetadata; txHash: string; txType: TokenTransactionType; invoiceDetails?: SparkInvoicePaymentDetails; conversionInfo?: ConversionInfo } | { type: "lightning"; description?: string; invoice: string; destinationPubkey: string; htlcDetails: SparkHtlcDetails; lnurlPayInfo?: LnurlPayInfo; lnurlWithdrawInfo?: LnurlWithdrawInfo; lnurlReceiveMetadata?: LnurlReceiveMetadata; conversionInfo?: ConversionInfo } | { type: "withdraw"; txId: string } | { type: "deposit"; txId: string; vout: number };
 
 export type PaymentDetailsFilter = { type: "spark"; htlcStatus?: SparkHtlcStatus[]; conversionRefundNeeded?: boolean } | { type: "token"; conversionRefundNeeded?: boolean; txHash?: string; txType?: TokenTransactionType } | { type: "lightning"; htlcStatus?: SparkHtlcStatus[] };
@@ -1850,6 +1926,8 @@ export type SourceAsset = { type: "bitcoin" } | { type: "token"; tokenIdentifier
 
 export type SparkHtlcStatus = "waitingForPreimage" | "preimageShared" | "returned";
 
+export type SparkMasterIdentityPublicKey = { type: "set"; publicKey: string } | { type: "unset" };
+
 export type StableBalanceActiveLabel = { type: "set"; label: string } | { type: "unset" };
 
 export type StoragePaymentDetailsFilter = { type: "spark"; htlcStatus?: SparkHtlcStatus[]; conversionFilter?: ConversionFilter } | { type: "token"; conversionFilter?: ConversionFilter; txHash?: string; txType?: TokenTransactionType } | { type: "lightning"; htlcStatus?: SparkHtlcStatus[]; conversionFilter?: ConversionFilter };
@@ -1864,6 +1942,8 @@ export type TransferSignature = { type: "transfer"; signed: ExternalPreparedTran
 
 export type TransferTarget = { type: "spark"; address: string; sparkInvoice?: string } | { type: "lightning"; bolt11: string; lnurlPay?: LnurlPayContext; feePolicy: FeePolicy; completionTimeoutSecs?: number } | { type: "coopExit"; address: string; feeQuote: SendOnchainFeeQuote; confirmationSpeed: OnchainConfirmationSpeed };
 
+export type UnilateralExitTxKind = "fanOut" | "node" | "refund" | "sweep";
+
 export type UnsignedTransferPackage = { type: "swap"; prepareTransfer: ExternalPrepareTransferRequest; targetAmounts: number[]; amountSat: number; feeSat: number } | { type: "transfer"; prepareTransfer: ExternalPrepareTransferRequest; amountSat: number; feeSat: number; target: TransferTarget } | { type: "token"; prepareTokenTransaction: ExternalPrepareTokenTransactionRequest; tokenContext: number[]; tokenIdentifier: string; amount: string; fee: string; isSwap: boolean };
 
 export type UpdateDepositPayload = { type: "claimError"; error: DepositClaimError } | { type: "refund"; refundTxid: string; refundTx: string };
@@ -1884,7 +1964,9 @@ export class BitcoinChainServiceHandle {
     free(): void;
     [Symbol.dispose](): void;
     broadcastTransaction(tx: string): Promise<void>;
+    getAddressTxos(address: string): Promise<any>;
     getAddressUtxos(address: string): Promise<any>;
+    getOutspend(txid: string, vout: number): Promise<any>;
     getTransactionHex(txid: string): Promise<any>;
     getTransactionStatus(txid: string): Promise<any>;
     recommendedFees(): Promise<any>;
@@ -1929,23 +2011,35 @@ export class BreezSdk {
     parse(input: string): Promise<InputType>;
     prepareLnurlPay(request: PrepareLnurlPayRequest): Promise<PrepareLnurlPayResponse>;
     prepareSendPayment(request: PrepareSendPaymentRequest): Promise<PrepareSendPaymentResponse>;
+    prepareUnilateralExit(request: PrepareUnilateralExitRequest): Promise<PrepareUnilateralExitResponse>;
     publishSignedLnurlPayPackage(request: PublishSignedLnurlPayPackageRequest): Promise<PublishSignedLnurlPayResponse>;
     publishSignedTransferPackage(request: PublishSignedTransferPackageRequest): Promise<PublishSignedTransferPackageResponse>;
     receivePayment(request: ReceivePaymentRequest): Promise<ReceivePaymentResponse>;
     recommendedFees(): Promise<RecommendedFees>;
     refundDeposit(request: RefundDepositRequest): Promise<RefundDepositResponse>;
-    refundPendingConversions(): Promise<void>;
+    refundPendingConversions(): Promise<RefundPendingConversionsResponse>;
     registerLightningAddress(request: RegisterLightningAddressRequest): Promise<LightningAddressInfo>;
     registerWebhook(request: RegisterWebhookRequest): Promise<RegisterWebhookResponse>;
     removeEventListener(id: string): Promise<boolean>;
     sendPayment(request: SendPaymentRequest): Promise<SendPaymentResponse>;
     signMessage(request: SignMessageRequest): Promise<SignMessageResponse>;
     syncWallet(request: SyncWalletRequest): Promise<SyncWalletResponse>;
+    unilateralExit(request: UnilateralExitRequest, signer: CpfpSigner): Promise<UnilateralExitResponse>;
     unregisterWebhook(request: UnregisterWebhookRequest): Promise<void>;
     updateContact(request: UpdateContactRequest): Promise<Contact>;
     updateUserSettings(request: UpdateUserSettingsRequest): Promise<void>;
 }
 
+/**
+ * A CPFP signer matching the `CpfpSigner` TypeScript interface.
+ */
+export class DefaultCpfpSigner {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    signPsbt(psbt_bytes: Uint8Array): Promise<Uint8Array>;
+}
+
 /**
  * A JS handle to a backend's own session store (from `defaultSessionStore`),
  * exposing the same `getSession` / `setSession` interface. Wrap it in a JS
@@ -2041,6 +2135,7 @@ export class ExternalSparkSignerHandle {
     prepareTransfer(request: ExternalPrepareTransferRequest): Promise<ExternalPreparedTransfer>;
     signAuthenticationChallenge(challenge: Uint8Array): Promise<EcdsaSignatureBytes>;
     signFrost(jobs: ExternalFrostJob[]): Promise<ExternalFrostShareResult[]>;
+    signLeafRefundSpend(leaf_id: ExternalTreeNodeId, sighash: Uint8Array): Promise<SchnorrSignatureBytes>;
     signMessage(message: Uint8Array): Promise<EcdsaSignatureBytes>;
     signSparkInvoice(request: ExternalSignSparkInvoiceRequest): Promise<ExternalSignedSparkInvoice>;
     signStaticDepositRefund(request: ExternalSignStaticDepositRefundRequest): Promise<ExternalFrostSignature>;
@@ -2365,6 +2460,11 @@ export function newSharedSdkContext(config: WasmSdkContextConfig): Promise<WasmS
  */
 export function postgresStorage(config: PostgresStorageConfig): WasmStorageConfig;
 
+/**
+ * Creates a default CPFP signer backed by a single private key.
+ */
+export function singleKeyCpfpSigner(secret_key_bytes: Uint8Array): DefaultCpfpSigner;
+
 /**
  * Runs automatically when the wasm module is instantiated. Installs the
  * panic hook so Rust panics surface as readable `console.error` output