thunder-bridge 1.5.0 → 2.2.0

package/dist/{client-CzGZcByI.d.cts → bank-Bg6RjuO-.d.cts}

@@ -1,12 +1,12 @@
 import { R as Resolved, Q as QrOptions } from './qr-CF-YeXU1.cjs';
-import { A as Amount, T as Ticker, C as Charge, e as MintedPayment, g as PaymentStatus, h as Priced, f as Msat, S as Settlement, P as Payment, Q as Quote, H as Handover, i as SocketTicket } from './types-BNPmVnA7.cjs';
-import { a as BankTransferParams, B as BankTransfer, b as BankVerifyConfig } from './bank-B3mHISn1.cjs';
+import { A as Amount, T as Ticker, C as Charge, f as MintedPayment, h as PaymentStatus, i as Priced, g as Msat, S as Settlement, P as Payment, Q as Quote, e as Held, H as Handover, j as SocketTicket } from './types-DYZ9EkmJ.cjs';
 
 type Sent = {
     method?: string;
     headers?: Record<string, string>;
     body?: string;
     deadline?: AbortSignal;
+    staysOnOrigin?: boolean;
 };
 type Verified = {
     address: string;
@@ -15,6 +15,120 @@ type Verified = {
 /** Carries one request to an address ask() already verified, so nothing resolves the name again */
 type Send = (url: string, sent: Sent, signal: AbortSignal, at: readonly Verified[]) => Promise<Response>;
 
+/** A wallet reachable over NIP-47, as its `nostr+walletconnect://` URI describes it */
+interface NwcConnection {
+    /** The wallet service's public key, which is what its answers have to be signed by */
+    walletPubkey: string;
+    /** Where to reach it, tried in order until one answers */
+    relays: string[];
+    /** Our own private key on this connection, and the only thing that authorises it */
+    secret: string;
+}
+/** A minted invoice and everything needed to watch it */
+interface NwcInvoice {
+    bolt11: string;
+    paymentHash: string;
+    expiresAt: number;
+}
+/** The endpoint the gateway polls for an NWC payment, answering off your own wallet */
+interface NwcVerifyConfig {
+    /** The wallet this endpoint speaks for. It never leaves this process */
+    connection: NwcConnection;
+    /** The secret the payment hash was sealed with, and nothing else uses it */
+    secret: string;
+    /** How often the gateway should ask, in seconds, sent as `Cache-Control: max-age`, `5` by default */
+    pollEverySecs?: number;
+    /** How long one `lookup_invoice` may take before the wallet counts as unreachable, `10_000` by default */
+    askTimeoutMs?: number;
+}
+/**
+ * Read a `nostr+walletconnect://` URI. Refuses a relay that is not `wss`, for the
+ * reason the gateway refuses a verify URL that is not https
+ */
+declare function nwcConnection(uri: string): NwcConnection;
+/** Mint an invoice on the connected wallet, decoded so the caller need not trust its word */
+declare function nwcInvoice(connection: NwcConnection, amountMsat: number, description: string, timeoutMs?: number): Promise<NwcInvoice>;
+/**
+ * Mint a hold invoice on a hash the wallet does not hold the preimage for, which
+ * is what lets an operator be paid only by paying somebody else first. The hash
+ * has to come from the recipient's own invoice, and the invoice that comes back
+ * is decoded rather than believed
+ */
+declare function nwcHoldInvoice(connection: NwcConnection, held: {
+    paymentHash: string;
+    amountMsat: number;
+    description: string;
+    expirySecs: number;
+    minCltvExpiryDelta?: number;
+}, timeoutMs?: number): Promise<NwcInvoice>;
+/**
+ * The preimage the wallet released for this hash, null while it has released
+ * none. A preimage that does not hash to what was asked for is a lie rather than
+ * an answer, so it throws instead of being passed on
+ */
+declare function nwcSettlement(connection: NwcConnection, paymentHash: string, timeoutMs?: number): Promise<string | null>;
+/**
+ * Pay an invoice and keep the preimage the network handed back. Whoever pays
+ * learns it, which is what makes delivery provable to a recipient publishing no
+ * LUD-21 of their own. A preimage that does not hash to the invoice's own hash is
+ * a lie rather than a receipt, so it throws instead of being passed on
+ */
+declare function nwcPay(connection: NwcConnection, bolt11: string, timeoutMs?: number): Promise<string>;
+/**
+ * A verify endpoint of your own that asks your wallet over NIP-47, so the gateway
+ * polls you and never learns the connection, the relay, or which wallet it is.
+ *
+ * `nwcVerifyUrl` seals the payment hash into the query with your secret, which is
+ * what stops a stranger driving your wallet through this handler. It answers the
+ * LUD-21 shape the gateway already speaks, so nothing on that side changes.
+ *
+ * A wallet it cannot reach answers `502` rather than "not settled", because those
+ * are different claims and only one of them is true.
+ */
+declare function nwcVerifyEndpoint(config: NwcVerifyConfig): (request: Request) => Promise<Response>;
+/**
+ * The URL to hand the gateway, with the payment hash sealed inside it. Point it at
+ * wherever `nwcVerifyEndpoint` is mounted
+ */
+declare function nwcVerifyUrl(endpoint: string, paymentHash: string, secret: string): Promise<string>;
+/**
+ * One NIP-47 call, for a method this SDK does not wrap. The wallet's own info
+ * event lists what it will answer, and anything it refuses comes back as a
+ * `WalletRefused` whose `reason` says which kind of refusal it was
+ */
+declare function askWallet(connection: NwcConnection, method: string, params: Record<string, unknown>, timeoutMs?: number): Promise<Record<string, unknown>>;
+/** A Lightning rail minting on a wallet of your own over NIP-47, bound once per shop */
+interface NwcRailConfig extends RailConfig {
+    /** The wallet that mints, which never leaves this process */
+    connection: NwcConnection;
+    /**
+     * What to charge for one order, the order's own price converted at `rate` by
+     * default. Give it a function and the price is whatever you say
+     */
+    amount?: (order: Order) => Amount;
+    /** Where the default conversion gets its rate, the median of four venues by default */
+    rate?: Ticker;
+    /** Where `nwcVerifyEndpoint` is mounted, and the secret the hash is sealed with */
+    verifyThrough: {
+        endpoint: string;
+        secret: string;
+    };
+    /** What the payer's wallet shows, the order's reference by default */
+    description?: (order: Order) => string;
+    /** Sealed before the gateway sees it, the way the blind Lightning rail does */
+    sealed?: {
+        secret: string;
+        data: (order: Order) => unknown;
+    };
+}
+/**
+ * Sell for Lightning against a wallet of your own over NIP-47, for a wallet that
+ * has no LUD-21 address to be watched at. Your node mints the invoice and releases
+ * the preimage, so the proof comes from one hop nearer than any hosted address can
+ * manage, and the gateway sees a hash and a URL of yours
+ */
+declare function nwcRail(gateway: ThunderBridge, config: NwcRailConfig): Rail;
+
 /** What a shop knows about a sale before any rail exists */
 interface Order {
     /** The bank matches it on the statement, and Lightning keys idempotency on it */
@@ -26,8 +140,9 @@ interface Order {
 }
 /** One way to pay one order, already registered with the gateway */
 interface Leg {
-    /** The watched payment's id, which is what `firstSettled`, `payment` and `settled` take */
+    /** The watched payment's id, which with `paymentHash` is what `firstSettled`, `payment` and `settled` take */
     id: string;
+    paymentHash: string;
     /** Which rail made it, so a shop can label a leg without knowing how it was built */
     rail: string;
     /** What the payer reads, a BOLT11 invoice or a Short Payment Descriptor */
@@ -69,10 +184,13 @@ interface LightningRailConfig extends RailConfig {
 /** The same rail with the invoice resolved here, so the gateway is told neither address nor amount */
 interface BlindLightningRailConfig extends LightningRailConfig {
     /**
-     * What the watcher needs and the gateway must not read, sealed with `seal`
-     * before it goes anywhere near the gateway
+     * What the watcher needs and the gateway must not read, sealed under `secret`
+     * for the invoice's payment hash before it goes anywhere near the gateway
      */
-    sealed?: (order: Order) => string | Promise<string>;
+    sealed?: {
+        secret: string;
+        data: (order: Order) => unknown;
+    };
     /**
      * Where your own `serve.verify` endpoint is mounted, and its secret. Without
      * it the gateway is handed the wallet's own URL, which a gateway enforcing its
@@ -96,12 +214,15 @@ interface BankRailConfig extends RailConfig {
     /** When this leg stops being payable, in unix seconds */
     expiresAt: (order: Order) => number;
     /** Sealed before the gateway sees it, the way the blind Lightning rail does */
-    sealed?: (order: Order) => string | Promise<string>;
+    sealed?: {
+        secret: string;
+        data: (order: Order) => unknown;
+    };
     /** The Czech variable symbol, taken off the reference's digits by default */
     variableSymbol?: (order: Order) => string | undefined;
     /**
-     * Register on a gateway you do not own anyway. The verify URL names the amount
-     * and the reference, so its operator could read your order book off the watches
+     * Register on a gateway you do not own anyway. The sealed verify URL names
+     * nothing about the order, but its operator still learns every watch you place
      */
     allowPublicGateway?: boolean;
 }
@@ -132,6 +253,13 @@ declare class Rails {
     blindLightning(config: BlindLightningRailConfig): Rail;
     /** A bank transfer, proved the way a Lightning payment is */
     bank(config: BankRailConfig): Rail;
+    /**
+     * Lightning against a wallet of your own over NIP-47, for a wallet that has no
+     * LUD-21 address to be watched at. Your node mints the invoice and releases the
+     * preimage, so the proof comes from one hop nearer than any hosted address can
+     * manage, and the gateway sees a hash and a URL of yours
+     */
+    nwc(config: NwcRailConfig): Rail;
     /**
      * One bank transfer without building a rail first, for a shop that asks for
      * them one at a time rather than beside another payment method
@@ -180,7 +308,7 @@ interface PaymentRequest {
      * unpaid or the wait is aborted. It follows a WebSocket and reconnects through
      * a drop, so this is one await rather than a poll.
      *
-     * `gateway.settled(id)` is the wider question and ends on an expiry too. This
+     * `gateway.settled(payment)` is the wider question and ends on an expiry too. This
      * one is about the payment that was asked for, and one that expired was never paid
      */
     paid(options?: WaitOptions): Promise<MintedPayment>;
@@ -335,7 +463,7 @@ interface WrapAllowance {
  * Throws `GatewayCheatError` when a check fails and `UnverifiedRecipientError`
  * when the recipient could not be reached to run one
  */
-declare function proveOrigin(payment: MintedPayment, asked: Priced): Promise<void>;
+declare function proveOrigin(payment: MintedPayment, asked: Priced, askedAt?: number): 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
@@ -351,26 +479,39 @@ interface Provable {
     bolt11?: string | null;
 }
 /**
- * A report `carriesProof` has already accepted, so the preimage is there and the
- * status is settled. Nothing downstream of the check needs a null guard
+ * A report `agreesWithItself` has already accepted, so the preimage is there and
+ * the status is settled. Nothing downstream of the check needs a null guard
  */
-type Proven<T extends Provable> = T & {
+type SelfConsistent<T extends Provable> = T & {
     status: "paid";
     preimage: string;
 };
 /**
- * Whether a report proves what it claims: it says paid, and it carries a preimage
+ * What `SelfConsistent` was called before 2.2.0
+ *
+ * @deprecated Use `SelfConsistent`, which says the report was checked against itself and nothing else
+ */
+type Proven<T extends Provable> = SelfConsistent<T>;
+/**
+ * Whether a report agrees with itself: it says paid, and it carries a preimage
  * that hashes to the payment hash it itself names. Where an invoice comes with it,
  * the invoice's own hash has to agree too.
  *
  * A payment, a settlement delivered to a webhook and a frame off a trigger all
- * answer this, because all three carry those fields and no other question about
- * one matters.
+ * answer this, because all three carry those fields.
  *
- * It asks nobody anything, so it costs no round trip and is not a proof of
- * arrival. Only `proveSettlement` asks the recipient
+ * It asks nobody anything and holds the report against nothing you hold, so a
+ * gateway that invents a preimage and names its hash passes it. Checking against
+ * the hash you hold is what `payment` and `settled` do, and only
+ * `proveSettlement` asks the recipient
  */
-declare function carriesProof<T extends Provable>(report: T): report is Proven<T>;
+declare function agreesWithItself<T extends Provable>(report: T): report is SelfConsistent<T>;
+/**
+ * What `agreesWithItself` was called before 2.2.0
+ *
+ * @deprecated Use `agreesWithItself`, because it proves nothing beyond the report itself
+ */
+declare const carriesProof: typeof agreesWithItself;
 /**
  * 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
@@ -395,9 +536,15 @@ declare function wrapFeeCeiling(amountMsat: number, allowance?: WrapAllowance):
  */
 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 */
+/**
+ * How far the gateway's clock may drift from yours before a webhook is refused,
+ * and the URL you registered when a proxy in front of you hands requests on under
+ * another one. A delivery is signed for the URL it was sent to, so one made for
+ * somebody else's endpoint is refused here
+ */
 type WebhookOptions = {
     toleranceSecs?: number;
+    url?: string;
 };
 /**
  * What checks a delivery: the hex the gateway publishes at `/webhook-key`. There
@@ -427,11 +574,11 @@ interface WebhookHandlers {
      * A settlement that proves itself: it says paid and its preimage hashes to the
      * payment hash it names. This is the only callback a shop needs
      */
-    onSettled?: (settlement: Proven<Settlement>) => void | Promise<void>;
+    onSettled?: (settlement: SelfConsistent<Settlement>) => void | Promise<void>;
     /**
-     * A delivery that carries no proof, so an expiry or a paid claim with no
-     * preimage behind it. Left unset, the handler answers `202` and does nothing,
-     * because acting on an unproven claim is the one thing this refuses to do
+     * A delivery that carries no proof, so an expiry. Left unset, the handler
+     * answers `202` and does nothing, because acting on an unproven claim is the
+     * one thing this refuses to do
      */
     onUnproven?: (settlement: Settlement) => void | Promise<void>;
     /** A whole payment rather than a settlement, which is what an older gateway posts */
@@ -443,14 +590,21 @@ interface WebhookHandlers {
     credential?: WebhookCredential;
     /** How far the gateway's clock may drift from yours, five minutes by default */
     toleranceSecs?: number;
+    /**
+     * The URL you registered, when a proxy in front of you hands the request on
+     * under another host or scheme. Left unset, the request's own URL is what the
+     * delivery has to have been signed for
+     */
+    url?: string;
 }
 /**
  * Everything one gateway lets you mount, in one place so a caller never has to
  * know which handler needs the gateway and which does not. Most of these took it
  * as a config field before, and reaching them through the gateway deleted it.
  *
- * `verify` and `bankVerify` need nothing from the gateway and are here anyway,
- * because a reader looking for a handler should find every handler in one list
+ * `lightningVerify`, `bankVerify` and `nwcVerify` need nothing from the gateway and
+ * are here anyway, because a reader looking for a handler should find every handler
+ * in one list
  */
 declare class Serve {
     private readonly gateway;
@@ -471,13 +625,24 @@ declare class Serve {
      * A verify endpoint of your own that asks the recipient's wallet for you, so
      * the gateway polls you and never the wallet
      */
+    lightningVerify(config: LightningVerifyConfig): Handler;
+    /**
+     * What `lightningVerify` was called before 2.2.0
+     *
+     * @deprecated Use `lightningVerify`, beside `bankVerify` and `nwcVerify`
+     */
     verify(config: LightningVerifyConfig): Handler;
     /** The verify endpoint a bank rail is polled at, answering off your own statement */
     bankVerify(config: BankVerifyConfig): Handler;
+    /**
+     * The verify endpoint an NWC rail is polled at, asking your own wallet over
+     * NIP-47, so the gateway never learns the connection, the relay or the wallet
+     */
+    nwcVerify(config: NwcVerifyConfig): Handler;
     /**
      * The whole webhook route: it answers the gateway's challenge, checks the
      * signature against the key the gateway publishes, refuses a settlement that
-     * proves nothing, and calls you for the one that does.
+     * proves nothing, and calls you once for the one that does.
      *
      * `export const POST = gateway.serve.webhook({ onSettled: fulfil })` is the
      * entire integration
@@ -492,14 +657,8 @@ declare class Serve {
     private credential;
 }
 
-/** How this instance talks to one gateway, and how much of what it says to check */
+/** How this instance talks to one gateway */
 interface ThunderBridgeOptions {
-    /**
-     * Prove every payment against the recipient's own server before handing it
-     * back, and refuse a reported settlement whose preimage does not hash to the
-     * payment hash, defaults to true
-     */
-    verify?: boolean;
     /**
      * Sent as `Authorization: Bearer`, which a gateway started with
      * `GATEWAY_TOKEN` requires on every call, the socket handshake included. No
@@ -521,7 +680,7 @@ interface WaitOptions {
     signal?: AbortSignal;
     /**
      * Mint a short-lived ticket and put that in the socket URL instead of the
-     * payment id. Implied by `token`. The id stays readable inside the ticket,
+     * payment id. Implied by `token` and by `secret`. The id stays readable inside the ticket,
      * what changes is that a URL out of a log stops opening anything after a
      * minute
      */
@@ -584,17 +743,32 @@ interface FollowOptions {
     /**
      * Mint a short-lived ticket and put that in the socket URL instead of the
      * secret, one per connection. Keeps the secret out of access logs, at the cost
-     * of a POST before each connect. Implied by `token`. Leave it off for a
+     * of a POST before each connect. Implied by `token` and by `secret`. Leave it off for a
      * microcontroller, where one hardcoded URL and a dumb reconnect loop is the
      * whole point
      */
     tickets?: boolean;
 }
+/** How this caller holds a socket open and what it answers on it */
+interface AttendOptions {
+    /**
+     * What this caller answers when the gateway asks about one of its payments.
+     * The preimage when the money is there, null while it is not, and the gateway
+     * checks the preimage against the hash either way
+     */
+    answer: (paymentHash: string) => Promise<string | null> | string | null;
+    /** Called when a connection drops or a frame is refused, the socket keeps going */
+    onError?: (error: unknown) => void;
+    /** Reconnect after a drop, defaults to true */
+    reconnect?: boolean;
+    /** The first wait after a drop, doubling and jittered, defaults to 3000 */
+    reconnectDelayMs?: number;
+}
 /** Talks to a Thunder Bridge gateway and trusts it for nothing it can check itself */
 declare class ThunderBridge {
     private readonly baseUrl;
-    private readonly verify;
     private readonly token;
+    private readonly handedOut;
     private readonly secret;
     private strangers;
     private speaks;
@@ -651,7 +825,7 @@ declare class ThunderBridge {
      * for both sorts: `kind` says whether the gateway minted it or was handed it,
      * and the address, amount and invoice are null on one it was never told
      */
-    payment(id: string): Promise<Payment | null>;
+    payment(held: Held): Promise<Payment | null>;
     /**
      * List what this gateway is watching, newest first. Only a gateway started
      * with `GATEWAY_TOKEN` serves this, because on a shared one it would hand
@@ -671,7 +845,7 @@ declare class ThunderBridge {
      * one that has answered is followed until its own expiry, so the wait always
      * ends by itself
      */
-    settled(id: string, options?: WaitOptions): Promise<Payment>;
+    settled(held: Held, options?: WaitOptions): Promise<Payment>;
     private followed;
     /**
      * Wait on several payments and keep the first one that is really paid, then stop
@@ -690,8 +864,12 @@ declare class ThunderBridge {
      * the recipient's own wallet minted it, so a payer who pays the loser afterwards
      * really does pay twice and that shows up on `follow` as a second settlement to
      * refund.
+     *
+     * A leg the gateway is caught lying about before any leg is paid ends the wait
+     * with its `GatewayCheatError`, even when another leg is paid after it, so a
+     * detected cheat is never traded for a later win.
      */
-    firstSettled(ids: string[], options?: WaitOptions): Promise<Payment | null>;
+    firstSettled(held: Held[], options?: WaitOptions): Promise<Payment | null>;
     /**
      * Hand over an invoice you obtained yourself so the gateway watches it without
      * being told the address or the amount. It can then only refuse everyone
@@ -707,6 +885,12 @@ declare class ThunderBridge {
      * because then the gateway names the payment and only it can
      */
     nameFor(paymentHash: string): Promise<string | null>;
+    /**
+     * Hold a socket open and answer what the gateway asks about this caller's own
+     * payments, so a watch addressed to this caller settles without anybody
+     * hosting a URL. Reconnects on its own until the returned function is called
+     */
+    attend(options: AttendOptions): () => void;
     /**
      * Follow every payment made to one trigger, replayed from the recent ones on
      * connect and then live, reconnecting on its own until the returned function
@@ -727,7 +911,148 @@ declare class ThunderBridge {
     private sending;
     private reading;
     private speaking;
+    private handOut;
     private proven;
 }
 
-export { relayedVerifyUrl as A, type BankRailConfig as B, type CreateOptions as C, wrapFeeCeiling as D, type FollowOptions as F, type Handler as H, type Leg as L, type Minted as M, type Order as O, type PaymentRequest as P, type RailConfig as R, type Send as S, ThunderBridge as T, type WaitOptions as W, type Rail as a, type ThunderBridgeOptions as b, type BlindLightningRailConfig as c, type LightningRailConfig as d, type LightningVerifyConfig as e, type PaymentRequestInit as f, type PaymentRequestOptions as g, type Provable as h, type Proven as i, Rails as j, type Range as k, type Relayed as l, Serve as m, type TicketOptions as n, type TriggerConfig as o, type WatchTicketConfig as p, type WebhookCredential as q, type WebhookHandlers as r, type WebhookOptions as s, type WrapAllowance as t, answerVerifyChallenge as u, carriesProof as v, invoiceFrom as w, proveOrigin as x, proveSettlement as y, proveWrapped as z };
+/** One incoming payment as the bank booked it, in the smallest unit of its currency */
+interface Credit {
+    amountMinor: number;
+    currency: string;
+    /** Whatever the payer wrote, wherever this bank puts it. Matching is a whole word, so noise around it is fine */
+    reference: string;
+    /**
+     * Unix seconds. A bank that books a day rather than an instant, as Fio does,
+     * gives the day's midnight in its own zone, so rendering this in UTC can show
+     * the day before. Nothing here matches on it, it is yours to read
+     */
+    bookedAt: number;
+}
+/**
+ * Recent credits on one account, oldest or newest first, it makes no difference.
+ * This is the whole plugin seam: a bank is a function of this shape, and
+ * `fioStatement` is one implementation of it
+ */
+type Statement = (sinceUnix: number) => Promise<Credit[]>;
+/** One transfer to ask for: what is owed, where it lands, and where its arrival is read back from */
+interface BankTransferParams {
+    /**
+     * Long lived and server side, at least 32 characters. The preimage is derived
+     * from it and the verify query is sealed with it, so losing it loses every proof
+     */
+    secret: string;
+    /** What the payer must leave on the transfer, an order id or a nonce. It is matched, not stored */
+    reference: string;
+    /** The price in the smallest unit, so 48055 is 480.55 CZK */
+    amountMinor: number;
+    /** The account the money goes to, as an IBAN */
+    iban: string;
+    /**
+     * Where `bankVerifyEndpoint` is mounted, a public https URL with no query of
+     * its own. Not needed when `answerBy` is "agent", because then nothing is polled
+     */
+    verifyUrl?: string;
+    /**
+     * How the gateway gets its answer. "poll" hands it a URL it fetches, which
+     * needs a public host. "agent" hands it this caller's name instead, and the
+     * socket `bankAgent` holds open answers for it, which needs no host at all
+     */
+    answerBy?: "poll" | "agent";
+    /** When the offer dies, in unix seconds. Money in a bank moves on banking days, so give it days */
+    expiresAt: number;
+    /** Defaults to CZK */
+    currency?: string;
+    /** Up to ten digits, for accounting systems that still want one */
+    variableSymbol?: string;
+    /**
+     * Groups this transfer with everything else paid to the same secret, so one
+     * `followTrigger` socket hears about it. Give the Lightning leg of the same
+     * 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 on that stream, so a watcher learns which order settled without
+     * asking anyone. It is sealed under `secret` for this transfer's payment hash,
+     * so the gateway can neither read it nor move it onto another payment
+     */
+    sealed?: {
+        secret: string;
+        data: unknown;
+    };
+    /**
+     * Where the gateway posts once the money lands, a public https URL. Without one
+     * a transfer is only ever learned by following the trigger or asking
+     */
+    webhookUrl?: string;
+    /**
+     * Register on a gateway you do not own anyway. The sealed verify URL tells its
+     * operator nothing about the order, but the URL itself still answers whether
+     * that order was paid. Say true only when that much is not worth hiding
+     */
+    allowPublicGateway?: boolean;
+}
+/** A transfer the gateway is now watching, and the descriptor the payer scans */
+interface BankTransfer {
+    /** The watched payment's id at the gateway, which is how you read this order back */
+    id: string;
+    /** What the gateway was given, and what the preimage has to hash to */
+    paymentHash: string;
+    /** The same URL you mounted, carrying what to look for and a signature over it */
+    verifyUrl: string;
+    /** The payer scans this, it is a Short Payment Descriptor, the Czech QR platba format */
+    spd: string;
+}
+/** The endpoint the gateway polls for a bank transfer, answering off your own statement */
+interface BankVerifyConfig {
+    /** The same secret `bankTransfer` was given */
+    secret: string;
+    /** The IBAN this endpoint answers for, refusing a question sealed for another account */
+    iban: string;
+    /** The account to read */
+    statement: Statement;
+    /** How far back a credit still counts, seven days by default */
+    lookBackSecs?: number;
+    /**
+     * How often you want the gateway to ask, in seconds. It goes out as
+     * `Cache-Control: max-age`, so the pace is yours to set rather than the
+     * gateway's, and a bank that updates once a minute should say so instead of
+     * being polled every few seconds. Thirty by default, clamped to an hour
+     */
+    pollEverySecs?: number;
+}
+/** One order this caller is waiting on, and the account it is waiting on it in */
+interface BankOrder {
+    iban: string;
+    reference: string;
+    amountMinor: number;
+    currency?: string;
+    expiresAt: number;
+    statement: Statement;
+}
+/** What a caller needs to answer for its own transfers over a socket */
+interface BankAgentConfig {
+    /** The gateway holding the watches this caller raised */
+    gateway: ThunderBridge;
+    /** The same secret `bankTransfer` was given, never leaving this device */
+    secret: string;
+    /** What the payment the gateway is asking about was asking for, or null when it is none of ours */
+    orders: (paymentHash: string) => Promise<BankOrder | null> | BankOrder | null;
+    /** How far back a credit still counts, seven days by default */
+    lookBackSecs?: number;
+    /** Called when a connection drops or a frame is refused, the socket keeps going */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Answer the gateway over a socket this device opens, so a transfer addressed to
+ * this caller settles from a till behind NAT, a browser tab or a phone. The
+ * preimage is derived here from the secret, so the gateway is told only that one
+ * exists and can check it against the hash it already holds.
+ *
+ * Call the returned function to stop attending. Whatever is still open is asked
+ * again on the gateway's own schedule, so leaving and coming back loses nothing
+ */
+declare function bankAgent(config: BankAgentConfig): () => void;
+
+export { type WebhookOptions as $, type AttendOptions as A, type BankAgentConfig as B, type Credit as C, type Proven as D, type RailConfig as E, type FollowOptions as F, Rails as G, type Handler as H, type Range as I, type Relayed as J, type SelfConsistent as K, type Leg as L, type Minted as M, type NwcConnection as N, type Order as O, type PaymentRequest as P, type Send as Q, type Rail as R, type Statement as S, ThunderBridge as T, Serve as U, type TicketOptions as V, type WaitOptions as W, type TriggerConfig as X, type WatchTicketConfig as Y, type WebhookCredential as Z, type WebhookHandlers as _, type BankOrder as a, type WrapAllowance as a0, agreesWithItself as a1, answerVerifyChallenge as a2, carriesProof as a3, invoiceFrom as a4, proveOrigin as a5, proveSettlement as a6, proveWrapped as a7, relayedVerifyUrl as a8, wrapFeeCeiling as a9, type BankTransfer as b, type BankTransferParams as c, type BankVerifyConfig as d, bankAgent as e, nwcVerifyEndpoint as f, type NwcInvoice as g, type NwcRailConfig as h, type NwcVerifyConfig as i, askWallet as j, nwcConnection as k, nwcHoldInvoice as l, nwcInvoice as m, nwcRail as n, nwcPay as o, nwcSettlement as p, nwcVerifyUrl as q, type ThunderBridgeOptions as r, type BankRailConfig as s, type BlindLightningRailConfig as t, type CreateOptions as u, type LightningRailConfig as v, type LightningVerifyConfig as w, type PaymentRequestInit as x, type PaymentRequestOptions as y, type Provable as z };