@qntx/spark 0.2.1 → 0.4.0

package/README.md

@@ -66,7 +66,14 @@ and amount; that retry either returns the committed transaction's hash or broadc
 those inputs once. Retrying without it would select different outputs and pay twice.
 
 Offline receive: once a transfer commits, the sender cannot cancel it and its expiry does not
-return it — `transfers.claim`/`claimPending` can pick it up at any later time.
+return it — `transfers.claim(transferId)`/`claimPending` can pick it up at any later time.
+
+Transaction history: `transfers.history({ limit?, offset? })` pages transfers newest-first
+(`TRANSFER`, `PREIMAGE_SWAP`, `COOPERATIVE_EXIT`, `UTXO_SWAP`), folding each entry with its SSP
+`user_request` when the counterparty is the SSP — lightning invoices, payment hashes and
+preimages, coop-exit fees and payout txids, static-deposit credits. Entries surface as
+`SparkPayment` (`send`/`receive`, `pending`/`completed`/`failed`, `spark`/`lightning`/`deposit`/
+`withdraw`); `nextOffset` is `undefined` at the end.
 
 Unilateral exit: each pre-signed transaction carries a hard deadline — once its parent confirms
 and its relative timelock passes, it must confirm within 50 blocks; otherwise the operators'

package/dist/{index-DISbAuPB.d.mts → index-Bq6pNclo.d.mts}

@@ -332,6 +332,43 @@ type SparkTransfer = {
   readonly leaves: ReadonlyArray<SparkTransferLeaf>;
 };
 //#endregion
+//#region src/transfer/payment.d.ts
+/**
+ * One entry of `client.transfers.history`: a transfer folded with its SSP `user_request` into the
+ * wallet-facing payment shape. Mapping follows the Breez adaptor semantics; every field a consumer
+ * displays comes from authenticated SO data or the SSP record — never from host input.
+ */
+type SparkPayment = {
+  readonly id: string;
+  readonly direction: "send" | "receive";
+  readonly status: "pending" | "completed" | "failed";
+  readonly method: "spark" | "lightning" | "deposit" | "withdraw";
+  /** Sats excluding fees — the total minus the fee for outbound sends and exits. */
+  readonly amountSats: number;
+  readonly feeSats: number;
+  /** Milliseconds since the epoch; absent when the SO reports none. */
+  readonly createdAt: number | undefined;
+  readonly details: {
+    readonly kind: "spark";
+    readonly invoice?: string;
+  } | {
+    readonly kind: "lightning";
+    readonly invoice: string;
+    /** Payment hash, hex. */
+    readonly paymentHash: string;
+    /** Payment preimage, hex. */
+    readonly preimage?: string;
+    readonly description?: string;
+  } | {
+    readonly kind: "withdraw";
+    readonly txid?: string;
+  } | {
+    readonly kind: "deposit";
+    readonly txid: string;
+    readonly vout: number;
+  } | undefined;
+};
+//#endregion
 //#region src/core/bitcoin/cpfp.d.ts
 type FundingInput = {
   /** Display-order hex txid of the confirmed funding output. */
@@ -430,6 +467,19 @@ type SparkClient = {
       readonly limit?: number;
       readonly offset?: number;
     }) => Promise<ReadonlyArray<SparkTransfer>>;
+    /**
+     * Transfer history as wallet-facing payments: TRANSFER, PREIMAGE_SWAP, COOPERATIVE_EXIT and
+     * UTXO_SWAP records (newest first) folded with their SSP user requests when the counterparty is
+     * the SSP — one batched SSP call per page. `limit` is 1–100 (default 20); `nextOffset` is the
+     * offset of the next page, `undefined` at the end.
+     */
+    readonly history: (options?: {
+      readonly limit?: number;
+      readonly offset?: number;
+    }) => Promise<{
+      readonly payments: ReadonlyArray<SparkPayment>;
+      readonly nextOffset: number | undefined;
+    }>;
     /**
      * 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
@@ -463,8 +513,15 @@ type SparkClient = {
       }>;
       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 the transfer `transferId` once it becomes claimable and returns the new leaves —
+     * re-querying the coordinator between retries the way upstream `TransferService.claimTransfer`
+     * does (five attempts, 1/2/4/8 s). `[]` means this identity's receiver leg already completed. A
+     * terminal status (`EXPIRED`, `RETURNED`, …) throws immediately; `signal` aborts the waits.
+     */
+    readonly claim: (transferId: string, options?: {
+      readonly signal?: AbortSignal;
+    }) => 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
@@ -816,4 +873,4 @@ type SparkClientOptions = {
  */
 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 };
