/** * The payer's own recourse for a bridge payment (v3 §26.8 step 7). * * A bridge facilitator holds the payer's whole amount from the commit until * the merchant is paid or the coins come back, and §26.6 relies on that same * facilitator to notice when they should come back: no relayer signed, the * merchant never used the authorization, a relayer recorded a payout it never * made. A facilitator that does not act would keep the money. So for every * bridge payment not confirmed delivered the wallet keeps a **dispute * intent** beside the receipt -- the payment's preimage and a schedule -- and * pursues it itself, between calls, with nothing but that preimage: * * ```text * at settleAt + LEASE_TTL + 2·RECORD_GRACE (when any record is disputable) * POST {facilitator}/bridge/lookup { contract_terms } * "paid" -> closed: the merchant was paid * "refunded" -> closed: the coins' value is back (a refunded receipt is appended) * otherwise, or no answer: * POST {issuer}/disputes { contract_terms } (no payto_sig, §26.7) * 200 revoked -> the relayer's record is revoked; the cancel refund follows * PAYOUT_OBSERVED -> closed: the nonce paid the merchant * PAYMENT_UNKNOWN -> closed: nothing was committed (a refunded receipt is appended) * PAYOUT_NOT_RECORDED -> POST {registry}/bridge/cancel-request { contract_terms_hash }: * §20.2's fallback clock starts; ask again after PAYOUT_DEADLINE * DISPUTE_TOO_EARLY -> ask again at not_before * DISPUTE_NEEDS_OPERATOR -> ask again after PAYOUT_DEADLINE * DISPUTE_WINDOW_CLOSED -> closed: a record stands; nothing more to dispute * anything else -> ask again later * ``` * * `settleAt + LEASE_TTL + 2·RECORD_GRACE` is the first moment the issuer can * decide a dispute of any record the payment could have: a relayer leased by * `settleAt + LEASE_TTL` records by `leaseUntil + RECORD_GRACE`, and its * record is disputable `RECORD_GRACE` after that. * * Every request is idempotent at its service -- the lookup is a read, the * issuer answers a repeated dispute from the outcome it persisted, and the * registry anchors the fallback clock at the **first** cancel request -- so a * round that is repeated after a crash costs a request and changes nothing. * The schedule lives in the receipt file (`receipts.ts`), so it survives a * restart. * * # What it shows, and to whom * * Only a payment that went wrong is ever pursued, and each request carries * its preimage -- `payTo` included -- from the wallet's network address: to * the bridge facilitator, which already holds it; to the issuer, which also * sees that address at withdrawals; to the registry. Route the issuer * client's `fetch` and the wallet's `bridgeFetch` through a proxy you control. */ import { type BridgeLookup } from "./bridge.js"; import type { ServiceAnswer } from "./client.js"; import { type BridgeRecourse, type RecourseOutcome, type RecourseStage } from "./receipts.js"; import { type ContractTerms } from "./terms.js"; /** The protocol windows a recourse is timed by, in seconds. */ export interface RecourseTiming { /** `LEASE_TTL`: how long a relayer's lease runs. */ readonly leaseTtlSeconds: number; /** `RECORD_GRACE`: how long after its lease a relayer may record, and after a record a dispute waits. */ readonly recordGraceSeconds: number; /** `PAYOUT_DEADLINE`: the dispute window, and the cancel fallback's wait. */ readonly payoutDeadlineSeconds: number; } /** The launch values: `LEASE_TTL` 60, `RECORD_GRACE` 3600, `PAYOUT_DEADLINE` 86400. */ export declare const DEFAULT_RECOURSE_TIMING: RecourseTiming; /** * The least a round waits before the next, whatever a service said: a * `not_before` already past must not turn `pursueBridgeRecourse` into a loop. */ export declare const MIN_RECOURSE_RETRY_SECONDS = 60; /** The three services a round asks, each bound to its payment's facilitator or the wallet's issuer. */ export interface RecoursePorts { /** `POST {facilitator}/bridge/lookup { contract_terms }`. */ lookup(terms: ContractTerms): Promise; /** `POST {issuer}/disputes { contract_terms }`. */ dispute(terms: ContractTerms): Promise; /** `POST {registry}/bridge/cancel-request { contract_terms_hash }` -- the registry never learns a preimage. */ cancel(terms: ContractTerms): Promise; } /** When a recourse's next round is due, unix seconds. */ export declare function recourseDueAt(recourse: BridgeRecourse, timing: RecourseTiming): number; /** * One round of a due recourse: what the services say now, and the recourse * that follows from it. Never throws for a service's failure -- a request * that fails is an `"unavailable"` round, asked again later. */ export declare function recourseRound(recourse: BridgeRecourse, now: number, timing: RecourseTiming, ports: RecoursePorts): Promise; /** One round {@link Wallet.pursueBridgeRecourse} ran. */ export interface RecourseStepReport { /** The receipt's sequence number. */ readonly seq: number; readonly stage: RecourseStage; readonly outcome: RecourseOutcome | undefined; /** When the next round is due; absent once closed. */ readonly nextAt: number | undefined; } /** What one call of {@link Wallet.pursueBridgeRecourse} did. */ export interface BridgeRecourseReport { /** The rounds this call ran: one per bridge payment whose recourse was due. */ readonly pursued: readonly RecourseStepReport[]; /** Bridge payments whose recourse is still open after this call. */ readonly open: number; /** When the earliest of them is due, unix seconds; `null` with none open. */ readonly nextAt: number | null; }