@qntx/spark 0.0.0-stage → 0.1.1

package/dist/index-B_g3vHnT.d.mts

@@ -0,0 +1,820 @@
+import { i as SparkOperatorConfig, n as SparkNetwork, o as Signature, r as SparkNetworkConfig } from "./lightning-address-CRULmi9v.mjs";
+import { g as SparkSigner } from "./types-jBCznYd6.mjs";
+import "@bufbuild/protobuf/codegenv2";
+import "@bufbuild/protobuf/wkt";
+import { Message, UnknownEnum } from "@bufbuild/protobuf";
+import "@connectrpc/connect";
+import "@scure/btc-signer/utils.js";
+//#region src/connection/index.d.ts
+/**
+ * A Spark protocol event delivered by the coordinator's `subscribe_to_events` stream. Plain types;
+ * unknown oneof variants are skipped.
+ */
+type SparkEvent = {
+  readonly type: "connected";
+} | {
+  readonly type: "heartbeat";
+} | {
+  readonly type: "transfer";
+  readonly direction: "incoming" | "outgoing";
+  readonly transferId: string;
+  readonly senderIdentityPublicKey: Uint8Array;
+  readonly receiverIdentityPublicKey: Uint8Array;
+} | {
+  readonly type: "deposit";
+  readonly leafId: string;
+} | {
+  readonly type: "token-transaction";
+  readonly transactionHash: Uint8Array;
+  readonly tokenIdentifiers: ReadonlyArray<Uint8Array>;
+};
+//#endregion
+//#region src/tree/index.d.ts
+type SparkLeaf = {
+  readonly id: string;
+  readonly treeId: string;
+  readonly valueSats: number;
+  readonly status: string;
+  readonly nodeTx: Uint8Array;
+  readonly refundTx: Uint8Array;
+  readonly directTx?: Uint8Array;
+  readonly directRefundTx?: Uint8Array;
+  readonly directFromCpfpRefundTx?: Uint8Array;
+  readonly verifyingPublicKey: Uint8Array;
+  readonly ownerIdentityPublicKey: Uint8Array;
+  readonly ownerSigningPublicKey: Uint8Array;
+  readonly signingKeyshare: {
+    readonly ownerIdentifiers: ReadonlyArray<string>;
+    readonly threshold: number;
+    readonly publicKey: Uint8Array;
+  };
+  readonly vout: number;
+  readonly parentNodeId?: string;
+};
+//#endregion
+//#region src/deposit/index.d.ts
+type UnusedDepositAddress = {
+  readonly address: string;
+  readonly leafId: string;
+  readonly verifyingPublicKey: Uint8Array;
+};
+//#endregion
+//#region src/ssp/types.d.ts
+/** Speed tier accepted by `request_coop_exit` (upstream `ExitSpeed`). */
+type SspCoopExitSpeed = "FAST" | "MEDIUM" | "SLOW";
+type SspCoopExitFeeQuote = {
+  readonly id: string;
+  readonly expiresAtMs: number;
+  /** `user_fee + l1_broadcast_fee` per speed, in sats. */
+  readonly fees: {
+    readonly fast: number;
+    readonly medium: number;
+    readonly slow: number;
+  };
+};
+type SspCoopExitStatus = {
+  readonly id: string;
+  readonly status: string;
+  readonly transferId?: string;
+  /** The SSP-built payout transaction, when the request record carries it. */
+  readonly rawCoopExitTransaction?: Uint8Array;
+};
+//#endregion
+//#region src/deposit/static.d.ts
+/** Upstream's minimum spend-tx fee (spark-wallet.ts MIN_SPEND_TX_FEE_SATS). */
+declare const MIN_STATIC_REFUND_FEE_SATS = 194;
+type StaticDepositUtxo = {
+  /** Display-order hex txid. */
+  readonly txid: string;
+  readonly vout: number;
+  /** Amount from the SO's `raw_tx`; absent when the SO does not return it. */
+  readonly amountSats?: number;
+  /** The deposit transaction when the SO returns it. */
+  readonly rawTx?: Uint8Array;
+};
+type StaticDepositClaim = {
+  readonly creditAmountSats: number;
+  /** `utxo amount − creditAmountSats`. */
+  readonly feeSats: number;
+  /** The SSP's inbound transfer id, when the claim response carries one. */
+  readonly transferId?: string;
+};
+type StaticDepositRefund = {
+  /** The signed refund transaction (not broadcast — broadcasting is the caller's job). */
+  readonly transaction: Uint8Array;
+  /** Display-order txid of the signed transaction. */
+  readonly txid: string;
+};
+//#endregion
+//#region src/exit/coop.d.ts
+type CooperativeExitResult = {
+  /** The cooperative-exit transfer id — the idempotency handle for retries. */
+  readonly transferId: string;
+  /** The SSP exit request id — pass to `cooperativeExitStatus`. */
+  readonly requestId: string;
+  readonly coopExitTxid: string;
+  readonly payoutSats: number;
+  readonly feeSats: number;
+  readonly status: string;
+};
+/** `FAST` | `MEDIUM` | `SLOW` — the SSP's broadcast-speed tiers. */
+type CooperativeExitSpeed = SspCoopExitSpeed;
+type CooperativeExitQuote = SspCoopExitFeeQuote;
+type CooperativeExitStatus = SspCoopExitStatus;
+//#endregion
+//#region src/exit/store.d.ts
+/**
+ * Every pre-signed transaction needed to exit one leaf unilaterally. The `directTx`,
+ * `directRefundTx` and `directFromCpfpRefundTx` fields are witness-stripped templates — the SO's
+ * DirectTransactionResponseInterceptor drops the witness from every `direct_*` transaction field it
+ * serves. Their txids still match the signed copies, so they can recognise the watchtower's
+ * broadcast on chain and feed `sweepRefund`, but the wallet can never broadcast them: the
+ * signatures exist only server-side.
+ */
+type SparkExitChain = {
+  readonly leafId: string;
+  /** Root → leaf. */
+  readonly nodes: ReadonlyArray<{
+    readonly nodeId: string;
+    readonly nodeTx: Uint8Array;
+    readonly directTx?: Uint8Array;
+  }>;
+  readonly refundTx: Uint8Array;
+  readonly directRefundTx?: Uint8Array;
+  readonly directFromCpfpRefundTx?: Uint8Array;
+};
+type SparkStore = {
+  readonly exitChains: () => Promise<ReadonlyArray<SparkExitChain>>;
+  /** Upsert by leafId. */
+  readonly putExitChains: (chains: ReadonlyArray<SparkExitChain>) => Promise<void>;
+  readonly deleteExitChains: (leafIds: ReadonlyArray<string>) => Promise<void>;
+};
+/**
+ * In-memory `SparkStore` — the default when no persistence is injected. Byte arrays are copied on
+ * write and on read so callers can never alias stored state.
+ */
+declare function createMemorySparkStore(): SparkStore;
+//#endregion
+//#region src/exit/unilateral.d.ts
+/**
+ * A pre-signed exit transaction plus the context needed to broadcast it. Broadcasting is
+ * deadline-bound: once `parentTxid` confirms and `relativeTimelock` blocks pass, this must confirm
+ * within DIRECT_TIMELOCK_OFFSET blocks or the SO watchtower replaces it with the direct variant
+ * (see the module doc).
+ */
+type ExitTransaction = {
+  /** The tree node this transaction belongs to (the leaf's id for refunds). */
+  readonly nodeId: string;
+  readonly kind: "node" | "refund";
+  /** Zero-fee v3 transaction with a P2A anchor output. */
+  readonly transaction: Uint8Array;
+  /** Display-order txid. */
+  readonly txid: string;
+  /** Display-order txid spent by input 0 (the deposit tx for a root node tx). */
+  readonly parentTxid: string;
+  /** BIP-68 blocks the input must wait after its parent confirms. */
+  readonly relativeTimelock: number;
+};
+/**
+ * Flattens stored chains into broadcast order: for each leaf's chain root→leaf, ancestor node txs
+ * deduplicated by node id at first use, then that leaf's refund right after its leaf node tx.
+ * Broadcast strictly in this order — each transaction's deadline is its parent's confirmation
+ * height plus its own relative timelock plus DIRECT_TIMELOCK_OFFSET, so a stalled package endangers
+ * every transaction below it.
+ */
+declare function exitTransactions(chains: ReadonlyArray<SparkExitChain>): ExitTransaction[];
+//#endregion
+//#region src/exit/watchtower.d.ts
+type WatchtowerExitedLeaf = {
+  readonly leafId: string;
+  readonly status: "WATCHTOWER_EXITED" | "WATCHTOWER_EXIT_RECOVERED";
+  readonly valueSats: number;
+  /** The confirmed ancestor output the leaf can still spend, when one resolves locally. */
+  readonly recovery?: {
+    readonly txid: string;
+    readonly outputIndex: number;
+    readonly valueSats: number;
+  };
+};
+//#endregion
+//#region src/lightning/receive.d.ts
+type LightningInvoice = {
+  /** The SSP lightning receive request id — pass to `lightningReceiveStatus`. */
+  readonly id: string;
+  /** The encoded BOLT-11 invoice to hand to the payer. */
+  readonly invoice: string;
+  readonly paymentHash: Uint8Array;
+  readonly amountSats: number;
+  readonly expiresAtMs: number;
+};
+//#endregion
+//#region src/lightning/send.d.ts
+type LightningPayment = {
+  /** The preimage-swap transfer id — the idempotency handle for retries. */
+  readonly transferId: string;
+  /** The SSP lightning send request id — pass to `lightningSendStatus`. */
+  readonly requestId: string;
+  readonly status: string;
+  readonly paymentHash: Uint8Array;
+  readonly amountSats: number;
+  readonly feeSats: number;
+};
+//#endregion
+//#region src/lightning/status.d.ts
+/** Coarse outcome of a lightning send, derived from the SSP status and the verified preimage. */
+type LightningSendOutcome = "pending" | "succeeded" | "failed" | "returned";
+type LightningSendStatus = {
+  readonly status: string;
+  /**
+   * "succeeded" once a verified preimage is present; "returned" once the SSP reports
+   * `USER_SWAP_RETURNED` — the leaves reappear in `leaves()` on the next sync. "failed" means the
+   * payment will not settle but the swap return has not finished — keep polling until "returned".
+   * Everything else is "pending".
+   */
+  readonly outcome: LightningSendOutcome;
+  /** The settled payment preimage — present once the SSP reports the send paid. */
+  readonly preimage?: Uint8Array;
+};
+type LightningReceiveStatus = {
+  readonly status: string;
+  /** The inbound transfer's spark id, once the SSP reports the payment arrived. */
+  readonly transferId?: string;
+  /** The settled payment preimage — verified against the request invoice's payment hash. */
+  readonly preimage?: Uint8Array;
+};
+/** A `LightningPayment` satisfies this shape — pass the pay() result straight in. */
+type LightningSendStatusRequest = {
+  readonly requestId: string;
+  /** The payment hash of the invoice we paid — the proof target, not SSP-supplied data. */
+  readonly paymentHash: Uint8Array;
+};
+/** A `LightningInvoice` satisfies this shape — pass the createInvoice result straight in. */
+type LightningReceiveStatusRequest = {
+  readonly requestId: string;
+  /** The payment hash the invoice was created for — the proof target, not SSP-supplied data. */
+  readonly paymentHash: Uint8Array;
+};
+//#endregion
+//#region src/settings/index.d.ts
+type SparkWalletSettings = {
+  /**
+   * When true, only the owner's (or master's) session may read this wallet's nodes and transfers.
+   * Other identities get no error — their queries simply come back empty (observed on hosted).
+   */
+  readonly privateEnabled: boolean;
+};
+//#endregion
+//#region src/tokens/model.d.ts
+/**
+ * Mapped `query_token_outputs` status. `"unknown"` marks an enum value this SDK does not recognize
+ * — it must never be spendable; an unset status field stays absent instead.
+ */
+type SparkTokenOutputStatus = "available" | "pending-outbound" | "unknown";
+/** One owned token output, keyed by its previous transaction location. */
+type SparkTokenOutput = {
+  readonly id: string;
+  /** Raw 32-byte token identifier (bech32m-encode for display). */
+  readonly tokenIdentifier: Uint8Array;
+  /** Decoded 128-bit amount. */
+  readonly amount: bigint;
+  readonly prevTransactionHash: Uint8Array;
+  readonly prevTransactionVout: number;
+  readonly ownerPublicKey: Uint8Array;
+  readonly status?: SparkTokenOutputStatus;
+};
+/** Aggregate balance for one token identifier, display-ready. */
+type SparkTokenBalance = {
+  /** Bech32m `btkn`/`btknrt` token identifier. */
+  readonly tokenIdentifier: string;
+  readonly amount: bigint;
+  readonly outputCount: number;
+};
+//#endregion
+//#region src/transfer/model.d.ts
+type SparkTransferLeaf = {
+  readonly leaf: SparkLeaf;
+  /** ECIES(receiver identity) ciphertext sealing the leaf key the sender generated. */
+  readonly secretCipher: Uint8Array;
+  /** Sender's per-leaf authorization: legacy bare signature or scheme-tagged `common.Signature`. */
+  readonly sig: {
+    readonly case: "signature";
+    readonly value: Uint8Array;
+  } | {
+    readonly case: "typedSignature";
+    readonly value: Signature;
+  } | undefined;
+  /** Receiver-edge id that owns this leaf on multi-receiver transfers ("" when unset). */
+  readonly transferReceiverId: string;
+  /** Receiver-side refund txs captured at send time; they are the leaf's current refund state. */
+  readonly intermediateRefundTx: Uint8Array;
+  readonly intermediateDirectRefundTx: Uint8Array;
+  readonly intermediateDirectFromCpfpRefundTx: Uint8Array;
+};
+type SparkTransferReceiver = {
+  readonly id: string;
+  readonly identityPublicKey: Uint8Array;
+  /** Sats this receiver edge carries (0 on single-receiver transfers that leave it unset). */
+  readonly amountSats: number;
+  readonly status: string;
+};
+type SparkTransfer = {
+  readonly id: string;
+  readonly senderIdentityPublicKey: Uint8Array;
+  readonly receiverIdentityPublicKey: Uint8Array;
+  readonly receivers: ReadonlyArray<SparkTransferReceiver>;
+  readonly status: string;
+  readonly type: string;
+  readonly network: SparkNetwork;
+  readonly totalValueSats: number;
+  readonly expiryTimeMs?: number;
+  readonly createdTimeMs?: number;
+  readonly updatedTimeMs?: number;
+  readonly sparkInvoice?: string;
+  readonly leaves: ReadonlyArray<SparkTransferLeaf>;
+};
+//#endregion
+//#region src/core/bitcoin/cpfp.d.ts
+type FundingInput = {
+  /** Display-order hex txid of the confirmed funding output. */
+  readonly txid: string;
+  readonly vout: number;
+  /** Witness program scriptPubKey (P2WPKH, P2TR, …). */
+  readonly script: Uint8Array;
+  readonly amountSats: number;
+  /** Caller's upper bound for this input once signed (68 vB P2WPKH, 58 vB P2TR). */
+  readonly signedInputVbytes: number;
+};
+/**
+ * Builds the unsigned fee-paying child for a zero-fee v3 parent: inputs are the caller's confirmed
+ * funding UTXOs (kept in the given order — a TRUC child may have only one unconfirmed ancestor, so
+ * funding must be confirmed) followed by the parent's P2A anchor carrying only its `witness_utxo`.
+ * Signing software finalizes the anyone-can-spend anchor with an empty witness (Bitcoin Core's
+ * `walletprocesspsbt`/`finalizepsbt` does), so only the funding inputs need signatures. Returns the
+ * PSBT, the package fee (covering parent + child at `feeRateSatPerVbyte`), and the estimated child
+ * vsize.
+ */
+declare function buildCpfpChild(options: {
+  readonly parent: Uint8Array;
+  readonly funding: ReadonlyArray<FundingInput>;
+  readonly changeScript: Uint8Array;
+  /** Fee rate in sats per virtual byte; no upper cap is enforced — the caller picks the value. */
+  readonly feeRateSatPerVbyte: number;
+}): {
+  readonly psbt: Uint8Array;
+  readonly feeSats: number;
+  readonly vsize: number;
+};
+//#endregion
+//#region src/client/deposits.d.ts
+/** `claim_static_deposit` plus the leaves its inbound transfer credited. */
+type StaticDepositClaimResult = StaticDepositClaim & {
+  readonly leaves: ReadonlyArray<SparkLeaf>;
+};
+//#endregion
+//#region src/client/optimize.d.ts
+type OptimizeLeavesOptions = {
+  /**
+   * 0 consolidates dust into the fewest leaves (cheapest unilateral exit); 1–5 keeps every
+   * power-of-two denomination that many times so sends can pay from exact leaves without a swap.
+   */
+  readonly multiplicity?: number;
+  /** Soft bound on swap inputs per round — well under the SO's 1000-leaf transfer limit. */
+  readonly maxLeavesPerSwap?: number;
+  /** Checked between swaps; an in-flight swap completes first. */
+  readonly signal?: AbortSignal;
+};
+type OptimizeLeavesResult = {
+  /** Swaps actually executed. */
+  readonly swaps: number;
+  readonly leavesBefore: number;
+  readonly leavesAfter: number;
+};
+//#endregion
+//#region src/client/index.d.ts
+/**
+ * `transfers.claimPending` result: the leaves claimed this round plus one entry per transfer whose
+ * claim failed. Transfers in non-claimable statuses are skipped, not failures.
+ */
+type ClaimPendingResult = {
+  readonly leaves: ReadonlyArray<SparkLeaf>;
+  readonly failures: ReadonlyArray<{
+    readonly transferId: string;
+    readonly error: unknown;
+  }>;
+};
+type SparkClient = {
+  /** The 33-byte compressed secp256k1 identity public key. */
+  readonly identityPublicKey: () => Promise<Uint8Array>;
+  /** Sum of the owner's `AVAILABLE` leaf values, in sats. */
+  readonly balance: () => Promise<number>;
+  /** The owner's `AVAILABLE` leaves from the coordinator's `query_nodes`. */
+  readonly leaves: () => Promise<ReadonlyArray<SparkLeaf>>;
+  /**
+   * Reshapes leaf denominations through zero-fee SSP swaps (upstream `optimizeLeaves`): with
+   * `multiplicity` 1–5 (default 1) each power of two is kept up to that many times so sends can pay
+   * from exact leaves without a swap; `multiplicity` 0 consolidates into the fewest leaves
+   * (cheapest unilateral exit). Swaps run one at a time under the leaf lock — a concurrent spend
+   * sees a consistent leaf set between rounds. The wallet decides when to call this (e.g. after
+   * claims); nothing schedules it. Returns the executed swap count and leaf counts before/after.
+   *
+   * Swap fee note: the SSP response carries no fee before the inbound counter transfer is claimed,
+   * and the primary transfer is already committed by then — claiming anyway is the only safe move,
+   * so a non-zero SSP swap fee is detected only after the claim. Funds are never stranded or lost:
+   * the thrown error states the leaves are already ours.
+   */
+  readonly optimizeLeaves: (optimizeOptions?: OptimizeLeavesOptions) => Promise<OptimizeLeavesResult>;
+  readonly transfers: {
+    /** Transfers awaiting this identity as receiver. */
+    readonly pending: () => Promise<ReadonlyArray<SparkTransfer>>;
+    /** All transfers where the identity is sender or receiver. */
+    readonly list: (options?: {
+      readonly limit?: number;
+      readonly offset?: number;
+    }) => Promise<ReadonlyArray<SparkTransfer>>;
+    /**
+     * Sends exactly `amountSats` to `receiver` (a `spark1…`/`sparkrt1…` address string or a 33-byte
+     * identity public key) via `start_transfer_v2` — selecting exact leaves, or swapping with the
+     * SSP first when no exact combination exists. Pass the same `transferId` to retry a call whose
+     * response was lost.
+     *
+     * Once the transfer commits (sender key tweaked) it stays claimable indefinitely: the sender
+     * cannot cancel it and its expiry does not return it — the pre-claim refund already pays the
+     * receiver's identity key.
+     *
+     * Leaf selection through the commit runs under the wallet's leaf lock, across leaf renewal and
+     * the signing-operator calls — the lock's hold time grows with the number of stale leaves
+     * renewed and each remote round trip (bounded by the RPC timeouts).
+     */
+    readonly send: (sendOptions: {
+      readonly receiver: string | Uint8Array;
+      readonly amountSats: number;
+      readonly transferId?: string;
+    }) => Promise<SparkTransfer>;
+    /**
+     * Sends to several receivers in one `start_transfer_v3` — one exact leaf group per entry, or a
+     * single SSP swap minting every amount. `receiver` accepts the same shapes as `send` (invoice
+     * addresses are rejected); duplicate receivers are rejected. `transferId` has the same retry
+     * semantics as `send`. Committed transfers share `send`'s claimability: no sender cancel, no
+     * expiry return.
+     */
+    readonly sendMany: (sendOptions: {
+      readonly receivers: ReadonlyArray<{
+        readonly receiver: string | Uint8Array;
+        readonly amountSats: number;
+      }>;
+      readonly transferId?: string;
+    }) => Promise<SparkTransfer>;
+    /** Verifies and claims a pending transfer addressed to this identity; returns the new leaves. */
+    readonly claim: (transfer: SparkTransfer) => Promise<ReadonlyArray<SparkLeaf>>;
+    /**
+     * Claims every pending incoming transfer; returns the new leaves plus one failure entry per
+     * transfer that could not be claimed — a single poisoned transfer does not abort the rest. A
+     * committed transfer stays claimable indefinitely — the sender cannot cancel it and its expiry
+     * does not return it, so a receiver may stay offline across the sender's expiry and claim
+     * later.
+     */
+    readonly claimPending: () => Promise<ClaimPendingResult>;
+  };
+  readonly tokens: {
+    /** Token outputs owned by this identity, optionally narrowed to one bech32m identifier. */
+    readonly outputs: (options?: {
+      readonly tokenIdentifier?: string;
+    }) => Promise<ReadonlyArray<SparkTokenOutput>>;
+    /** Per-identifier aggregate balances. */
+    readonly balances: () => Promise<ReadonlyArray<SparkTokenBalance>>;
+    /**
+     * Sends exactly `amount` of the bech32m token to `receiver` (a spark address string or a
+     * 33-byte identity public key) via `broadcast_transaction`; returns the hex final transaction
+     * hash. Change returns to the sender.
+     *
+     * A lost broadcast response is recovered automatically: the identical partial re-broadcasts
+     * once (the SO dedups by partial hash), then the committed transaction is probed by the spent
+     * input ids. If that cannot resolve the outcome the call throws `SparkTokenBroadcastError`
+     * carrying the spent `inputOutputIds` — retry with `inputOutputIds: error.inputOutputIds` and
+     * the same receiver and amount; that retry either returns the committed transaction's hash or
+     * broadcasts exactly those inputs once. Retrying without them would select different outputs
+     * and pay twice.
+     */
+    readonly transfer: (transferOptions: {
+      readonly tokenIdentifier: string;
+      readonly amount: bigint;
+      readonly receiver: string | Uint8Array;
+      /** Output ids from a `SparkTokenBroadcastError`, to retry the same transaction safely. */
+      readonly inputOutputIds?: ReadonlyArray<string>;
+    }) => Promise<string>;
+    /**
+     * Merges this identity's available outputs for `tokenIdentifier` into a single self-owned
+     * output (upstream `optimizeTokenOutputs`): smallest-first, at most 500 inputs per transaction,
+     * on demand — no change output is created. Returns `undefined` when fewer than two available
+     * outputs exist; call again to keep merging when more than 500 were owned.
+     *
+     * Shares `transfer`'s lost-response recovery: on `SparkTokenBroadcastError`, retry with
+     * `inputOutputIds: error.inputOutputIds` — at least two, as the failed call's inputs were.
+     */
+    readonly consolidate: (options: {
+      readonly tokenIdentifier: string;
+      /** Output ids from a `SparkTokenBroadcastError`, to retry the same transaction safely. */
+      readonly inputOutputIds?: ReadonlyArray<string>;
+    }) => Promise<{
+      readonly transactionHash: string;
+    } | undefined>;
+  };
+  readonly invoices: {
+    /**
+     * Creates a signed sats invoice address for this identity. `amountSats` omitted means the payer
+     * picks the amount.
+     */
+    readonly createSats: (options?: {
+      readonly amountSats?: number;
+      readonly memo?: string;
+      readonly senderPublicKey?: Uint8Array;
+      readonly expiresAtMs?: number;
+    }) => Promise<string>;
+    /**
+     * Creates a signed token invoice address for this identity. `tokenIdentifier` is the bech32m
+     * identifier; omit it (with `amount`) for any-token invoices.
+     */
+    readonly createTokens: (options?: {
+      readonly tokenIdentifier?: string;
+      readonly amount?: bigint;
+      readonly memo?: string;
+      readonly senderPublicKey?: Uint8Array;
+      readonly expiresAtMs?: number;
+    }) => Promise<string>;
+    /**
+     * Pays a Spark invoice address. `amount` is required for open invoices and must equal a fixed
+     * invoice amount when set. Unsigned invoices are accepted too: invoice fields (amount, sender
+     * restriction, expiry) are then only hints, and the receiver is always the identity key inside
+     * the address. Resolves to the `SparkTransfer` for sats invoices or the hex final token
+     * transaction hash for token invoices.
+     *
+     * `transferId` (sats invoices) and `inputOutputIds` (token invoices) are the retry handles
+     * after a lost response: a retry under the same handle recovers the committed result instead of
+     * paying twice, and a committed result under different terms fails rather than riding along.
+     */
+    readonly pay: (invoice: string, options?: {
+      readonly amount?: number | bigint;
+      /** Sats invoices: idempotent transfer id, like `transfers.send`'s. */
+      readonly transferId?: string;
+      /** Token invoices: ids of the spent outputs, like `tokens.transfer`'s. */
+      readonly inputOutputIds?: ReadonlyArray<string>;
+    }) => Promise<SparkTransfer | string>;
+    /** Coordinator `query_spark_invoices` statuses for the given invoice address strings. */
+    readonly status: (invoices: ReadonlyArray<string>) => Promise<ReadonlyArray<SparkInvoiceStatus>>;
+  };
+  /**
+   * This wallet's coordinator settings. `setPrivate(true)` restricts node and transfer reads to
+   * this identity's own session on every operator; `get` reports `privateEnabled: false` for a
+   * wallet that never stored a setting.
+   */
+  readonly walletSettings: {
+    readonly get: () => Promise<SparkWalletSettings>;
+    readonly setPrivate: (enabled: boolean) => Promise<SparkWalletSettings>;
+  };
+  /** SSP leaves-swap fee quote in sats. */
+  readonly swapFeeEstimate: (amountSats: number) => Promise<number>;
+  readonly lightning: {
+    /**
+     * Asks the SSP for a BOLT-11 invoice paying this identity. `amountSats` of 0 requests an
+     * amountless invoice; `includeSparkAddress` embeds a Spark fallback address payers can settle
+     * directly. `receiver` (a spark address string or 33-byte identity key) creates the invoice for
+     * another identity instead — the SSP routes its payment there and the payee claims it. The
+     * returned invoice is verified field-by-field before it is handed out.
+     */
+    readonly createInvoice: (options: {
+      readonly amountSats: number;
+      readonly memo?: string;
+      readonly descriptionHash?: Uint8Array;
+      readonly expirySecs?: number;
+      readonly includeSparkAddress?: boolean;
+      readonly receiver?: string | Uint8Array;
+    }) => Promise<LightningInvoice>;
+    /**
+     * Pays a BOLT-11 invoice via a preimage swap with the SSP. `amountSats` is required for
+     * zero-amount invoices and rejected otherwise; `transferId` makes a retry resume the same
+     * transfer instead of paying twice.
+     *
+     * On a `transferId` retry the reported `feeSats` is derived as the committed transfer total
+     * minus the amount passed in this call — pass the same invoice and `amountSats` as the first
+     * attempt. The SSP send request's echoed invoice is still verified before continuing.
+     *
+     * The leaf lock is held across the SSP call — see `transfers.send` for what that covers.
+     */
+    readonly pay: (options: {
+      readonly invoice: string;
+      readonly maxFeeSats: number;
+      readonly amountSats?: number;
+      readonly transferId?: string;
+    }) => Promise<LightningPayment>;
+    /**
+     * `user_request` status of a send; `preimage` appears once the SSP settled it. Pass the
+     * `LightningPayment` from `pay` — the request's invoice and preimage are verified against its
+     * payment hash, not the hash the SSP reports. `outcome` maps the SSP status to
+     * "pending"/"succeeded"/"failed"/"returned": "failed" means the payment will not settle but the
+     * funds are not back — keep polling until "returned" (≈5 min on hosted; the leaves then
+     * reappear in `leaves()` on the next sync).
+     */
+    readonly sendStatus: (request: LightningSendStatusRequest) => Promise<LightningSendStatus>;
+    /**
+     * `user_request` status of a receive, with the inbound transfer id once present and the settled
+     * `preimage` once the SSP reports it — the request's invoice and preimage are both checked
+     * against the payment hash of the invoice we created (a mismatch throws).
+     */
+    readonly receiveStatus: (request: LightningReceiveStatusRequest) => Promise<LightningReceiveStatus>;
+    /**
+     * Signs the sender timeout spend of a Lightning HTLC output — output `vout` of `htlcTx`, a
+     * committed refund transaction of an in-flight `pay` whose SSP never settled. Once `htlcTx` is
+     * `LIGHTNING_HTLC_SEQUENCE` (2160) blocks deep the output can be spent through the
+     * sequence-lock leaf back to `destinationAddress`. Returns the signed transaction UNBROADCAST —
+     * broadcast it yourself after the CSV wait; bitcoind rejects it earlier as non-BIP68-final.
+     * `paymentHash` and the SSP identity bind the output, which is verified before signing. Stored
+     * exit chains do not cover in-flight Lightning sends, so keep `htlcTx` until the sweep
+     * confirms.
+     */
+    readonly sweepHtlcTimeout: (options: {
+      readonly htlcTx: Uint8Array;
+      readonly vout: number;
+      readonly paymentHash: Uint8Array;
+      readonly destinationAddress: string;
+      readonly feeRateSatPerVbyte: number;
+    }) => Promise<Uint8Array>;
+  };
+  readonly deposits: {
+    /** Fresh single-use deposit address with a verified proof-of-possession. */
+    readonly newAddress: () => Promise<string>;
+    /** Deposit addresses the SO still considers unused. */
+    readonly unused: () => Promise<ReadonlyArray<UnusedDepositAddress>>;
+    /**
+     * Claims an on-chain deposit paying to one of the unused addresses. When the transaction has
+     * multiple matching outputs `vout` selects which one.
+     */
+    readonly claim: (options: {
+      readonly transaction: Uint8Array;
+      readonly vout?: number;
+    }) => Promise<SparkLeaf>;
+    /**
+     * Claims several confirmed UTXOs paying the SAME single-use address into one leaf — the only
+     * way to claim more than one UTXO, since a single-use address is consumed by a claim. At most
+     * 11 outputs; `vout` is resolved by unique match when omitted.
+     */
+    readonly claimMany: (options: {
+      readonly outputs: ReadonlyArray<{
+        readonly transaction: Uint8Array;
+        readonly vout?: number;
+      }>;
+    }) => Promise<SparkLeaf>;
+    /** The identity's reusable static deposit address — the same address on every call. */
+    readonly staticAddress: () => Promise<string>;
+    /** Confirmed, unclaimed UTXOs paying the static deposit address. */
+    readonly staticUtxos: () => Promise<ReadonlyArray<StaticDepositUtxo>>;
+    /**
+     * Claims a static-deposit UTXO through the SSP: quotes the credit, rejects fees over
+     * `maxFeeSats`, then claims the SSP's inbound transfer. `rawTx` supplies the deposit
+     * transaction when the SO's utxo listing does not return it.
+     */
+    readonly claimStatic: (options: {
+      readonly txid: string;
+      readonly vout: number;
+      readonly maxFeeSats: number;
+      readonly rawTx?: Uint8Array;
+    }) => Promise<StaticDepositClaimResult>;
+    /**
+     * Signs a version-3 refund spending a static-deposit UTXO to `destinationAddress` at
+     * `feeRateSatPerVbyte` (fee floored at 194 sats; output must clear dust). The signed
+     * transaction is returned unbroadcast.
+     */
+    readonly refundStatic: (options: {
+      readonly txid: string;
+      readonly vout: number;
+      readonly destinationAddress: string;
+      readonly feeRateSatPerVbyte: number;
+      readonly rawTx?: Uint8Array;
+    }) => Promise<StaticDepositRefund>;
+  };
+  readonly withdrawals: {
+    /**
+     * Pre-signed exit transactions for the given leaves, root first (see ExitTransaction), from a
+     * live `query_nodes` call the coordinator and every other operator must answer identically —
+     * use `offlineExitTransactions` when the operators are unreachable or withholding data. Each
+     * transaction carries a hard deadline: once its parent confirms and its relative timelock
+     * passes, it must confirm within DIRECT_TIMELOCK_OFFSET blocks; otherwise the operators'
+     * watchtower may publish a self-fee variant instead. For intermediate nodes this strands
+     * descendants as WATCHTOWER_EXITED (recover with recoverWatchtowerExit while the SO is online);
+     * for refunds the watchtower publishes direct_from_cpfp_refund_tx, which pays the leaf key
+     * (sweep with sweepRefund). Keep each exit package confirming promptly.
+     */
+    readonly unilateralExit: (leafIds: ReadonlyArray<string>) => Promise<ReadonlyArray<ExitTransaction>>;
+    /**
+     * The same broadcast list `unilateralExit` returns, built purely from the exit chains the
+     * SparkStore persists — this method performs no network calls. Stored chains are refreshed by
+     * every leaves sync, so this is the recovery path when the operators are unreachable or
+     * withholding data. Throws a SparkInputError naming any leaf that has no stored chain. The same
+     * broadcast deadlines apply: each transaction must confirm within DIRECT_TIMELOCK_OFFSET blocks
+     * once its parent's relative timelock matures.
+     */
+    readonly offlineExitTransactions: (leafIds: ReadonlyArray<string>) => Promise<ReadonlyArray<ExitTransaction>>;
+    /**
+     * The SSP's per-speed cooperative-exit fees for `address`. `amountSats` selects exactly that
+     * much to exit (swapping if needed); omitting it quotes for the whole balance.
+     */
+    readonly quoteCooperativeExit: (options: {
+      readonly address: string;
+      readonly amountSats?: number;
+    }) => Promise<CooperativeExitQuote>;
+    /**
+     * Cooperatively exits leaves to `address`, deducting `speed`'s quoted fee from the payout.
+     * `amountSats` exits exactly that much; omitting it exits the whole balance. Pass the same
+     * `transferId` to retry a call whose response was lost — a committed exit resumes with the
+     * committed leaves. Note the SSP request expires ~2 minutes after creation unless the transfer
+     * commits: an uncommitted id is burned, retry with a fresh `transferId`.
+     *
+     * The leaf lock is held across the fee quote and the SSP request — see `transfers.send` for
+     * what that covers.
+     */
+    readonly cooperativeExit: (options: {
+      readonly address: string;
+      readonly speed: CooperativeExitSpeed;
+      readonly maxFeeSats: number;
+      readonly amountSats?: number;
+      readonly transferId?: string;
+    }) => Promise<CooperativeExitResult>;
+    /** The SSP's status for a cooperative-exit request id. */
+    readonly cooperativeExitStatus: (requestId: string) => Promise<CooperativeExitStatus>;
+    /**
+     * The leaves a watchtower exit cut off from their exit path, each with the confirmed ancestor
+     * output it can still spend when one resolves. Entries stay listed after a recovery — the SE
+     * never sees the broadcast, so check the chain for whether a recovery landed.
+     */
+    readonly watchtowerExitedLeaves: () => Promise<ReadonlyArray<WatchtowerExitedLeaf>>;
+    /**
+     * Co-signs a transaction spending the on-chain output a watchtower exit stranded under
+     * `leafId`, returned signed but NOT broadcast. Re-call with a higher fee to re-sign the same
+     * outpoint — at most one recovery can confirm.
+     */
+    readonly recoverWatchtowerExit: (options: {
+      readonly leafId: string;
+      readonly destinationScript: Uint8Array;
+      readonly feeRateSatPerVbyte: number;
+      readonly recoveryTxid?: string;
+      readonly outputIndex?: number;
+    }) => Promise<{
+      readonly transaction: Uint8Array;
+      readonly txid: string;
+    }>;
+    /**
+     * Signed key-path sweep of a confirmed refund output (any of the leaf's refund variants, output 0)
+     * to `destinationScript`. `refundTx` may be the stored witness-less `directFromCpfpRefundTx`
+     * template — only its txid and output 0 are read.
+     */
+    readonly sweepRefund: (options: {
+      readonly leafId: string;
+      readonly refundTx: Uint8Array;
+      readonly destinationScript: Uint8Array;
+      readonly feeRateSatPerVbyte: number;
+    }) => Promise<Uint8Array>;
+  };
+  /** Coordinator `subscribe_to_events`; reconnects until `signal` aborts or `close()` runs. */
+  readonly events: (signal?: AbortSignal) => AsyncIterable<SparkEvent>;
+  /** Aborts all outstanding event streams (including caller-signaled ones). */
+  readonly close: () => void;
+};
+/** One entry of `query_spark_invoices`: the invoice string, its status name, and the payment. */
+type SparkInvoiceStatus = {
+  readonly invoice: string;
+  /** `InvoiceStatus` enum name, e.g. `"PENDING"`, `"FINALIZED"`. */
+  readonly status: string;
+  /** Hex transfer id when a sats transfer paid the invoice. */
+  readonly satsTransferId?: string | undefined;
+  /** Hex `hashFinalTokenTransaction` when a token transfer paid the invoice. */
+  readonly tokenTransactionHash?: string | undefined;
+};
+type SparkClientOptions = {
+  readonly network: SparkNetwork;
+  readonly signer: SparkSigner;
+  /**
+   * On React Native inject a streaming fetch (`expo/fetch`, the global from Expo SDK 56): RN's
+   * XHR-based fetch (e.g. with `EXPO_PUBLIC_USE_RN_FETCH=1`) has no streaming body, so `events()`
+   * cannot work with it.
+   */
+  readonly fetch: typeof globalThis.fetch;
+  /**
+   * Exit-chain persistence (e.g. `createMemorySparkStore()`). Required: stored chains are the
+   * wallet's unilateral-exit data, so durability is a caller decision — a silent in-memory default
+   * would lose them on restart.
+   */
+  readonly store: SparkStore;
+  readonly random?: (length: number) => Uint8Array;
+  readonly now?: () => number;
+  readonly sleep?: (ms: number) => Promise<void>;
+  readonly operators?: ReadonlyArray<SparkOperatorConfig>;
+  readonly ssp?: SparkNetworkConfig["ssp"];
+};
+/**
+ * Builds a Spark client over one operator set. All spend paths are concurrency-safe within one
+ * client instance — sends, swaps, lightning payments, exits and claims serialize leaf selection and
+ * exit-chain bookkeeping on an internal lock, and token transfers likewise — but several client
+ * instances or devices on one identity are not coordinated: the SO rejects the conflicting spend.
+ */
+declare function createSparkClient(options: SparkClientOptions): SparkClient;
+//#endregion
+export { CooperativeExitStatus as A, exitTransactions as C, CooperativeExitQuote as D, createMemorySparkStore as E, UnusedDepositAddress as F, SparkLeaf as I, SparkEvent as L, StaticDepositClaim as M, StaticDepositRefund as N, CooperativeExitResult as O, StaticDepositUtxo as P, ExitTransaction as S, SparkStore as T, LightningSendStatus as _, createSparkClient as a, LightningInvoice as b, buildCpfpChild as c, SparkTokenBalance as d, SparkTokenOutput as f, LightningSendOutcome as g, LightningReceiveStatus as h, SparkInvoiceStatus as i, MIN_STATIC_REFUND_FEE_SATS as j, CooperativeExitSpeed as k, SparkTransfer as l, SparkWalletSettings as m, SparkClient as n, StaticDepositClaimResult as o, SparkTokenOutputStatus as p, SparkClientOptions as r, FundingInput as s, ClaimPendingResult as t, SparkTransferLeaf as u, LightningSendStatusRequest as v, SparkExitChain as w, WatchtowerExitedLeaf as x, LightningPayment as y };