+export { CooperativeExitSpeed as A, ExitTransaction as C, createMemorySparkStore as D, SparkStore as E, StaticDepositUtxo as F, UnusedDepositAddress as I, SparkLeaf as L, MIN_STATIC_REFUND_FEE_SATS as M, StaticDepositClaim as N, CooperativeExitQuote as O, StaticDepositRefund as P, SparkEvent as R, WatchtowerExitedLeaf as S, SparkExitChain as T, LightningSendOutcome as _, createSparkClient as a, LightningPayment as b, buildCpfpChild as c, SparkTransferLeaf as d, SparkTokenBalance as f, LightningReceiveStatus as g, SparkWalletSettings as h, SparkInvoiceStatus as i, CooperativeExitStatus as j, CooperativeExitResult as k, SparkPayment as l, SparkTokenOutputStatus as m, SparkClient as n, StaticDepositClaimResult as o, SparkTokenOutput as p, SparkClientOptions as r, FundingInput as s, ClaimPendingResult as t, SparkTransfer as u, LightningSendStatus as v, exitTransactions as w, LightningInvoice as x, LightningSendStatusRequest as y };

package/dist/index.d.mts

@@ -1,11 +1,11 @@
 import { a as SparkTokenBroadcastError, i as SparkRequestError, n as SparkError, r as SparkInputError, t as SparkCryptoError } from "./index-D1fBaHTa.mjs";
 import { a as sparkNetworkConfig, i as SparkOperatorConfig, n as SparkNetwork, r as SparkNetworkConfig } from "./lightning-address-CRULmi9v.mjs";
 import { i as isExpired, n as Bolt11Network, r as decodeBolt11, t as Bolt11Invoice } from "./bolt11-DsNTTS_O.mjs";
-import { A as CooperativeExitStatus, C as exitTransactions, D as CooperativeExitQuote, E as createMemorySparkStore, F as UnusedDepositAddress, I as SparkLeaf, L as SparkEvent, M as StaticDepositClaim, N as StaticDepositRefund, O as CooperativeExitResult, P as StaticDepositUtxo, S as ExitTransaction, T as SparkStore, _ as LightningSendStatus, a as createSparkClient, b as LightningInvoice, c as buildCpfpChild, d as SparkTokenBalance, f as SparkTokenOutput, g as LightningSendOutcome, h as LightningReceiveStatus, i as SparkInvoiceStatus, j as MIN_STATIC_REFUND_FEE_SATS, k as CooperativeExitSpeed, l as SparkTransfer, m as SparkWalletSettings, n as SparkClient, o as StaticDepositClaimResult, p as SparkTokenOutputStatus, r as SparkClientOptions, s as FundingInput, t as ClaimPendingResult, u as SparkTransferLeaf, v as LightningSendStatusRequest, w as SparkExitChain, x as WatchtowerExitedLeaf, y as LightningPayment } from "./index-DISbAuPB.mjs";
+import { A as CooperativeExitSpeed, C as ExitTransaction, D as createMemorySparkStore, E as SparkStore, F as StaticDepositUtxo, I as UnusedDepositAddress, L as SparkLeaf, M as MIN_STATIC_REFUND_FEE_SATS, N as StaticDepositClaim, O as CooperativeExitQuote, P as StaticDepositRefund, R as SparkEvent, S as WatchtowerExitedLeaf, T as SparkExitChain, _ as LightningSendOutcome, a as createSparkClient, b as LightningPayment, c as buildCpfpChild, d as SparkTransferLeaf, f as SparkTokenBalance, g as LightningReceiveStatus, h as SparkWalletSettings, i as SparkInvoiceStatus, j as CooperativeExitStatus, k as CooperativeExitResult, l as SparkPayment, m as SparkTokenOutputStatus, n as SparkClient, o as StaticDepositClaimResult, p as SparkTokenOutput, r as SparkClientOptions, s as FundingInput, t as ClaimPendingResult, u as SparkTransfer, v as LightningSendStatus, w as exitTransactions, x as LightningInvoice, y as LightningSendStatusRequest } from "./index-Bq6pNclo.mjs";
 import { n as EPHEMERAL_ANCHOR_SCRIPT, t as addressToScript, v as SparkSigner } from "./transactions-DjTZU8ev.mjs";
 //#region src/core/invoice.d.ts
 /** Payment carried by a Spark invoice: satoshis or BTKN tokens. */
