@qntx/spark 0.2.0 → 0.3.0

package/README.md

@@ -66,7 +66,7 @@ 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.
 
 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-rHuqmVV3.d.mts}

@@ -463,8 +463,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

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 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 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-rHuqmVV3.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. */
@@ -68,6 +68,14 @@ export declare function encodeTokenIdentifier(tokenIdentifier: Uint8Array, netwo
  */
 export declare function decodeTokenIdentifier(text: string): SparkTokenIdentifierData;
 //#endregion
+//#region src/core/uuid.d.ts
+/**
+ * UUIDv7 (RFC 9562 §5.7): 48-bit millisecond timestamp, then 74 random bits with the version (0111)
+ * and variant (10) fields applied. Randomness and the clock are injected so the function stays
+ * platform-neutral and deterministic under test.
+ */
+export declare function uuidv7(random: (length: number) => Uint8Array, now?: () => number): string;
+//#endregion
 //#region src/invoice/create.d.ts
 type InvoiceOptions = {
   readonly signer: SparkSigner;

package/dist/index.mjs

@@ -3586,6 +3586,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();
@@ -4190,6 +4200,67 @@ 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/send.ts
 /**
@@ -5842,13 +5913,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({
@@ -7328,4 +7405,4 @@ function createMemorySparkStore() {
 	};
 }
 //#endregion
-export { EPHEMERAL_ANCHOR_SCRIPT, MIN_STATIC_REFUND_FEE_SATS, SparkCryptoError, SparkError, SparkInputError, SparkRequestError, SparkTokenBroadcastError, addressToScript, buildCpfpChild, createMemorySparkStore, createSatsInvoice, createSparkClient, createTokensInvoice, decodeBolt11, decodeSparkAddress, decodeTokenIdentifier, encodeSparkAddress, encodeTokenIdentifier, exitTransactions, isExpired, parseSparkInvoice, sparkNetworkConfig, verifySparkAddressSignature };
+export { EPHEMERAL_ANCHOR_SCRIPT, MIN_STATIC_REFUND_FEE_SATS, SparkCryptoError, SparkError, SparkInputError, SparkRequestError, SparkTokenBroadcastError, addressToScript, buildCpfpChild, createMemorySparkStore, createSatsInvoice, createSparkClient, createTokensInvoice, decodeBolt11, decodeSparkAddress, decodeTokenIdentifier, encodeSparkAddress, encodeTokenIdentifier, exitTransactions, isExpired, parseSparkInvoice, sparkNetworkConfig, uuidv7, verifySparkAddressSignature };

package/dist/server.d.mts

@@ -1,4 +1,4 @@
-import { n as SparkClient } from "./index-DISbAuPB.mjs";
+import { n as SparkClient } from "./index-rHuqmVV3.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.0",
+  "version": "0.3.0",
   "description": "Spark Bitcoin L2 protocol for TypeScript: platform-neutral client, signer and crypto-backend interfaces.",
   "keywords": [
     "bitcoin",