thunder-bridge 1.0.0 → 1.3.0

package/dist/index.d.cts

@@ -1,45 +1,20 @@
-import { T as ThunderBridge, a as ThunderBridgeOptions, W as WatchPaymentParams, b as TriggerEvent, c as WaitOptions, P as Payment, C as CreatePaymentParams, S as Settlement, d as WalletFailure } from './rail-CL9QkiHo.cjs';
-export { B as BankRailConfig, e as CreateOptions, f as CreateQuoteParams, F as FollowOptions, L as Leg, g as LightningRailConfig, O as Order, h as PaymentKind, i as PaymentStatus, Q as Quote, R as Rail, j as WalletReason, k as bankRail, l as lightningRail } from './rail-CL9QkiHo.cjs';
+import { T as ThunderBridge, W as WalletFailure, a as ThunderBridgeOptions, b as WatchPaymentParams, c as TriggerEvent, d as WaitOptions, P as Payment, C as CreatePaymentParams, S as Settlement } from './rail-DZzlN-bi.cjs';
+export { B as BankRailConfig, e as CreateOptions, f as CreateQuoteParams, F as FollowOptions, L as Leg, g as LightningRailConfig, O as Order, h as PaymentKind, i as PaymentStatus, Q as Quote, R as Rail, j as WalletReason, k as bankRail, l as lightningRail, t as toLnurl } from './rail-DZzlN-bi.cjs';
 