-type SparkPayment = {
+type SparkInvoicePayment = {
   readonly type: "sats";
   readonly amount?: number | undefined;
 } | {
@@ -20,7 +20,7 @@ type SparkInvoiceFields = {
   readonly version: number;
   /** UUID identifying the invoice (canonical lowercase form). */
   readonly id: string;
-  readonly payment?: SparkPayment | undefined;
+  readonly payment?: SparkInvoicePayment | undefined;
   /** At most 120 UTF-8 bytes. */
   readonly memo?: string | undefined;
   /** 33-byte compressed secp256k1 public key. */
@@ -120,4 +120,4 @@ export declare function parseSparkInvoice(text: string, options: {
   readonly now: number;
 }): ParsedSparkInvoice;
 //#endregion
-export { type Bolt11Invoice, type Bolt11Network, type ClaimPendingResult, type CooperativeExitQuote, type CooperativeExitResult, type CooperativeExitSpeed, type CooperativeExitStatus, EPHEMERAL_ANCHOR_SCRIPT, type ExitTransaction, type FundingInput, type LightningInvoice, type LightningPayment, type LightningReceiveStatus, type LightningSendOutcome, type LightningSendStatus, type LightningSendStatusRequest, MIN_STATIC_REFUND_FEE_SATS, type ParsedSparkInvoice, type SparkAddress, type SparkClient, type SparkClientOptions, SparkCryptoError, SparkError, type SparkEvent, type SparkExitChain, SparkInputError, type SparkInvoiceFields, type SparkInvoiceStatus, type SparkLeaf, type SparkNetwork, type SparkNetworkConfig, type SparkOperatorConfig, type SparkPayment, SparkRequestError, type SparkStore, type SparkTokenBalance, SparkTokenBroadcastError, type SparkTokenIdentifierData, type SparkTokenOutput, type SparkTokenOutputStatus, type SparkTransfer, type SparkTransferLeaf, type SparkWalletSettings, type StaticDepositClaim, type StaticDepositClaimResult, type StaticDepositRefund, type StaticDepositUtxo, type UnusedDepositAddress, type WatchtowerExitedLeaf, addressToScript, buildCpfpChild, createMemorySparkStore, createSparkClient, decodeBolt11, exitTransactions, isExpired, sparkNetworkConfig };
+export { type Bolt11Invoice, type Bolt11Network, type ClaimPendingResult, type CooperativeExitQuote, type CooperativeExitResult, type CooperativeExitSpeed, type CooperativeExitStatus, EPHEMERAL_ANCHOR_SCRIPT, type ExitTransaction, type FundingInput, type LightningInvoice, type LightningPayment, type LightningReceiveStatus, type LightningSendOutcome, type LightningSendStatus, type LightningSendStatusRequest, MIN_STATIC_REFUND_FEE_SATS, type ParsedSparkInvoice, type SparkAddress, type SparkClient, type SparkClientOptions, SparkCryptoError, SparkError, type SparkEvent, type SparkExitChain, SparkInputError, type SparkInvoiceFields, type SparkInvoicePayment, type SparkInvoiceStatus, type SparkLeaf, type SparkNetwork, type SparkNetworkConfig, type SparkOperatorConfig, type SparkPayment, SparkRequestError, type SparkStore, type SparkTokenBalance, SparkTokenBroadcastError, type SparkTokenIdentifierData, type SparkTokenOutput, type SparkTokenOutputStatus, type SparkTransfer, type SparkTransferLeaf, type SparkWalletSettings, type StaticDepositClaim, type StaticDepositClaimResult, type StaticDepositRefund, type StaticDepositUtxo, type UnusedDepositAddress, type WatchtowerExitedLeaf, addressToScript, buildCpfpChild, createMemorySparkStore, createSparkClient, decodeBolt11, exitTransactions, isExpired, sparkNetworkConfig };

package/dist/index.mjs

@@ -11,7 +11,7 @@ import { base64, bech32m } from "@scure/base";
 import { sha256 } from "@noble/hashes/sha2.js";
 import { Code, ConnectError, createClient } from "@connectrpc/connect";
 import { createGrpcWebTransport } from "@connectrpc/connect-web";
-import { bytesToNumberBE, equalBytes, hexToBytes as hexToBytes$1, numberToBytesBE, numberToVarBytesBE } from "@noble/curves/utils.js";
+import { bytesToHex as bytesToHex$1, bytesToNumberBE, equalBytes, hexToBytes as hexToBytes$1, numberToBytesBE, numberToVarBytesBE } from "@noble/curves/utils.js";
 import { Address, OutScript, Transaction } from "@scure/btc-signer";
 //#region src/core/address.ts
 const BECH32M_LIMIT$1 = 1024;
@@ -1229,6 +1229,94 @@ fragment UserRequestFragment on UserRequest {
         lightning_send_request_payment_preimage: payment_preimage
     }
 }`;
+const TRANSFERS = `
+query Transfers($transfer_spark_ids: [UUID!]!) {
+  transfers(transfer_spark_ids: $transfer_spark_ids) {
+    ...TransferFragment
+    transfer_user_request: user_request {
+      ...UserRequestFragment
+    }
+  }
+}
+
+fragment TransferFragment on Transfer {
+  __typename
+  transfer_spark_id: spark_id
+}
+
+fragment CurrencyAmountFragment on CurrencyAmount {
+  __typename
+  currency_amount_original_value: original_value
+  currency_amount_original_unit: original_unit
+}
+
+fragment TransferSparkIdFragment on Transfer {
+  __typename
+  transfer_spark_id: spark_id
+}
+
+fragment UserRequestFragment on UserRequest {
+  __typename
+  ... on ClaimStaticDeposit {
+    claim_static_deposit_id: id
+    claim_static_deposit_deposit_amount: deposit_amount {
+      ...CurrencyAmountFragment
+    }
+    claim_static_deposit_credit_amount: credit_amount {
+      ...CurrencyAmountFragment
+    }
+    claim_static_deposit_max_fee: max_fee {
+      ...CurrencyAmountFragment
+    }
+    claim_static_deposit_status: status
+    claim_static_deposit_transaction_id: transaction_id
+    claim_static_deposit_output_index: output_index
+    claim_static_deposit_transfer_spark_id: transfer_spark_id
+  }
+  ... on CoopExitRequest {
+    coop_exit_request_id: id
+    coop_exit_request_fee: fee {
+      ...CurrencyAmountFragment
+    }
+    coop_exit_request_l1_broadcast_fee: l1_broadcast_fee {
+      ...CurrencyAmountFragment
+    }
+    coop_exit_request_status: status
+    coop_exit_request_coop_exit_txid: coop_exit_txid
+    coop_exit_request_transfer: transfer {
+      ...TransferSparkIdFragment
+    }
+  }
+  ... on LeavesSwapRequest {
+    leaves_swap_request_id: id
+    leaves_swap_request_status: status
+  }
+  ... on LightningReceiveRequest {
+    lightning_receive_request_id: id
+    lightning_receive_request_invoice: invoice {
+      __typename
+      invoice_encoded_invoice: encoded_invoice
+      invoice_payment_hash: payment_hash
+    }
+    lightning_receive_request_status: status
+    lightning_receive_request_transfer: transfer {
+      ...TransferSparkIdFragment
+    }
+    lightning_receive_request_payment_preimage: payment_preimage
+  }
+  ... on LightningSendRequest {
+    lightning_send_request_id: id
+    lightning_send_request_encoded_invoice: encoded_invoice
+    lightning_send_request_fee: fee {
+      ...CurrencyAmountFragment
+    }
+    lightning_send_request_status: status
+    lightning_send_request_transfer: transfer {
+      ...TransferSparkIdFragment
+    }
+    lightning_send_request_payment_preimage: payment_preimage
+  }
+}`;
 //#endregion
 //#region src/ssp/parse.ts
 /** A malformed SSP response is a server fault, not caller input. */
@@ -1251,6 +1339,11 @@ function asSats(value, field) {
 	if (n === void 0 || !Number.isSafeInteger(n) || n < 0) throw unexpectedResponse(field, "is not a non-negative integer");
 	return n;
 }
+/** A GraphQL Int field used as an array/output index — a number, not a decimal string. */
+function asIndex(value, field) {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw unexpectedResponse(field, "is not a non-negative integer");
+	return value;
+}
 /** CurrencyAmount in SATOSHI → sats; any other unit is an unexpected response. */
 function currencyAmountSats(value, field) {
 	const amount = asObject(value, field);
@@ -1371,6 +1464,75 @@ function parseCoopExitResult(request, field) {
 		rawConnectorTransaction: asHexBytes(request["coop_exit_request_raw_connector_transaction"], `${field}.coop_exit_request_raw_connector_transaction`)
 	};
 }
+function optionalTxidHex(value, field) {
+	if (value === void 0 || value === null) return;
+	return asTxidHex(value, field);
+}
+/** The `transfers` query's per-item parse: id plus its user_request union member (or none). */
+function parseTransfersResponse(data) {
+	const items = data["transfers"];
+	if (!Array.isArray(items)) throw unexpectedResponse("transfers", "is not an array");
+	return items.map((item, index) => {
+		const field = `transfers[${index}]`;
+		const entry = asObject(item, field);
+		const request = entry["transfer_user_request"];
+		return {
+			transferId: asString(entry["transfer_spark_id"], `${field}.transfer_spark_id`),
+			request: request === void 0 || request === null ? void 0 : parseUserRequest(asObject(request, `${field}.transfer_user_request`), `${field}.transfer_user_request`)
+		};
+	});
+}
+/**
+* Discriminated `user_request` parse. An unknown `__typename` is a variant we do not model, not a
+* malformed response.
+*/
+function parseUserRequest(request, field) {
+	switch (request["__typename"]) {
+		case "LightningSendRequest": {
+			const send = parseLightningSend(request, field);
+			return {
+				kind: "lightning-send",
+				status: send.status,
+				invoice: send.encodedInvoice,
+				feeSats: send.feeSats,
+				...send.paymentPreimage === void 0 ? {} : { preimage: send.paymentPreimage }
+			};
+		}
+		case "LightningReceiveRequest": {
+			const receive = parseLightningReceive(request, field);
+			return {
+				kind: "lightning-receive",
+				status: receive.status,
+				invoice: receive.invoice,
+				...receive.paymentPreimage === void 0 ? {} : { preimage: receive.paymentPreimage }
+			};
+		}
+		case "CoopExitRequest": return parseCoopExitRequest(request, field);
+		case "ClaimStaticDeposit": return parseStaticDepositRequest(request, field);
+		case "LeavesSwapRequest": return { kind: "leaves-swap" };
+		default: return;
+	}
+}
+/** `coop_exit` for history: fee = `fee` + `l1_broadcast_fee`, status and payout txid. */
+function parseCoopExitRequest(request, field) {
+	const txid = optionalTxidHex(request["coop_exit_request_coop_exit_txid"], `${field}.coop_exit_request_coop_exit_txid`);
+	return {
+		kind: "coop-exit",
+		status: asString(request["coop_exit_request_status"], `${field}.coop_exit_request_status`),
+		feeSats: currencyAmountSats(request["coop_exit_request_fee"], `${field}.coop_exit_request_fee`) + currencyAmountSats(request["coop_exit_request_l1_broadcast_fee"], `${field}.coop_exit_request_l1_broadcast_fee`),
+		...txid === void 0 ? {} : { txid }
+	};
+}
+/** `claim_static_deposit` for history: the claim's txid, vout and credited amount. */
+function parseStaticDepositRequest(request, field) {
+	return {
+		kind: "static-deposit",
+		txid: asTxidHex(request["claim_static_deposit_transaction_id"], `${field}.claim_static_deposit_transaction_id`),
+		vout: asIndex(request["claim_static_deposit_output_index"], `${field}.claim_static_deposit_output_index`),
+		depositAmountSats: currencyAmountSats(request["claim_static_deposit_deposit_amount"], `${field}.claim_static_deposit_deposit_amount`),
+		creditAmountSats: currencyAmountSats(request["claim_static_deposit_credit_amount"], `${field}.claim_static_deposit_credit_amount`)
+	};
+}
 //#endregion
 //#region src/ssp/index.ts
 /**
@@ -1501,6 +1663,11 @@ function createSspClient(options) {
 		}
 	}
 	return {
+		async transfers(transferIds) {
+			if (transferIds.length === 0) return [];
+			if (transferIds.length > 100) throw new SparkInputError("transfers: at most 100 ids per call");
+			return parseTransfersResponse(asObject(await readPost("Transfers", TRANSFERS, { transfer_spark_ids: [...transferIds] }), "transfers"));
+		},
 		async swapFeeEstimate(amountSats) {
 			if (!Number.isSafeInteger(amountSats) || amountSats <= 0) throw new SparkInputError("amount sats must be a positive integer");
 			return currencyAmountSats(asObject((await readPost("LeavesSwapFeeEstimate", LEAVES_SWAP_FEE_ESTIMATE, { total_amount_sats: amountSats }))["leaves_swap_fee_estimate"], "leaves_swap_fee_estimate")["leaves_swap_fee_estimate_output_fee_estimate"], "leaves_swap_fee_estimate_output_fee_estimate");
@@ -3586,6 +3753,16 @@ const CLAIMABLE_TRANSFER_STATUSES = [
 	"RECEIVER_KEY_TWEAKED",
 	"RECEIVER_REFUND_SIGNED"
 ];
+/**
+* Whole-transfer statuses where the sender leg has not finished: the transfer will become claimable
+* (or terminal) later, so a receiver claim must wait and re-query rather than fail.
+*/
+const TRANSIENT_TRANSFER_STATUSES = [
+	"SENDER_INITIATED",
+	"SENDER_KEY_TWEAK_PENDING",
+	"SENDER_INITIATED_COORDINATOR",
+	"APPLYING_SENDER_KEY_TWEAK"
+];
 function millis(timestamp) {
 	if (timestamp === void 0) return;
 	return timestampDate(timestamp).getTime();
@@ -3696,17 +3873,27 @@ async function queryTransfersByIds(options) {
 		network: sparkNetworkProto(options.network)
 	}, options.call)).transfers;
 }
-/** `query_all_transfers` — transfers where the identity is sender or receiver. */
+/**
+* `query_all_transfers` — transfers where the identity is sender or receiver. `types` filters on
+* the server side (empty means all). `nextOffset` is the offset of the following page — `undefined`
+* when the SO reports `-1` (a short page ends the listing).
+*/
 async function queryAllTransfers(options) {
-	return (await options.spark.query_all_transfers({
+	const response = await options.spark.query_all_transfers({
 		participant: {
 			case: "senderOrReceiverIdentityPublicKey",
 			value: options.identityPublicKey
 		},
 		network: sparkNetworkProto(options.network),
 		limit: BigInt(options.limit ?? 100),
-		offset: BigInt(options.offset ?? 0)
-	}, options.call)).transfers.map(mapTransfer);
+		offset: BigInt(options.offset ?? 0),
+		types: [...options.types ?? []]
+	}, options.call);
+	const nextOffset = Number(response.offset);
+	return {
+		transfers: response.transfers.map(mapTransfer),
+		nextOffset: nextOffset < 0 ? void 0 : nextOffset
+	};
 }
 /**
 * Whether `transfer` is exactly the one we signed for: our id, same type, our sender key, and the
@@ -4190,6 +4377,172 @@ async function claimTransfer(options) {
 	if (response.transfer === void 0) throw new SparkError("claimTransfer: coordinator returned no transfer");
 	return verifyClaimedLeaves(receiverLeaves(response.transfer.leaves, receiverId));
 }
+/** Upstream `DEFAULT_RETRY_CONFIG`: five attempts, 1 s base, doubling — 1/2/4/8 s between tries. */
+const CLAIM_RETRY_DELAYS_MS = [
+	1e3,
+	2e3,
+	4e3,
+	8e3
+];
+/** Resolves after `ms` — injected so tests control the pace — or rejects promptly on abort. */
+async function abortableWait(ms, sleep, signal) {
+	if (signal === void 0) {
+		await sleep(ms);
+		return;
+	}
+	if (signal.aborted) throw new SparkRequestError("claim aborted", { code: "canceled" });
+	let onAbort;
+	const aborted = new Promise((_resolve, reject) => {
+		onAbort = () => {
+			reject(new SparkRequestError("claim aborted", { code: "canceled" }));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+	try {
+		await Promise.race([sleep(ms), aborted]);
+	} finally {
+		if (onAbort !== void 0) signal.removeEventListener("abort", onAbort);
+	}
+}
+/**
+* Receiver claim by transfer id (upstream `TransferService.claimTransfer` with `withRetry` and
+* re-query). Every attempt re-queries the transfer: a receiver-leg-complete row returns `[]`, a
+* claimable one is claimed through the caller's `claim` (which serializes the claim plus its chain
+* store under the client leaf lock), a still-transient status waits and retries, and a terminal or
+* unrecognized status fails immediately — retrying `EXPIRED`/`RETURNED` can only burn the budget. A
+* transfer absent from the coordinator's index is treated as transient: the receive event can land
+* seconds before the SSP marks the transfer claimable.
+*/
+async function claimByTransferId(options) {
+	const { spark, signer, network, transferId, sleep, signal, claim } = options;
+	const self = await signer.identityPublicKey();
+	for (let attempt = 0;; attempt += 1) {
+		if (signal?.aborted === true) throw new SparkRequestError("claim aborted", { code: "canceled" });
+		const [row] = await queryTransfersByIds({
+			spark,
+			transferIds: [transferId],
+			network
+		});
+		const transfer = row === void 0 ? void 0 : mapTransfer(row);
+		if (transfer !== void 0) {
+			if (isReceiverLegComplete(transfer, self)) return [];
+			if (CLAIMABLE_TRANSFER_STATUSES.includes(transfer.status)) try {
+				return await claim(transfer);
+			} catch (error) {
+				if (!(error instanceof SparkRequestError) || error.code !== "already_exists") throw error;
+			}
+			else if (!TRANSIENT_TRANSFER_STATUSES.includes(transfer.status)) throw new SparkInputError(`claim: transfer ${transferId} status ${transfer.status} is not claimable`);
+		}
+		const delay = CLAIM_RETRY_DELAYS_MS[attempt];
+		if (delay === void 0) throw new SparkRequestError(`claim: transfer ${transferId} did not become claimable`, { code: "deadline_exceeded" });
+		await abortableWait(delay, sleep, signal);
+	}
+}
+//#endregion
+//#region src/transfer/payment.ts
+/**
+* CoopExitRequest statuses, bucketed per Breez's `SparkCoopExitRequestStatus::acceptance`: accepted
+* means the SSP took the exit over — the SO-side transfer status keeps telling completion; terminal
+* failures are failed; anything else (incl. unknown values) is pending.
+*/
+const COOP_EXIT_ACCEPTED$1 = /* @__PURE__ */ new Set([
+	"INBOUND_TRANSFER_CHECKED",
+	"TX_SIGNED",
+	"TX_BROADCASTED",
+	"WAITING_ON_TX_CONFIRMATIONS",
+	"COMPLETE_REQUEST_RECEIVED",
+	"ON_CHAIN_TX_CONFIRMED",
+	"SUCCEEDED"
+]);
+const COOP_EXIT_FAILED$1 = /* @__PURE__ */ new Set([
+	"EXPIRED",
+	"FAILED",
+	"INBOUND_TRANSFER_CLAIMING_FAILED",
+	"EXPIRING_FAILED",
+	"FAILING_FAILED"
+]);
+/**
+* Whether the transfer's counterparty is the SSP: the receiver on sends (any edge of a
+* multi-receiver), the sender on receives. Shared by the history batch-fetch and the mapper.
+*/
+function sspCounterparty(transfer, identityPublicKey, sspIdentityPublicKey) {
+	return equalBytes(transfer.senderIdentityPublicKey, identityPublicKey) ? equalBytes(transfer.receiverIdentityPublicKey, sspIdentityPublicKey) || transfer.receivers.some((receiver) => equalBytes(receiver.identityPublicKey, sspIdentityPublicKey)) : equalBytes(transfer.senderIdentityPublicKey, sspIdentityPublicKey);
+}
+function toSparkPayment(options) {
+	const { transfer, request } = options;
+	const direction = equalBytes(transfer.senderIdentityPublicKey, options.identityPublicKey) ? "send" : "receive";
+	const isSsp = sspCounterparty(transfer, options.identityPublicKey, options.sspIdentityPublicKey);
+	const method = transfer.type === "COOPERATIVE_EXIT" ? "withdraw" : transfer.type === "UTXO_SWAP" ? "deposit" : transfer.type === "PREIMAGE_SWAP" ? isSsp ? "lightning" : "spark" : "spark";
+	let status;
+	if (transfer.status === "COMPLETED") status = "completed";
+	else if (direction === "send" && transfer.status === "SENDER_KEY_TWEAKED") status = "completed";
+	else if (transfer.status === "EXPIRED" || transfer.status === "RETURNED") status = "failed";
+	else status = "pending";
+	let feeSats = 0;
+	let amountSats = transfer.totalValueSats;
+	let details;
+	switch (method) {
+		case "lightning":
+			if (request?.kind === "lightning-send") {
+				if (request.preimage !== void 0) status = "completed";
+				({feeSats} = request);
+				amountSats = Math.max(0, transfer.totalValueSats - feeSats);
+				details = lightningDetails(request.invoice, request.preimage);
+			} else if (request?.kind === "lightning-receive") details = lightningDetails(request.invoice, request.preimage);
+			break;
+		case "withdraw":
+			if (request?.kind === "coop-exit") {
+				({feeSats} = request);
+				amountSats = Math.max(0, transfer.totalValueSats - feeSats);
+				if (COOP_EXIT_FAILED$1.has(request.status)) status = "failed";
+				else if (!COOP_EXIT_ACCEPTED$1.has(request.status)) status = "pending";
+				details = {
+					kind: "withdraw",
+					...request.txid === void 0 ? {} : { txid: request.txid }
+				};
+			}
+			break;
+		case "deposit":
+			if (request?.kind === "static-deposit") {
+				feeSats = Math.max(0, request.depositAmountSats - request.creditAmountSats);
+				details = {
+					kind: "deposit",
+					txid: request.txid,
+					vout: request.vout
+				};
+			}
+			break;
+		case "spark": details = {
+			kind: "spark",
+			...transfer.sparkInvoice === void 0 ? {} : { invoice: transfer.sparkInvoice }
+		};
+	}
+	if (method !== "spark" && details === void 0) status = "pending";
+	return {
+		id: transfer.id,
+		direction,
+		status,
+		method,
+		amountSats,
+		feeSats,
+		createdAt: transfer.createdTimeMs,
+		details
+	};
+}
+function lightningDetails(invoice, preimage) {
+	try {
+		const decoded = decodeBolt11(invoice);
+		return {
+			kind: "lightning",
+			invoice,
+			paymentHash: bytesToHex$1(decoded.paymentHash),
+			...decoded.description === void 0 ? {} : { description: decoded.description },
+			...preimage === void 0 ? {} : { preimage: bytesToHex$1(preimage) }
+		};
+	} catch {
+		return;
+	}
+}
 //#endregion
 //#region src/transfer/send.ts
 /**
@@ -5821,13 +6174,49 @@ function createTransfers(context) {
 				network
 			})).transfers;
 		},
-		list: async (listOptions) => queryAllTransfers({
-			spark,
-			identityPublicKey: await signer.identityPublicKey(),
-			network,
-			...listOptions?.limit === void 0 ? {} : { limit: listOptions.limit },
-			...listOptions?.offset === void 0 ? {} : { offset: listOptions.offset }
-		}),
+		history: async (historyOptions) => {
+			const limit = historyOptions?.limit ?? 20;
+			if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw new SparkInputError("history: limit must be an integer in 1–100");
+			const offset = historyOptions?.offset ?? 0;
+			if (!Number.isSafeInteger(offset) || offset < 0) throw new SparkInputError("history: offset must be a non-negative integer");
+			const identityPublicKey = await signer.identityPublicKey();
+			const sspIdentityPublicKey = context.config.ssp.identityPublicKey;
+			const { transfers, nextOffset } = await queryAllTransfers({
+				spark,
+				identityPublicKey,
+				network,
+				limit,
+				offset,
+				types: [
+					TransferType.TRANSFER,
+					TransferType.PREIMAGE_SWAP,
+					TransferType.COOPERATIVE_EXIT,
+					TransferType.UTXO_SWAP
+				]
+			});
+			const sspIds = transfers.filter((transfer) => sspCounterparty(transfer, identityPublicKey, sspIdentityPublicKey)).map((transfer) => transfer.id);
+			const requests = /* @__PURE__ */ new Map();
+			for (const result of await context.sspClient.transfers(sspIds)) if (result.request !== void 0) requests.set(result.transferId, result.request);
+			return {
+				payments: transfers.map((transfer) => toSparkPayment({
+					transfer,
+					request: requests.get(transfer.id),
+					identityPublicKey,
+					sspIdentityPublicKey
+				})),
+				nextOffset
+			};
+		},
+		list: async (listOptions) => {
+			const { transfers } = await queryAllTransfers({
+				spark,
+				identityPublicKey: await signer.identityPublicKey(),
+				network,
+				...listOptions?.limit === void 0 ? {} : { limit: listOptions.limit },
+				...listOptions?.offset === void 0 ? {} : { offset: listOptions.offset }
+			});
+			return transfers;
+		},
 		send: async (sendOptions) => sendSats(context, {
 			receivers: [{
 				receiverIdentityPublicKey: context.receiverIdentityKey(sendOptions.receiver),
@@ -5842,13 +6231,19 @@ function createTransfers(context) {
 			})),
 			...sendOptions.transferId === void 0 ? {} : { transferId: sendOptions.transferId }
 		}),
-		claim: async (transfer) => context.leafLock.run(async () => {
-			const claimed = await claimTransfer({
-				...context.transferCoordinator,
-				transfer
-			});
-			await context.storeChainsFor(claimed);
-			return claimed;
+		claim: async (transferId, claimOptions) => claimByTransferId({
+			...context.transferCoordinator,
+			transferId,
+			sleep: context.sleep ?? defaultSleep,
+			...claimOptions?.signal === void 0 ? {} : { signal: claimOptions.signal },
+			claim: async (transfer) => context.leafLock.run(async () => {
+				const claimed = await claimTransfer({
+					...context.transferCoordinator,
+					transfer
+				});
+				await context.storeChainsFor(claimed);
+				return claimed;
+			})
 		}),
 		claimPending: async () => {
 			const pending = await queryPendingTransfers({

package/dist/server.d.mts

@@ -1,4 +1,4 @@
-import { n as SparkClient } from "./index-DISbAuPB.mjs";
+import { n as SparkClient } from "./index-Bq6pNclo.mjs";
 //#region src/server/store.d.ts
 type LightningAddressUser = {
   /** Lowercase LUD-16 local-part. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qntx/spark",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Spark Bitcoin L2 protocol for TypeScript: platform-neutral client, signer and crypto-backend interfaces.",
   "keywords": [
     "bitcoin",