-interface GatewaysOptions extends ThunderBridgeOptions {
-    /**
-     * Called for each gateway that would not take the watch, with the url and what
-     * it said. Registering at three and having one refuse still leaves you watched,
-     * so this is how you find out you are less covered than you asked to be, rather
-     * than finding out when the one that took it goes away
-     */
-    onRefused?: (baseUrl: string, refusal: unknown) => void;
+/** What a BOLT11 invoice says about itself, every field null when it does not carry one */
+interface Invoice {
+    paymentHash: string | null;
+    descriptionHash: string | null;
+    amountMsat: number | null;
+    expiresAt: number | null;
 }
 /**
- * The same payment watched at several gateways at once, which is what makes any
- * one of them replaceable. They all answer with the same name for it, because a
- * payment is named after the caller and not after any gateway, so the first
- * delivery to arrive is the answer and the rest are the same news twice.
- *
- * For watching only. Two gateways asked to mint would fetch two different invoices
- * from the wallet and only one of them could ever be paid
+ * Read a BOLT11 invoice without trusting anyone for its contents, an
+ * undecodable string or a BOLT12 offer yields an invoice with every field null
  */
-declare class Gateways {
-    readonly each: readonly ThunderBridge[];
-    private readonly urls;
-    private readonly onRefused;
-    constructor(baseUrls: string[], options?: GatewaysOptions);
-    /** What this payment is called, which every gateway here will agree on */
-    nameFor(paymentHash: string): Promise<string | null>;
-    /**
-     * Hand the same invoice to every gateway. Throws only when none of them took it,
-     * carrying the first refusal, because one gateway that agreed is enough to be
-     * watched
-     */
-    watchPayment(params: WatchPaymentParams): Promise<TriggerEvent>;
-    /**
-     * Wait for whichever gateway speaks first. A settlement from any of them is the
-     * settlement, and each has already proved the preimage against the hash before
-     * saying so. When they all end without a payment, the first ending is the answer,
-     * and when they all fail, the first failure is thrown
-     */
-    waitForWatched(id: string, options?: WaitOptions): Promise<TriggerEvent>;
-}
+declare function decodeInvoice(bolt11: string): Invoice;
+/** True when `preimage` is the secret behind `paymentHash` */
+declare function preimageMatchesHash(preimage: string, paymentHash: string): boolean;
 
 /**
  * Encrypt what the watcher needs and the gateway must not have. The gateway
@@ -101,6 +76,8 @@ interface BankTransferParams {
      * order the same secret and both rails arrive on one stream
      */
     trigger?: string;
+    /** How many settlements of that trigger the gateway keeps replayable past the hour, needs `trigger` */
+    replay?: number;
     /**
      * Handed back untouched on that stream, so a watcher learns which order settled
      * without asking anyone. `seal` it and the gateway cannot read it either
@@ -178,6 +155,110 @@ declare function bankTransfer(params: BankTransferParams): Promise<BankTransfer>
  */
 declare function bankVerifyEndpoint(config: BankVerifyConfig): (request: Request) => Promise<Response>;
 
+/**
+ * How many digits ISO 4217 gives the currency's minor unit, so 2 for a crown and a
+ * euro, 0 for a yen and 3 for a dinar.
+ *
+ * There is no sane default here, which is why an unlisted code throws rather than
+ * being treated as two. Assuming two turns 1000 yen into 10 and a dinar into a
+ * tenth of itself, and a payment library that guesses at this is a payment library
+ * that moves the wrong amount.
+ */
+declare function minorUnitsOf(currency: string): number;
+/** The scale that minor unit implies, so 100 for a crown, 1 for a yen, 1000 for a dinar */
+declare function minorScaleOf(currency: string): number;
+
+/**
+ * The way a gateway was caught out, every code is a check that held against the
+ * recipient's own server and failed against what the gateway returned
+ */
+type GatewayCheatCode = "address_not_requested" | "hash_mismatch" | "amount_mismatch" | "description_hash_mismatch" | "verify_url_foreign" | "invoice_not_issued" | "preimage_mismatch" | "id_not_mine";
+/**
+ * Thrown when the gateway demonstrably misbehaved, the invoice it returned is
+ * not the one the address you asked for issued, or a settlement it reported
+ * carries a preimage that does not hash to the payment hash
+ */
+declare class GatewayCheatError extends Error {
+    readonly code: GatewayCheatCode;
+    readonly paymentId: string;
+    constructor(code: GatewayCheatCode, paymentId: string);
+}
+/**
+ * The way a wrapping operator was caught out. Every code is the wrapped invoice
+ * failing to bind to the recipient's own, which is the only thing that makes
+ * paying the wrap the same act as paying the recipient
+ */
+type WrapRefusalCode = "undecodable" | "hash_mismatch" | "amount_below_recipient" | "fee_above_allowance" | "recipient_expires_first";
+/**
+ * Thrown when a wrapped invoice does not bind to the recipient's. Paying it
+ * would be paying the operator on its word rather than on the shared payment
+ * hash, which is the whole of what makes wrapping safe
+ */
+declare class WrapRefusedError extends Error {
+    readonly code: WrapRefusalCode;
+    constructor(code: WrapRefusalCode, detail: string);
+}
+/**
+ * Thrown when the recipient's own server could not be reached to check the
+ * invoice against, a CORS-blocked browser or a provider that is down, this is
+ * not proof the gateway cheated and it is not proof it did not
+ */
+declare class UnverifiedRecipientError extends Error {
+    readonly lnAddress: string;
+    readonly paymentId: string;
+    constructor(lnAddress: string, paymentId: string, cause: unknown);
+}
+/** An RFC 9457 problem document the gateway answered with */
+declare class ProblemError extends Error {
+    readonly type: string;
+    readonly title: string;
+    readonly status: number;
+    readonly detail: string | null;
+    constructor(problem: {
+        type?: string;
+        title?: string;
+        status?: number;
+        detail?: string;
+    });
+}
+/** Whether a problem document carries this type */
+declare function isProblemType(problem: {
+    type?: string;
+}, type: string): boolean;
+declare const NO_WALLET_AVAILABLE = "urn:problem-type:thunder-bridge:no-wallet-available";
+declare const REQUEST_IN_FLIGHT = "urn:problem-type:thunder-bridge:request-in-flight";
+declare const IDEMPOTENCY_KEY_REUSED = "urn:problem-type:thunder-bridge:idempotency-key-reused";
+declare const PAYMENT_ALREADY_WATCHED = "urn:problem-type:thunder-bridge:payment-already-watched";
+/**
+ * Why an `Idempotency-Key` was refused, `request-in-flight` is the benign one and
+ * `key-reused` means the same key was sent for a different request
+ */
+type IdempotencyConflict = "request-in-flight" | "key-reused";
+/**
+ * Thrown when an `Idempotency-Key` is held by another request. On
+ * `request-in-flight` the first attempt is still resolving, so wait and read the
+ * payment back rather than retrying. `key-reused` is a bug in the caller: the key
+ * is bound to the addresses, amount and webhook that claimed it
+ */
+declare class IdempotencyConflictError extends ProblemError {
+    readonly conflict: IdempotencyConflict;
+    constructor(problem: {
+        type?: string;
+        title?: string;
+        status?: number;
+        detail?: string;
+    }, conflict: IdempotencyConflict);
+}
+/** Thrown when no wallet on your list could issue a provable invoice, `wallets` says why each refused */
+declare class NoWalletAvailableError extends ProblemError {
+    readonly wallets: WalletFailure[];
+    constructor(problem: {
+        title?: string;
+        status?: number;
+        detail?: string;
+    }, wallets: WalletFailure[]);
+}
+
 interface FioConfig {
     /**
      * A token with "Sledování účtu" rights, which is read only and cannot move
@@ -217,6 +298,46 @@ interface FioConfig {
  */
 declare function fioStatement(config: FioConfig): Statement;
 
+interface GatewaysOptions extends ThunderBridgeOptions {
+    /**
+     * Called for each gateway that would not take the watch, with the url and what
+     * it said. Registering at three and having one refuse still leaves you watched,
+     * so this is how you find out you are less covered than you asked to be, rather
+     * than finding out when the one that took it goes away
+     */
+    onRefused?: (baseUrl: string, refusal: unknown) => void;
+}
+/**
+ * The same payment watched at several gateways at once, which is what makes any
+ * one of them replaceable. They all answer with the same name for it, because a
+ * payment is named after the caller and not after any gateway, so the first
+ * delivery to arrive is the answer and the rest are the same news twice.
+ *
+ * For watching only. Two gateways asked to mint would fetch two different invoices
+ * from the wallet and only one of them could ever be paid
+ */
+declare class Gateways {
+    readonly each: readonly ThunderBridge[];
+    private readonly urls;
+    private readonly onRefused;
+    constructor(baseUrls: string[], options?: GatewaysOptions);
+    /** What this payment is called, which every gateway here will agree on */
+    nameFor(paymentHash: string): Promise<string | null>;
+    /**
+     * Hand the same invoice to every gateway. Throws only when none of them took it,
+     * carrying the first refusal, because one gateway that agreed is enough to be
+     * watched
+     */
+    watchPayment(params: WatchPaymentParams): Promise<TriggerEvent>;
+    /**
+     * Wait for whichever gateway speaks first. A settlement from any of them is the
+     * settlement, and each has already proved the preimage against the hash before
+     * saying so. When they all end without a payment, the first ending is the answer,
+     * and when they all fail, the first failure is thrown
+     */
+    waitForWatched(id: string, options?: WaitOptions): Promise<TriggerEvent>;
+}
+
 /**
  * How many minor units of `currency` one bitcoin costs at one venue, so 134883815
  * is 1,348,838.15 CZK. Throws when that venue does not quote that currency, which
@@ -286,57 +407,6 @@ declare function msatFor(amountMinor: number, priceMinorPerBtc: number, options?
     spreadBps?: number;
 }): number;
 
-/**
- * How many digits ISO 4217 gives the currency's minor unit, so 2 for a crown and a
- * euro, 0 for a yen and 3 for a dinar.
- *
- * There is no sane default here, which is why an unlisted code throws rather than
- * being treated as two. Assuming two turns 1000 yen into 10 and a dinar into a
- * tenth of itself, and a payment library that guesses at this is a payment library
- * that moves the wrong amount.
- */
-declare function minorUnitsOf(currency: string): number;
-/** The scale that minor unit implies, so 100 for a crown, 1 for a yen, 1000 for a dinar */
-declare function minorScaleOf(currency: string): number;
-
-/**
- * Prove the invoice really is the one the recipient issued for what you asked,
- * before the payer ever sees it, both fetches go straight to the recipient's own
- * server and none of them goes back to the gateway
- *
- * Throws `GatewayCheatError` when a check fails and `UnverifiedRecipientError`
- * when the recipient could not be reached to run one
- */
-declare function proveOrigin(payment: Payment, request: CreatePaymentParams): Promise<void>;
-/**
- * Prove the money arrived by asking the recipient's own server, not the gateway,
- * returns the preimage when the recipient says it settled and null when it says
- * it has not, and runs the full origin proof first because a verify url the
- * gateway made up would otherwise answer for itself
- */
-declare function proveSettlement(payment: Payment, request: CreatePaymentParams): Promise<string | null>;
-/**
- * True when the gateway's own report of a settlement is at least self-consistent,
- * the preimage hashes to the payment hash the invoice itself carries, this is a
- * sanity check and not a proof, only `proveSettlement` asks the recipient
- */
-declare function isProvablyPaid(payment: Payment): boolean;
-
-/** What a BOLT11 invoice says about itself, every field null when it does not carry one */
-interface Invoice {
-    paymentHash: string | null;
-    descriptionHash: string | null;
-    amountMsat: number | null;
-    expiresAt: number | null;
-}
-/**
- * Read a BOLT11 invoice without trusting anyone for its contents, an
- * undecodable string or a BOLT12 offer yields an invoice with every field null
- */
-declare function decodeInvoice(bolt11: string): Invoice;
-/** True when `preimage` is the secret behind `paymentHash` */
-declare function preimageMatchesHash(preimage: string, paymentHash: string): boolean;
-
 interface QrOptions {
     /** SVG width and height in pixels, defaults to 256 */
     size?: number;
@@ -373,11 +443,61 @@ declare function qrToSvg(payload: string, options?: QrOptions): string;
 declare function qrToDataUrl(payload: string, options?: QrOptions): string;
 
 /**
- * Bech32-encode a pay endpoint as the `LNURL1` string LUD-01 defines, uppercase
- * because that is the form it asks a QR to carry. An onion endpoint is http
- * rather than https, which LUD-17 spells out, so both are taken here
+ * What a wrapping operator may charge over the recipient's own amount. This is a
+ * ceiling the client sets rather than a price the operator names, so it sits
+ * above what any operator lists and refuses only the ones reaching past it
+ */
+interface WrapAllowance {
+    /** As a fraction of the recipient's amount, `0.01` by default */
+    proportion?: number;
+    /** The floor in millisatoshi whatever the fraction works out to, `1000` by default */
+    baseMsat?: number;
+}
+/**
+ * Prove the invoice really is the one the recipient issued for what you asked,
+ * before the payer ever sees it, both fetches go straight to the recipient's own
+ * server and none of them goes back to the gateway
+ *
+ * Throws `GatewayCheatError` when a check fails and `UnverifiedRecipientError`
+ * when the recipient could not be reached to run one
+ */
+declare function proveOrigin(payment: Payment, request: CreatePaymentParams): Promise<void>;
+/**
+ * Prove the money arrived by asking the recipient's own server, not the gateway,
+ * returns the preimage when the recipient says it settled and null when it says
+ * it has not, and runs the full origin proof first because a verify url the
+ * gateway made up would otherwise answer for itself
+ */
+declare function proveSettlement(payment: Payment, request: CreatePaymentParams): Promise<string | null>;
+/**
+ * True when the gateway's own report of a settlement is at least self-consistent,
+ * the preimage hashes to the payment hash the invoice itself carries, this is a
+ * sanity check and not a proof, only `proveSettlement` asks the recipient
  */
-declare function toLnurl(endpoint: string): string;
+declare function isProvablyPaid(payment: Payment): boolean;
+/**
+ * The most an operator may add over the recipient's own amount, in millisatoshi.
+ * The proportion is what routing and the liquidity behind it costs, and the base
+ * is the floor it never drops below, because a fraction of a small payment
+ * rounds to nothing the operator can work for
+ */
+declare function wrapFeeCeiling(amountMsat: number, allowance?: WrapAllowance): number;
+/**
+ * Prove a wrapping operator's invoice is the recipient's own payment in
+ * disguise, so paying it can only settle by the operator paying the recipient.
+ *
+ * It compares two invoices and asks nobody anything, so it runs in a browser and
+ * costs no round trip. Prove the recipient's own invoice with `proveOrigin`
+ * first, because this says nothing about where that one came from.
+ *
+ * There is no settlement check here and there does not need to be. Both invoices
+ * carry one payment hash, so the preimage that settles the wrap is the preimage
+ * the recipient released, and `proveSettlement` already reads it from the
+ * recipient's own server.
+ *
+ * Throws `WrapRefusedError` naming which binding failed
+ */
+declare function proveWrapped(wrapped: string, recipient: string, allowance?: WrapAllowance): void;
 
 /** How far the gateway's clock may drift from yours before a webhook is refused */
 type WebhookOptions = {
@@ -447,80 +567,4 @@ declare function answerVerifyChallenge(body: string): string | null;
 /** {@link answerVerifyChallenge} against a `Request`, leaving its body unread */
 declare function answerVerifyChallengeRequest(request: Request): Promise<Response | null>;
 
-/**
- * The way a gateway was caught out, every code is a check that held against the
- * recipient's own server and failed against what the gateway returned
- */
-type GatewayCheatCode = "address_not_requested" | "hash_mismatch" | "amount_mismatch" | "description_hash_mismatch" | "verify_url_foreign" | "invoice_not_issued" | "preimage_mismatch" | "id_not_mine";
-/**
- * Thrown when the gateway demonstrably misbehaved, the invoice it returned is
- * not the one the address you asked for issued, or a settlement it reported
- * carries a preimage that does not hash to the payment hash
- */
-declare class GatewayCheatError extends Error {
-    readonly code: GatewayCheatCode;
-    readonly paymentId: string;
-    constructor(code: GatewayCheatCode, paymentId: string);
-}
-/**
- * Thrown when the recipient's own server could not be reached to check the
- * invoice against, a CORS-blocked browser or a provider that is down, this is
- * not proof the gateway cheated and it is not proof it did not
- */
-declare class UnverifiedRecipientError extends Error {
-    readonly lnAddress: string;
-    readonly paymentId: string;
-    constructor(lnAddress: string, paymentId: string, cause: unknown);
-}
-/** An RFC 9457 problem document the gateway answered with */
-declare class ProblemError extends Error {
-    readonly type: string;
-    readonly title: string;
-    readonly status: number;
-    readonly detail: string | null;
-    constructor(problem: {
-        type?: string;
-        title?: string;
-        status?: number;
-        detail?: string;
-    });
-}
-/** Whether a problem document carries this type */
-declare function isProblemType(problem: {
-    type?: string;
-}, type: string): boolean;
-declare const NO_WALLET_AVAILABLE = "urn:problem-type:thunder-bridge:no-wallet-available";
-declare const REQUEST_IN_FLIGHT = "urn:problem-type:thunder-bridge:request-in-flight";
-declare const IDEMPOTENCY_KEY_REUSED = "urn:problem-type:thunder-bridge:idempotency-key-reused";
-declare const PAYMENT_ALREADY_WATCHED = "urn:problem-type:thunder-bridge:payment-already-watched";
-/**
- * Why an `Idempotency-Key` was refused, `request-in-flight` is the benign one and
- * `key-reused` means the same key was sent for a different request
- */
-type IdempotencyConflict = "request-in-flight" | "key-reused";
-/**
- * Thrown when an `Idempotency-Key` is held by another request. On
- * `request-in-flight` the first attempt is still resolving, so wait and read the
- * payment back rather than retrying. `key-reused` is a bug in the caller: the key
- * is bound to the addresses, amount and webhook that claimed it
- */
-declare class IdempotencyConflictError extends ProblemError {
-    readonly conflict: IdempotencyConflict;
-    constructor(problem: {
-        type?: string;
-        title?: string;
-        status?: number;
-        detail?: string;
-    }, conflict: IdempotencyConflict);
-}
-/** Thrown when no wallet on your list could issue a provable invoice, `wallets` says why each refused */
-declare class NoWalletAvailableError extends ProblemError {
-    readonly wallets: WalletFailure[];
-    constructor(problem: {
-        title?: string;
-        status?: number;
-        detail?: string;
-    }, wallets: WalletFailure[]);
-}
-
-export { type BankTransfer, type BankTransferParams, type BankVerifyConfig, CreatePaymentParams, type Credit, type FioConfig, type GatewayCheatCode, GatewayCheatError, Gateways, type GatewaysOptions, IDEMPOTENCY_KEY_REUSED, type IdempotencyConflict, IdempotencyConflictError, type Invoice, type MedianOptions, NO_WALLET_AVAILABLE, NoWalletAvailableError, PAYMENT_ALREADY_WATCHED, Payment, ProblemError, type QrOptions, REQUEST_IN_FLIGHT, Settlement, type Statement, ThunderBridge, ThunderBridgeOptions, type Ticker, TriggerEvent, UnverifiedRecipientError, WaitOptions, WalletFailure, WatchPaymentParams, type WebhookCredential, type WebhookOptions, answerVerifyChallenge, answerVerifyChallengeRequest, answerWebhookChallenge, answerWebhookChallengeRequest, bankTransfer, bankVerifyEndpoint, bitstamp, coinbase, coinmate, decodeInvoice, fioStatement, invoiceToDataUrl, invoiceToSvg, isProblemType, isProvablyPaid, isProvablySettled, kraken, lnurlToDataUrl, lnurlToSvg, medianOf, minorScaleOf, minorUnitsOf, msatFor, parseSettlement, parseSettlementRequest, parseWatchedWebhook, parseWatchedWebhookRequest, parseWebhook, parseWebhookRequest, preimageMatchesHash, proveOrigin, proveSettlement, qrToDataUrl, qrToSvg, seal, spdToDataUrl, spdToSvg, toLnurl, unseal, verifyWebhookSignature };
+export { type BankTransfer, type BankTransferParams, type BankVerifyConfig, CreatePaymentParams, type Credit, type FioConfig, type GatewayCheatCode, GatewayCheatError, Gateways, type GatewaysOptions, IDEMPOTENCY_KEY_REUSED, type IdempotencyConflict, IdempotencyConflictError, type Invoice, type MedianOptions, NO_WALLET_AVAILABLE, NoWalletAvailableError, PAYMENT_ALREADY_WATCHED, Payment, ProblemError, type QrOptions, REQUEST_IN_FLIGHT, Settlement, type Statement, ThunderBridge, ThunderBridgeOptions, type Ticker, TriggerEvent, UnverifiedRecipientError, WaitOptions, WalletFailure, WatchPaymentParams, type WebhookCredential, type WebhookOptions, type WrapAllowance, type WrapRefusalCode, WrapRefusedError, answerVerifyChallenge, answerVerifyChallengeRequest, answerWebhookChallenge, answerWebhookChallengeRequest, bankTransfer, bankVerifyEndpoint, bitstamp, coinbase, coinmate, decodeInvoice, fioStatement, invoiceToDataUrl, invoiceToSvg, isProblemType, isProvablyPaid, isProvablySettled, kraken, lnurlToDataUrl, lnurlToSvg, medianOf, minorScaleOf, minorUnitsOf, msatFor, parseSettlement, parseSettlementRequest, parseWatchedWebhook, parseWatchedWebhookRequest, parseWebhook, parseWebhookRequest, preimageMatchesHash, proveOrigin, proveSettlement, proveWrapped, qrToDataUrl, qrToSvg, seal, spdToDataUrl, spdToSvg, unseal, verifyWebhookSignature, wrapFeeCeiling };