@arkade-os/swap 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,1747 @@
+import { asset, IWallet, arkade, RestIndexerProvider, Transaction, IContractManager, RestArkProvider, VHTLC, Identity } from '@arkade-os/sdk';
+import { A as AssetSwapRepository, a as AssetSwap, M as MarketsCacheEntry, R as RfqStatus, b as RfqTransport, O as OnchainHtlc, C as ChainSource, c as ChainUtxo, d as OnchainHtlcPhase } from './rfq-CRgIOQ_y.cjs';
+export { e as ARKADE_ASSET, f as ARKADE_BTC, g as AddressMismatch, h as AssetSwapFallbackSecrets, i as AssetSwapStatus, B as BTC_ASSET_ID, D as DerivedSwapSecrets, j as DeterministicSigner, H as HtlcUtxo, I as InMemoryAssetSwapRepository, k as InvoiceFacts, L as LIGHTNING_BTC, l as LIGHTNING_RECEIVE_PAIR, m as LIGHTNING_SEND_PAIR, n as MAX_MIN_CONFIRMATIONS, o as MIN_CLAIM_WINDOW_SECONDS, p as MIN_HEADROOM_SECONDS, q as ONCHAIN_BTC, r as ONCHAIN_CLAIM_MARGIN_SECONDS, s as ONCHAIN_DUST_SATS, t as ONCHAIN_ORDER_MARGIN_SECONDS, u as ONCHAIN_RECEIVE_PAIR, v as ONCHAIN_SECONDS_PER_BLOCK, w as ONCHAIN_SEND_PAIR, x as OnchainHtlcParams, y as OnchainNetwork, z as RFQ_PREIMAGE_TAG, E as RFQ_TERMINAL_STATES, F as RefundBlockedReason, G as RefundNotLocallyPossibleError, J as RelaySocket, K as RfqQuote, N as RfqRefusalReason, S as StoredSwapSecrets, P as SwapRefusal, Q as SwapSecrets, T as addAssetSwap, U as adoptSwapDescriptor, V as arkadeSwapRequest, W as assertFundable, X as assertReceivable, Y as awaitOnchainFill, Z as buildHtlcClaim, _ as buildHtlcRefund, $ as buildPreimageMessage, a0 as claimOnchainFill, a1 as classifyOnchainHtlc, a2 as deriveLightningReceive, a3 as deriveOnchainReceive, a4 as deriveOnchainSend, a5 as derivePreimage, a6 as deriveSwapSecrets, a7 as extractPreimage, a8 as getAssetSwaps, a9 as getAssetSwapsOrThrow, aa as httpTransport, ab as isDeterministicSigner, ac as lightningReceiveRequest, ad as lightningSendRequest, ae as lightningSendVtxoScript, af as newPreimage, ag as newRfqId, ah as offerTermsFromQuote, ai as onchainHtlcScript, aj as onchainReceiveRequest, ak as onchainSendRequest, al as paymentHashOf, am as preimageForRfqSecrets, an as randomSwapSecrets, ao as receiveVtxoScript, ap as relayTransport, aq as requestLightningReceive, ar as requestLightningSend, as as requestOnchainReceive, at as requestOnchainSend, au as rfqPair, av as rfqSecretsOfRecord, aw as rfqSecretsToRecord, ax as senderIdentityForRfqSecrets, ay as senderIdentityForSwapRecord, az as senderPubkeyForRfqSecrets, aA as unilateralClaimDelay, aB as unilateralRefundDelay, aC as unilateralRefundWithoutReceiverDelay, aD as updateAssetSwap, aE as updateAssetSwapBestEffort, aF as verifyLockupAddress, aG as verifyReceiveInvoice } from './rfq-CRgIOQ_y.cjs';
+import { Network, LocalCardInput, DiscoveredMarket, Side, OfferPlan } from '@arkade-os/solver-discovery';
+
+/** The contracts — pure data, shared verbatim with any other implementation. */
+declare const swapPrograms: Record<"wantAsset" | "wantBtc", ReturnType<typeof arkade.parseArtifact>>;
+/** A full-fill offer. Exactly one field names an asset: `wantAsset` set = the
+ * fill must deliver that asset (the deposit may be BTC or another asset,
+ * identified by the funding vtxo itself); `offerAsset` set = the user
+ * deposits that asset and wants sats. */
+interface Offer {
+    /** The scriptPubKey of the swap contract. */
+    swapPkScript: Uint8Array;
+    /** Amount the user wants (asset units, or sats when wanting BTC). */
+    wantAmount: bigint;
+    /** The asset the user wants. Omitted when wanting BTC. */
+    wantAsset?: asset.AssetId;
+    /** The asset the user deposits. Omitted when depositing BTC. */
+    offerAsset?: asset.AssetId;
+    /** Maker's taproot scriptPubKey (34 bytes) — where the fill must pay. */
+    makerPkScript: Uint8Array;
+    /** Maker's x-only key (32 bytes) — the cancel path's `user` signer. */
+    makerPublicKey: Uint8Array;
+    /** Covenant co-signer (emulator) x-only key (32 bytes). */
+    emulatorPubkey: Uint8Array;
+}
+/** Compile the offer's contract: program + args -> taproot tree. */
+declare function offerVtxoScript(offer: Omit<Offer, "swapPkScript">, serverPubkey: Uint8Array): InstanceType<typeof arkade.ArkadeProgramScript>;
+/** Extension packet type tag for Arkade Intents offers. */
+declare const OFFER_PACKET_TYPE = 3;
+/** Serialize an offer to TLV bytes (the packet payload). */
+declare function encodeOffer(offer: Offer): Uint8Array;
+/** Parse TLV bytes into an offer. Throws on malformed or unknown records. */
+declare function decodeOffer(data: Uint8Array): Offer;
+/**
+ * Build a new offer for `wallet` (the user). Fund `address` with the side
+ * you deposit, embedding the returned extension, and the solver does the rest:
+ *
+ *   // BTC -> asset
+ *   const o = await createOffer(wallet, ARK, EMULATOR_PUBKEY, { wantAmount: 1000n, wantAsset })
+ *   await wallet.send({ address: o.address, amount: 1000, extensions: [o.extension] })
+ *
+ *   // asset -> BTC (the sats are the VTXO carrier for the asset)
+ *   const o = await createOffer(wallet, ARK, EMULATOR_PUBKEY, { wantAmount: 1000n, offerAsset })
+ *   await wallet.send({ address: o.address, amount: 500,
+ *                       assets: [{ assetId, amount: 1000n }],
+ *                       extensions: [o.extension] })
+ *
+ * Broadcasts nothing, but does write locally: the covenant is registered with
+ * the wallet's contract manager before the address is returned, so the deposit
+ * is watched from the moment it lands and is marked as escrow (see
+ * {@link registerOfferContract}). Registration deliberately happens *before*
+ * funding rather than after: nothing is at stake yet, so a failure can throw
+ * and be retried, where the same failure after `wallet.send` would leave a
+ * funded deposit unwatched with no way to notice.
+ */
+declare function createOffer(wallet: IWallet, arkServerUrl: string, 
+/** Covenant co-signer (emulator) x-only key — the SOLVER's deployment,
+ * not the user's. This library does NOT fetch or verify it: clients
+ * have no network path to the emulator, only the solver and covclaimd
+ * do. The caller must obtain this out-of-band, before calling this
+ * function, from the solver's signed registry/corridor card (its
+ * `emulator_pubkey`, added in arkade-os/solver-registry#18) or an
+ * equivalent source it
+ * independently trusts, and is responsible for having checked it
+ * against that trusted value itself. */
+emulatorPubkey: Uint8Array, params: {
+    wantAmount: bigint;
+    wantAsset?: asset.AssetId;
+    offerAsset?: asset.AssetId;
+}): Promise<{
+    /** The encoded offer, hex. **Persist this** — it is the only input
+     * `cancelOffer` needs to rebuild the covenant, and the restore scan reads
+     * the same bytes back off the funding tx into `AssetSwap.offerHex`. */
+    offerHex: string;
+    /** Ready for `wallet.send`'s `extensions` — the caller never handles the packet type. */
+    extension: {
+        type: number;
+        payload: Uint8Array;
+    };
+    /** The swap address to fund. Nothing exists on chain until the deposit
+     * lands here: `createOffer` is pure derivation and broadcasts nothing.
+     * Identical offers derive an identical address, so the funding txid — not
+     * the address — is what identifies one deposit. */
+    address: string;
+    /** The covenant's scriptPubKey: the key an indexer watches to spot the
+     * deposit and its later spend (`AssetSwap.swapPkScript`). */
+    swapPkScript: Uint8Array;
+}>;
+/**
+ * Cancel an offer: spend the swap VTXO back to the user. Returns the ark txid.
+ *
+ * This is the refund path — how a user takes back a deposit no solver filled.
+ * **Neither program carries a timelock**, so an unfilled deposit keeps its
+ * place at the swap address rather than expiring: no deadline to miss and no
+ * "expired" state to unwind, at the cost of the refund being something the
+ * user asks for rather than something a clock delivers.
+ *
+ * Both paths out of the covenant are deliberately asymmetric:
+ *   - `fulfill` is signed by the **server alone**, but the covenant constrains
+ *     it to pay output 0 to `makerWP` for at least `wantAmount` — a solver
+ *     cannot take the deposit without delivering.
+ *   - `cancel` is a **2-of-2 of the user and the server**, so cancelling is
+ *     cooperative: the server co-signs. No solver signature is involved, so the
+ *     refund never depends on the counterparty being reachable.
+ *
+ * Cancel therefore races a fill rather than pre-empting it. An offer the solver
+ * is filling in the same moment may be spent by `fulfill` first, in which case
+ * this throws "no spendable VTXO at the swap address" — which means the swap
+ * completed, not that anything failed. `restoreAssetSwaps` classifies the two
+ * spends apart afterwards by the leaf each took (see `classifySpend`).
+ *
+ * Marking the deposit as escrow (see {@link registerOfferContract}) does not
+ * close this path: the gate's subject is *implicit* coin selection, and cancel
+ * names its input outpoint explicitly. The user keeps the only spend route
+ * that was ever theirs to take.
+ *
+ * Identical offers derive the same address, so `fundingTxid` selects the exact
+ * deposit; without it the address must hold exactly one spendable VTXO — with
+ * several, cancel refuses to guess and throws.
+ * `swapAddress` (the funded address) pins the server key the covenant was
+ * built with, so cancel keeps working across a server signer rotation; without
+ * it a rotated key is detected and reported rather than reading as a missing
+ * VTXO.
+ *
+ * **When the matching swap record is present, this records its own outcome,
+ * and that is what makes the live watcher cheap.** `cancel` is a 2-of-2 of
+ * user and server, so a cancel can only be the user's own act: on a
+ * successful submit this *is* the authoritative answer, and writing it here
+ * means `watchOfferSwaps` has nothing left to decide for our own cancels — it
+ * sees a terminal record and leaves it alone. The status moves to `cancelling`
+ * first so a crash between submit and record leaves a marker rather than a
+ * swap that still looks pending.
+ *
+ * Passing a repository that does not contain the swap record is allowed: the
+ * cancel still submits and returns its txid, but no local status is written,
+ * so the watcher or restore scan must classify the spend later.
+ *
+ * When a local record exists, the txid is only knowable after `send()`
+ * returns, so a spend event that arrives in that window finds a `cancelling`
+ * record and classifies the spend by its covenant leaf instead — the same
+ * answer, one indexer read more.
+ */
+declare function cancelOffer(wallet: IWallet, arkServerUrl: string, offerHex: string, opts: {
+    repository: AssetSwapRepository;
+    fundingTxid?: string;
+    swapAddress?: string;
+}): Promise<string>;
+
+/**
+ * Quoting: solver discovery and the pricing guardrails around a plan.
+ *
+ * The user side of a swap — the layer that works out what one would cost
+ * before `offer` commits to it. This is request-for-quote like every other
+ * Arkade Intents corridor; what is specific here is that the quote resolves
+ * client-side, from the market card the solver publishes (its price feed and
+ * its fee) rather than over a relay roundtrip. The card commits a solver to a
+ * price; only a fill commits it to this swap, so nothing here is signed and no
+ * inventory is reserved.
+ *
+ * Relay-negotiated quotes are where every corridor converges, this one
+ * included. What stays specific to intra-Arkade is the settlement covenant,
+ * not the negotiation. See the README's Roles section for why this package
+ * says user and solver rather than maker and taker.
+ */
+
+/** Shared quote options so every quote path agrees.
+ * No safety margin on top of the market fee: pricing drift between quote
+ * and fill is the solver's risk to manage, not the user's to prepay. */
+declare const QUOTE_OPTIONS: {
+    readonly safetyBps: 0;
+};
+/** Feed fetcher with a short per-URL TTL cache. A quote UI refetches the
+ * market's price feed on every debounced keystroke, and public feeds
+ * (CoinGecko) rate-limit that burst hard enough that big amounts reliably die
+ * as "Quote unavailable" mid-typing — one feed value per TTL window is fresh
+ * enough for a preview whose rate is re-checked at fill anyway.
+ * ponytail: no stale-serve when the fetch itself fails; add one if feeds
+ * flake beyond the TTL window (cap the staleness — the feed value becomes
+ * the covenant floor, so an old price must never price a real offer).
+ * Keyed on the request URL, so it assumes a market's feed URL is stable and
+ * amount-invariant (true today); a cache-busting nonce would silently make it
+ * a no-op — the flat-feedCalls swap test guards against that regressing. */
+declare const makeCachedFeedFetch: (ttlMs?: number, fetchImpl?: typeof fetch) => typeof fetch;
+interface DiscoverMarketsOptions {
+    network: Network;
+    /** The network's solver registry index URL; no registry means no markets. */
+    registryUrl: string | undefined;
+    /** Backs the 1-hour markets cache and its stale fallback. Omit for a
+     * one-shot discovery that always hits the registry. */
+    repository?: AssetSwapRepository;
+    /** Locally pinned solver cards to merge with the registry's markets. */
+    localCards?: LocalCardInput[];
+    /** Receives discovery warnings (stale index, skipped cards, …). */
+    logger?: (...args: unknown[]) => void;
+    /** Custom fetch (tests, mobile runtimes). Defaults to global fetch.
+     * ponytail: no request deadline here — a caller that needs one wraps its
+     * own fetchImpl with an AbortSignal; add one if a hung registry ever
+     * strands discovery in practice. */
+    fetchImpl?: typeof fetch;
+    /** `false` forces a refetch past a fresh cache (a user-triggered reload).
+     * It does not disable the stale-cache fallback: an unreachable registry
+     * still serves the last known markets rather than none. */
+    useCache?: boolean;
+}
+/**
+ * Markets from the network's solver registry; [] when none is configured.
+ * Registry content changes rarely, so results are cached for an hour and a
+ * stale cache backstops an unreachable registry (quotes stay live either way).
+ */
+declare const discoverMarkets: (options: DiscoverMarketsOptions) => Promise<DiscoveredMarket[]>;
+/** Best market for a from/to pair, in either orientation. `give` is the side
+ * the sender deposits; `wantSide` skips markets whose receive side is
+ * disabled (max = "0"). */
+declare const findMarket: (markets: DiscoveredMarket[], fromId: string, toId: string) => {
+    market: DiscoveredMarket | null;
+    give: Side;
+} | undefined;
+type PlanError = "insufficient-balance" | "side-disabled" | "below-min" | "above-max" | "below-dust";
+/** Validate a plan against the user's balance and the server dust limit. */
+declare const validatePlan: (plan: OfferPlan, giveBalance: bigint, dust: bigint) => PlanError | undefined;
+
+/** Browser backend over the SDK's shared IndexedDB manager — the same
+ * infrastructure the wallet already uses for its Boltz swap repository. */
+declare class IndexedDbAssetSwapRepository implements AssetSwapRepository {
+    private readonly dbName;
+    readonly version: 1;
+    private dbPromise;
+    constructor(dbName?: string);
+    private ensureDb;
+    private readStore;
+    /** Every write in one place, so none of them can forget to await the
+     * commit. Requests need no individual await: a failed one aborts the
+     * transaction, which `txDone` reports. */
+    private write;
+    saveSwap(swap: AssetSwap): Promise<void>;
+    getAllSwaps(): Promise<AssetSwap[]>;
+    getScannedTxids(): Promise<Set<string>>;
+    markTxidsScanned(txids: Iterable<string>): Promise<void>;
+    getCachedMarkets(network: string, registry: string): Promise<MarketsCacheEntry | undefined>;
+    saveCachedMarkets(network: string, registry: string, entry: MarketsCacheEntry): Promise<void>;
+    /** All stores in one transaction: clearing swaps but keeping scanned txids
+     * would leave the restore scan permanently skipping those funding txs, so
+     * a partial clear must not be observable. */
+    clear(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+
+/**
+ * The subset of a wallet transaction record the swap scan reads.
+ *
+ * No `assets`: a spend is classified from the covenant leaf it took, read off
+ * the spending transaction itself (see {@link classifySpend}). A wallet
+ * record's asset field is a net delta — an asset offer's cancel moves the asset
+ * out and back, netting to nothing — so it cannot answer the question.
+ */
+interface Tx {
+    type: string;
+    /** The virtual (ark) txid; the funding tx's identity. */
+    redeemTxid: string;
+    boardingTxid?: string;
+    roundTxid?: string;
+    /** Unix seconds. */
+    createdAt?: number;
+}
+/** The indexer surface the restore scan needs — narrower than a full provider. */
+type RestoreIndexer = Pick<RestIndexerProvider, "getVirtualTxs" | "getVtxos">;
+/**
+ * What became of a deposit, as the spending transaction reports it.
+ *
+ * `indeterminate` is not a third outcome — it is the absence of one, and the
+ * caller decides whether to retry or accept a default.
+ */
+type SpendKind = "cancelled" | "fulfilled" | "indeterminate";
+/**
+ * Classify a spend by the covenant leaf it took.
+ *
+ * The covenant's whole vocabulary is two leaves: `cancel` returns the deposit
+ * to the user, `fulfill` is the solver paying for it. A submitted ark tx keeps
+ * each input's `tapLeafScript`, so the spend *states* which one it used — this
+ * reads an answer rather than inferring one.
+ *
+ * **Hand it the transaction that actually spends the deposit outpoint, which is
+ * the checkpoint, not the ark tx.** A spend is two linked transactions: the
+ * checkpoint (`vtxo.spentBy`) takes the deposit outpoint and carries the
+ * covenant leaf, and the ark tx (`vtxo.arkTxId`) spends the checkpoint's output
+ * — carrying the same leaf, but over an outpoint that is not the deposit's. A
+ * caller that offers only the ark tx gets `indeterminate` for every real spend,
+ * which is exactly what the first version of this function did.
+ * {@link classifyDepositSpend} takes both and picks whichever answers.
+ *
+ * What it replaces, and why: the previous test asked what the transaction
+ * moved. That works only while the deposit is invisible to the wallet. Once the
+ * covenant is a registered contract the deposit joins the wallet's own coins,
+ * every wallet-level asset figure becomes a *net* delta, and an asset offer's
+ * cancel — asset out of the covenant, same asset back to the user — nets to
+ * zero and reads exactly like its fill. Leaves do not have that failure mode,
+ * and they also survive batching: a solver filling several offers in one tx
+ * gives each input its own leaf.
+ *
+ * `serverPubkey` must be the key the covenant was *funded* against. If it has
+ * rotated since, the rebuilt script will not match the offer's own
+ * `swapPkScript` and this returns `indeterminate` rather than guessing —
+ * `cancelOffer` diagnoses the same mismatch the same way.
+ */
+declare function classifySpend(offer: Offer, serverPubkey: Uint8Array, spendTx: Transaction, deposit: {
+    txid: string;
+    vout: number;
+}): SpendKind;
+/**
+ * The txids that may hold a deposit's spend, in the order worth trying: the
+ * checkpoint first, since it is the one carrying the deposit outpoint.
+ */
+declare const spendTxidsOf: (vtxo: {
+    spentBy?: string;
+    arkTxId?: string;
+}) => string[];
+/**
+ * Classify a deposit's spend across both halves of it.
+ *
+ * A caller holds two txids for one spend — `spentBy` (the checkpoint, which
+ * takes the deposit outpoint) and `arkTxId` (the ark tx built on it) — and
+ * cannot tell from the outside which shape a given deployment produced: for a
+ * settlement they may be the same id. Try each and take the first definite
+ * answer, so the classification does not depend on that distinction.
+ */
+declare function classifyDepositSpend(offer: Offer, serverPubkey: Uint8Array, spendTxs: Iterable<Transaction>, deposit: {
+    txid: string;
+    vout: number;
+}): SpendKind;
+/**
+ * Scan the given candidates for offer packets and rebuild the AssetSwap
+ * records the store lost. Returns the rebuilt swaps plus the txids that got
+ * an authoritative answer (fetched fine, vtxo lookup fine) — the caller
+ * persists those so they are never fetched again.
+ *
+ * ## A spent deposit is classified or left alone — never guessed
+ *
+ * Whether a spent deposit was filled or cancelled is read from the spending
+ * transaction's covenant leaf ({@link classifySpend}), fetched from the same
+ * indexer as everything else rather than from the `txs` you pass. A spend that
+ * cannot be classified — not fetchable yet, or gone by neither leaf — leaves
+ * the funding txid unanswered, so nothing is persisted and a later scan decides
+ * it. Nothing sticky is written on a guess.
+ *
+ * That is a deliberate reversal: this used to restore an unclassifiable spend
+ * as `fulfilled`, which a persisted record then made permanent, because the
+ * spending tx came from the caller's possibly-lagging history. It no longer
+ * does, so the `existingIds` escape hatch is no longer a correction mechanism
+ * for a wrong label — it is only a skip list.
+ *
+ * `serverPubkey` must be the server key the covenants were funded against; a
+ * key that has rotated since makes every affected swap unclassifiable rather
+ * than misclassified.
+ */
+declare function restoreAssetSwaps(indexer: RestoreIndexer, txs: Tx[], existingIds: ReadonlySet<string>, opts: {
+    serverPubkey: Uint8Array;
+    scanned?: ReadonlySet<string>;
+}): Promise<{
+    restored: AssetSwap[];
+    scannedTxids: string[];
+}>;
+
+/**
+ * The record change a classified spend implies, or `undefined` when it implies
+ * none — an already-resolved swap, or a spend nobody could classify.
+ *
+ * Pure, so a consumer with its own store can apply the same transition without
+ * taking the watcher, and so re-delivery of an event is a no-op rather than a
+ * rewrite.
+ */
+declare function spendUpdate(swap: AssetSwap, spend: {
+    txid: string;
+    kind: SpendKind;
+    at?: number;
+}): Partial<Omit<AssetSwap, "id">> | undefined;
+/** A running watcher. `idle()` exists because the writes are async: shutdown
+ * and tests both need to know when in-flight updates have settled. */
+interface OfferSwapWatcher {
+    stop(): void;
+    idle(): Promise<void>;
+}
+interface WatchOfferSwapsParams {
+    wallet: IWallet;
+    /** Same URL `createOffer`/`cancelOffer` take; used to read a spending tx
+     * when the exact classifier cannot answer. */
+    arkServerUrl: string;
+    repository: AssetSwapRepository;
+    /** Called after a change is persisted. A notification, not a store. */
+    onUpdate?: (swap: AssetSwap) => void;
+}
+/**
+ * Subscribe to the wallet's contract events and drive offer swap status.
+ *
+ * Registration ({@link createOffer}) is what makes this possible: only a
+ * registered covenant is watched, so only registered offers produce events.
+ * Offers funded before registration existed stay on the restore scan.
+ *
+ * This depends on the wallet's contract event transport. In Node, callers must
+ * provide an `EventSource` implementation or use a runtime where it is enabled;
+ * otherwise live updates do not arrive and restore remains the fallback.
+ */
+declare function watchOfferSwaps({ wallet, arkServerUrl, repository, onUpdate, }: WatchOfferSwapsParams): Promise<OfferSwapWatcher>;
+
+/**
+ * Coverage: whether an offer's script is in the wallet's watched set.
+ *
+ * Both edges live here because they are one decision seen from two sides.
+ * `createOffer` promotes a script the moment it hands the user an address to
+ * fund ({@link promoteOfferContract}); the watcher and the restore consumer
+ * retire it once nothing at that script holds funds any more
+ * ({@link retireSettledOfferContracts}). Identical offers derive one script, so
+ * those two can name the same row — and a demotion that lands after a promotion
+ * recreates exactly the failure the promotion exists to prevent: an address the
+ * user was told to fund, out of the subscription, the poll and every sync.
+ *
+ * Two things keep them apart:
+ *
+ * - **Per-script serialization.** `setContractWatchState` is a read-modify-write
+ *   over the contract row, so promotion and demotion are ordered here rather
+ *   than left to interleave inside the manager.
+ * - **The issuance mark.** A swap record is keyed by its funding txid, so an
+ *   offer that has been created but not yet funded has no record at all — it is
+ *   invisible to a liveness check over records, for as long as the user takes
+ *   to send. {@link promoteOfferContract} therefore records the issuance
+ *   itself, and a script with an address still waiting for its deposit is never
+ *   retired.
+ *
+ * The mark is per process: a second wallet context (another tab, a service
+ * worker) issuing an offer while this one retires the same script is not
+ * covered, and neither is an address issued before a restart and funded after
+ * it. Both leave a funded-but-unwatched row that the restore scan still finds —
+ * the same backstop every other best-effort step here relies on.
+ */
+
+/** The one contract-manager capability changing coverage needs. */
+type OfferContractRetirer = Pick<IContractManager, "setContractWatchState">;
+/**
+ * Retire every offer script in `swaps` that no live record still holds — the
+ * batch form of what the watcher does per spend event, for a consumer that
+ * applies {@link restoreAssetSwaps} results without running the watcher.
+ *
+ * Takes the caller's full record list: liveness is a property of all records at
+ * a script, so a partial list would retire a script another record still holds.
+ */
+declare function retireSettledOfferContracts(manager: OfferContractRetirer, swaps: AssetSwap[]): Promise<void>;
+
+interface SealedClaimPacket {
+    /** `ephPub(33) ‖ nonce(12) ‖ ciphertext`, base64 — wire-ready. This is
+     * the whole packet: the RFQ request's `claim_packet` field carries
+     * exactly this string. */
+    ciphertext: string;
+}
+interface ClaimPacketInput {
+    preimage: Uint8Array;
+    /** covclaimd's public key, 33-byte compressed (from its /v1 info). */
+    covclaimdPubkey: Uint8Array;
+}
+/**
+ * Seal a preimage to covclaimd. WebCrypto AES-GCM, hence async.
+ *
+ * The ephemeral key and nonce are generated here and CANNOT be supplied by a
+ * caller. That is the point of this signature: AES-GCM under a repeated
+ * (key, nonce) pair is a total break — forgery and plaintext recovery, not a
+ * degradation — so an optional `nonce` on a production export is a loaded gun
+ * whatever the doc comment says. Deterministic sealing lives in the test
+ * helper, where no consumer reaches it by accident.
+ */
+declare function sealClaimPacket(input: ClaimPacketInput): Promise<SealedClaimPacket>;
+
+/** True for the states after which the solver will report nothing further. */
+declare const isRfqTerminal: (state: string) => boolean;
+/**
+ * The terminal states that mean the swap is OVER and the lockup is already
+ * gone — the solver either claimed it (`settled`, revealing the preimage) or
+ * returned it (`refunded`). A trader seeing one of these has nothing left to
+ * do.
+ *
+ * Deliberately narrower than {@link RFQ_TERMINAL_STATES}: `refused`, `expired`
+ * and `stuck` are terminal for the NEGOTIATION but say nothing about whether
+ * the trader's sats are still sitting at the lockup. A trader that funded just
+ * as the quote expired, or whose solver wedged mid-payment, is exactly the
+ * trader who needs the refund most — so those states must not short-circuit
+ * it. {@link refundIfUnresolved} treats them as "keep going", and lets the
+ * on-chain VTXO lookup be the authority on whether anything is actually there.
+ */
+declare const RFQ_RESOLVED_STATES: readonly ["settled", "refunded"];
+/**
+ * Poll a swap's status until it reaches a terminal state.
+ *
+ * Same shape and conventions as {@link awaitOnchainFill}: a `pollMs` interval,
+ * an optional unix-seconds `deadline`, and a thrown error carrying a stable
+ * `reason` when that deadline passes.
+ *
+ * A `null` status (the solver has no record of this `rfq_id`) is treated as
+ * "not yet", not as an answer — a status route can legitimately 404 for a
+ * moment after a quote is issued. The deadline is what bounds that wait.
+ *
+ * Transport errors are NOT swallowed; a failing `status()` call rejects this
+ * function. Callers polling across a long refund window should expect to
+ * restart it after a network blip — nothing is lost by doing so, since the
+ * refund path this feeds is gated on an absolute timelock that does not
+ * expire.
+ */
+declare function awaitRfqResolution(transport: RfqTransport, rfqId: string, options?: {
+    pollMs?: number;
+    deadline?: number;
+}): Promise<RfqStatus>;
+/** The Ark surface the refund push needs — narrower than a full provider, and
+ * satisfied by {@link RestArkProvider}. Same seam style as `RestoreIndexer`. */
+type RefundArkProvider = Pick<RestArkProvider, "getInfo" | "submitTx" | "finalizeTx">;
+/** The indexer surface the lockup lookup needs. */
+type RefundIndexer = Pick<RestIndexerProvider, "getVtxos">;
+/** A still-refundable virtual output sitting at the swap lockup. */
+interface LockupVtxo {
+    txid: string;
+    vout: number;
+    value: number;
+    /**
+     * The batch this output lived in expired and the operator swept it, so it
+     * is no longer a live leaf — it can be RECOVERED, but not spent offchain.
+     *
+     * It is still the trader's money and it is still visible, which is why
+     * {@link findLockupVtxos} returns it. What it is not is refundable by
+     * {@link pushRefundWithoutReceiver}: that builds an offchain Ark
+     * transaction, and the SDK's own predicates make the two states mutually
+     * exclusive — `canSpendOffchain` is false exactly when `canRecoverOnchain`
+     * is true (`wallet/vtxo.ts`), and the latter is documented as "must be
+     * recovered into a fresh batch rather than spent offchain". Holding the
+     * trader's `sender` key does not change that; a sweep removes the leaf from
+     * the live tree, not the signature from the trader.
+     *
+     * `packages/boltz-swap` splits on exactly this fact rather than working
+     * around it: `settleRefundWithoutReceiver` sends a live VTXO through an
+     * offchain tx and a recoverable one through `joinBatch` — "a swept
+     * (recoverable) VTXO is no longer a live leaf, so it can only be reclaimed
+     * by re-registering it into a batch".
+     *
+     * So the remedy is recovery (renewing the output into a fresh batch),
+     * after which the ordinary CLTV refund works again. This package does not
+     * build that round — see {@link pushRefundWithoutReceiver}, which refuses
+     * rather than submitting a spend that cannot succeed.
+     */
+    recoverable: boolean;
+}
+/**
+ * Thrown when a refund was asked for over outputs that have been swept.
+ *
+ * Carries the outpoints so a caller can act — recover exactly those, then
+ * retry — instead of reading a server rejection and guessing. `reason` follows
+ * the same convention as `awaitOnchainFill`'s `fill_timeout` and
+ * `claimOnchainFill`'s `claim_window_closed`.
+ *
+ * **The remedy already exists; this package does not reimplement it.** The SDK
+ * recovers swept outputs by re-registering them into a fresh batch, through
+ * `IVtxoManager.recoverVtxos()` — the same batch round `packages/boltz-swap`
+ * reaches via its own `joinBatch`. It reads the wallet's registered-contract
+ * snapshot (`recoverVtxos` → `wallet.getVtxos({ withRecoverable: true })` →
+ * `contractSnapshot()` → `contractManager.getContractsWithVtxos()`), so it
+ * covers a swap lockup as soon as that lockup is registered as a contract —
+ * which is what {@link RfqSwapManagerDeps.contracts} does. Registration is
+ * therefore not only a latency optimization; it is what turns a swept lockup
+ * from a dead end into something the ordinary wallet path can recover.
+ *
+ * Two caveats a caller must hold, neither enforceable from here:
+ *
+ * - **The wallet must hold the lockup's `sender` key**, because recovery
+ *   settles through `refundWithoutReceiver` — the leaf `vhtlc-v2` annotates
+ *   these VTXOs with.
+ * - **`refundLocktime` must have matured.** That leaf carries a CLTV, so a
+ *   recovery round including this VTXO earlier is rejected. `recoverVtxos`
+ *   sweeps every recoverable output in ONE settlement and has no CLTV
+ *   awareness, so recovering early can fail the whole batch rather than just
+ *   this output. `packages/boltz-swap` encodes the same rule as "pre-CLTV
+ *   recoverable → skipped".
+ */
+declare class LockupNeedsRecoveryError extends Error {
+    readonly name = "LockupNeedsRecoveryError";
+    readonly reason = "needs_recovery";
+    /** `txid:vout` for each output that must be recovered first. */
+    readonly outpoints: string[];
+    /**
+     * The contract's `refundLocktime`. Recovering before this matures is the
+     * hazard described above: `recoverVtxos()` sweeps EVERY recoverable output
+     * into one settlement with no CLTV awareness, so an early attempt can fail
+     * the whole batch — including unrelated outputs that were otherwise fine.
+     *
+     * Exposed as a value, not only inside the message, so a caller can encode
+     * `packages/boltz-swap`'s "pre-CLTV recoverable → skipped" rule without
+     * parsing prose. Seconds-based locktimes mature against the chain tip's
+     * timestamp rather than wall clock, so treat this as a floor to wait past,
+     * not an exact alarm.
+     */
+    readonly recoverableAfter: bigint;
+    constructor(outpoints: string[], recoverableAfter: bigint);
+}
+/**
+ * Every output still sitting at the lockup script — spendable AND
+ * swept-but-recoverable, each tagged with which it is.
+ *
+ * All of them, not the first: a trader may fund a lockup in more than one
+ * send, and refunding only `vtxos[0]` returns part of the money and strands
+ * the rest at a script whose other refund paths are all longer.
+ *
+ * BOTH queries, because they are disjoint sets and `spendableOnly` alone goes
+ * blind at exactly the wrong moment. A lockup whose batch expiry passed is
+ * swept into the recoverable set, and this function exists to serve swaps that
+ * sat unresolved — which are precisely the ones most likely to have got there.
+ * Reading only the spendable set would report `nothing_to_refund` over money
+ * that is still sitting at the script, which is worse than an error: it looks
+ * like a resolved swap. `packages/boltz-swap` merges the same two queries for
+ * the same reason (`arkade-swaps.ts`'s `refundableVtxos`).
+ *
+ * **Visible is not the same as refundable.** A `recoverable` output cannot be
+ * spent offchain at all — see {@link LockupVtxo.recoverable} — so this set is
+ * "what is there", not "what {@link pushRefundWithoutReceiver} can take back".
+ * That function refuses the recoverable ones by name rather than submitting a
+ * spend the server must reject.
+ *
+ * This read — not the RFQ's reported state — is the authority on whether
+ * there is anything left at the lockup.
+ *
+ * **Not replaced by the contract manager's VTXO state, deliberately.** Once a
+ * lockup is registered (see `RfqSwapManagerDeps.contracts`) the wallet tracks
+ * these same outputs, and `getContractsWithVtxos` plus `canSpendOffchain` /
+ * `canRecoverOnchain` would classify them. That is a WEAKER answer here on two
+ * counts: it serves the wallet REPOSITORY, which a degraded sync will happily
+ * hand back stale (`getSyncState()` reports `degraded` and returns cached rows
+ * rather than failing), and its height-based expiry test needs a chain tip this
+ * module does not have. The two queries below ask the indexer itself and need
+ * neither. Ask-the-indexer, don't-trust-local-state — the same posture
+ * {@link readLockupFate} takes, and for the same reason: this decides money.
+ */
+declare function findLockupVtxos(indexer: RefundIndexer, swapPkScript: Uint8Array): Promise<LockupVtxo[]>;
+/**
+ * The indexer surface the lockup-spend read needs: the vtxo lookup, plus the
+ * raw transactions those vtxos were spent by. Same narrow-seam style as
+ * {@link RefundIndexer} and `restore.ts`'s `RestoreIndexer`, and satisfied by
+ * {@link RestIndexerProvider}.
+ */
+type LockupSpendIndexer = Pick<RestIndexerProvider, "getVtxos" | "getVirtualTxs">;
+/**
+ * What chain data says became of a swap lockup — the whole answer, with no
+ * solver involvement and nothing taken on the solver's word.
+ */
+type LockupFate = 
+/** At least one output at the lockup is still unspent. Not over. */
+{
+    fate: "open";
+}
+/** Spent by a witness carrying a preimage that HASHES to the quote's
+ * `payment_hash`. Only the claim leaf can reveal one, and the only
+ * legitimate way the solver obtains it is by completing its side. */
+ | {
+    fate: "claimed";
+    preimage: Uint8Array;
+}
+/** Fully spent, and nothing that spent it revealed a matching preimage —
+ * so the money went back to the trader. See {@link readLockupFate}. */
+ | {
+    fate: "returned";
+}
+/** Nothing was learned: no outputs visible, an output spent by nothing the
+ * indexer names, a spend it could not produce, or a blob that would not
+ * decode. Never an answer. */
+ | {
+    fate: "unknown";
+};
+/**
+ * Decide from chain data alone whether a swap lockup settled, came back, or is
+ * still live.
+ *
+ * **Why this is decidable without asking anyone.** The lockup's claim leaf can
+ * only be spent by revealing `P`, so a spend witness carrying a value that
+ * hashes to the quote's `payment_hash` is proof the claim leaf was used — and
+ * the only legitimate way the counterparty obtains `P` is by completing its
+ * side of the swap. Every OTHER leaf is a refund: `nonInteractiveRefund` is
+ * covenant-pinned to the trader's own address (`enforcePayTo(senderPkScript)`),
+ * and `refund`, `refundWithoutReceiver`, `unilateralRefund` and
+ * `unilateralRefundWithoutReceiver` all require the trader's own signature. So
+ * "spent, but not by a hash-verified claim" means the money went back to the
+ * trader, and nothing here has to trust a counterparty to say so.
+ *
+ * **A matching witness SHAPE is not proof.** Only a candidate that hashes to
+ * `paymentHash` may be read as a claim; a 32-byte item that hashes to anything
+ * else is just bytes, and is treated as a refund. Getting this wrong in the
+ * permissive direction would report "settled" for a swap that actually
+ * refunded, which is precisely the fact a trader is relying on.
+ *
+ * **`unknown` is not `returned`.** An empty vtxo set (indexer lag, or a lockup
+ * not visible yet), a `spentBy` the indexer cannot produce a transaction for,
+ * or a blob that will not decode all come back as `unknown`. `getVirtualTxs`
+ * may legitimately return fewer transactions than were asked for, so the
+ * observed set is counted rather than assumed complete. The caller's correct
+ * response to `unknown` is the same as to `open`: keep watching, and let the
+ * refund timelock — which no outage can move — be what ends the wait.
+ *
+ * Ask-the-indexer, don't-trust-local-state: read fresh on every poll, never
+ * cached, the same posture {@link findLockupVtxos} already establishes.
+ */
+declare function readLockupFate(indexer: LockupSpendIndexer, input: {
+    swapPkScript: Uint8Array;
+    /** `sha256(P)`, hex — the quote's `payment_hash`. */
+    paymentHash: string;
+}): Promise<LockupFate>;
+/**
+ * Build, sign, and push the `refundWithoutReceiver` spend: return every funded
+ * output at the lockup to the trader's refund address.
+ *
+ * The leaf is `CLTV(refundLocktime) + <sender> + <server>` — the trader's own
+ * VHTLC `sender` key and the Arkade server, and NOBODY else. In particular the
+ * emulator is not involved: it co-signs only the two covenant leaves
+ * (`nonInteractiveClaim` / `nonInteractiveRefund`), which is why the solver's
+ * own escape hatch has to go through it and this one does not. So unlike that
+ * push, this transaction is submitted SIGNED, and the only counterparty is the
+ * Arkade server doing what it does for any collaborative spend.
+ *
+ * One aggregate output, not one per input — again unlike the solver's covenant
+ * refund, which needs index-aligned outputs because its ArkadeScript inspects
+ * the output at the current input's index. This leaf carries no covenant, so a
+ * single output paying the whole balance is both valid and cheaper.
+ *
+ * `refundPkScript` defaults to the destination the contract itself commits to
+ * (`nonInteractiveRefund`'s `senderPkScript`, i.e. the address the trader gave
+ * at quote time), so the ordinary call cannot send the refund somewhere the
+ * trader did not intend. It is overridable because this leaf, having no
+ * covenant, genuinely does permit any destination.
+ *
+ * **Consensus, not wall clock, decides when this is spendable.** A seconds
+ * locktime matures against median-time-past, which trails real time by roughly
+ * an hour, so a push issued the moment `refundLocktime` passes can be rejected
+ * until enough blocks land. That is expected, not a failure — see
+ * {@link refundIfUnresolved}, which retries.
+ *
+ * **Swept outputs are refused, not attempted.** This is an OFFCHAIN spend, and
+ * a swept output is no longer a live leaf: `canSpendOffchain` and
+ * `canRecoverOnchain` are mutually exclusive by construction, so a recoverable
+ * input cannot be spent this way whatever key signs it (see
+ * {@link LockupVtxo.recoverable}). Because every input lands in ONE aggregate
+ * transaction, a single swept output would take the live ones down with it —
+ * so the whole push is refused with {@link LockupNeedsRecoveryError} naming the
+ * outpoints, rather than submitted and rejected. Filtering them out silently
+ * would be worse still: it would report success over money that never moved.
+ */
+declare function pushRefundWithoutReceiver(ark: RefundArkProvider, input: {
+    script: InstanceType<typeof VHTLC.ScriptV2>;
+    /** The `sender` signer. Build it from the swap's `secrets` with
+     * `senderIdentityForRfqSecrets` — on an HD wallet that resolves from
+     * the seed, with no stored key bytes anywhere. */
+    sender: Identity;
+    vtxos: readonly LockupVtxo[];
+    /** Defaults to the contract's own committed refund destination. */
+    refundPkScript?: Uint8Array;
+}): Promise<{
+    arkTxid: string;
+    amount: number;
+}>;
+/**
+ * How long past `refundLocktime` to keep retrying the push before giving up
+ * and surfacing the server's refusal.
+ *
+ * Two hours because the CLTV matures against median-time-past (BIP-113), which
+ * lags wall clock by about an hour, plus room for a slow block. This is the
+ * mirror of `MIN_HEADROOM_SECONDS`, which refuses to FUND without 90 minutes
+ * of the same margin.
+ */
+declare const REFUND_MTP_LAG_SECONDS: number;
+type RefundOutcome = 
+/** The solver resolved it — claimed (`settled`) or returned it (`refunded`). */
+{
+    outcome: "resolved";
+    status: RfqStatus;
+}
+/** The trader took it back via `refundWithoutReceiver`. */
+ | {
+    outcome: "refunded";
+    arkTxid: string;
+    amount: number;
+    status: RfqStatus | null;
+}
+/** The refund window opened but the lockup holds nothing to return. */
+ | {
+    outcome: "nothing_to_refund";
+    status: RfqStatus | null;
+}
+/**
+ * The money is still at the lockup, but its batch was swept, so no offchain
+ * spend can take it back until it is recovered into a fresh batch. Returned
+ * rather than retried: unlike a median-time-past refusal, no amount of
+ * waiting fixes this — see {@link LockupNeedsRecoveryError}. Recover the
+ * named outpoints, then call this again.
+ */
+ | {
+    outcome: "needs_recovery";
+    outpoints: string[];
+    vtxos: LockupVtxo[];
+    status: RfqStatus | null;
+};
+/**
+ * Ask first, then fall back: watch the swap for the solver to resolve it, and
+ * if `refundLocktime` matures without that happening, take the lockup back
+ * with `refundWithoutReceiver`.
+ *
+ * This is the whole trader-side failure story in one call. It polls `status()`
+ * — the only "asking" this protocol has (see the module doc) — and returns as
+ * soon as the solver reports `settled` or `refunded`. Otherwise, once the
+ * quote's `refund_locktime` passes, it looks up what is actually at the lockup
+ * and pushes the refund.
+ *
+ * Two behaviours worth knowing:
+ *
+ * - **A dead negotiation is not a reason to stop.** `refused`, `expired` and
+ *   `stuck` are terminal states, but a trader can be holding a funded lockup in
+ *   every one of them, so they do not end the wait — only `settled`/`refunded`
+ *   do (see {@link RFQ_RESOLVED_STATES}). What ends it otherwise is the
+ *   timelock.
+ * - **The first push after the deadline may legitimately fail.** Median-time-
+ *   past trails wall clock, so the server can still consider the leaf locked
+ *   for a while after `refundLocktime` passes in real time. Failures are
+ *   retried at the poll interval until `attemptDeadline`, after which the last
+ *   error is rethrown rather than swallowed.
+ * - **A swept lockup ends the wait instead of consuming it.** Once the batch
+ *   is gone the CLTV refund is not "not yet" but "not this way", so it returns
+ *   `needs_recovery` naming the outpoints rather than retrying until the
+ *   deadline. Recover them and call again.
+ *
+ * Safe to call late, and safe to call again: a caller recovering from a crash
+ * well past the deadline skips straight to the push, and a lockup that is
+ * already empty comes back as `nothing_to_refund` instead of an error.
+ */
+declare function refundIfUnresolved(transport: RfqTransport, ark: RefundArkProvider, indexer: RefundIndexer, input: {
+    rfqId: string;
+    script: InstanceType<typeof VHTLC.ScriptV2>;
+    /** @see pushRefundWithoutReceiver */
+    sender: Identity;
+    /** `refund_locktime` from the quote, unix seconds. */
+    refundLocktime: number;
+    /** Defaults to the contract's own committed refund destination. */
+    refundPkScript?: Uint8Array;
+    pollMs?: number;
+    /** Stop retrying the push at this unix time, rethrowing the last
+     * error. Defaults to `refundLocktime + REFUND_MTP_LAG_SECONDS`. */
+    attemptDeadline?: number;
+    /** Injected for tests; defaults to wall clock, in unix seconds. */
+    now?: () => number;
+}): Promise<RefundOutcome>;
+
+/** The Ark surface the claim push needs — the same seam the refund push uses. */
+type ClaimArkProvider = RefundArkProvider;
+/**
+ * The lockup is funded for less than the swap agreed.
+ *
+ * The attack this names: the solver funds the correctly derived script with
+ * dust. Deriving the script locally — what protects every other corridor —
+ * proves nothing here, because the script was never the lie. Claiming anyway
+ * publishes `P`, which is what lets the solver settle the payer's Lightning
+ * HTLC in full.
+ */
+declare class LockupAmountMismatchError extends Error {
+    readonly name = "LockupAmountMismatchError";
+    readonly reason = "amount_mismatch";
+    readonly expectedAmount: number;
+    readonly lockedAmount: number;
+    constructor(expectedAmount: number, lockedAmount: number);
+}
+/**
+ * Build, sign, and push the collaborative claim of a receive-corridor lockup:
+ * move every funded output at the lockup to the trader's own destination,
+ * revealing `P` in the witness — which is also what settles the trader's side
+ * of the swap (the solver reads `P` off the public claim).
+ *
+ * The preimage is checked against the script's committed hash BEFORE anything
+ * is signed: a wrong value can never open the leaf, and catching it here
+ * beats learning it from the server's rejection.
+ *
+ * So is the funded VALUE, against `expectedAmount` — and for the same reason,
+ * only more sharply: disclosure happens at SUBMIT, since `P` rides the PSBT to
+ * the Ark server. A check that waits for the transaction to land has already
+ * leaked the secret.
+ *
+ * Swept outputs are refused, not attempted, exactly as in
+ * {@link pushRefundWithoutReceiver} — one aggregate transaction means a
+ * single non-live input would take the live ones down with it. That refusal
+ * comes first, which is what leaves the value gate a plain sum over live
+ * outputs.
+ *
+ * The server's countersignature is verified before finalizing, per input and
+ * against that input's own leaf. It does not protect `P` — that reached the
+ * server at submit — but it turns "reported claimed, nothing landed, the
+ * solver refunds hours later" into an immediate failure.
+ */
+declare function pushClaim(ark: ClaimArkProvider, input: {
+    /** The receive-direction covenant (see `receiveVtxoScript`). */
+    script: InstanceType<typeof VHTLC.ScriptV2>;
+    /** The trader's `receiver` signer. Build it from the swap's `secrets`
+     * with `senderIdentityForRfqSecrets` — on an HD wallet that resolves
+     * from the seed, with no stored key bytes anywhere. */
+    receiver: Identity;
+    /** `P`, 32 bytes — the trader generated it at request time. */
+    preimage: Uint8Array;
+    vtxos: readonly LockupVtxo[];
+    /** Where the claimed sats land — the swap's payout address, decoded. */
+    destinationPkScript: Uint8Array;
+    /** What the lockup must carry: the quote's `to_amount`, captured at
+     * REQUEST time and persisted with the record. Required rather than
+     * optional, so the guard cannot be skipped by the records that need
+     * it most. */
+    expectedAmount: number;
+    /** Set when this lockup already carries a claim of ours: `P` is public
+     * by then, so the value gate protects nothing and would only strand
+     * the remainder. */
+    partiallyClaimed?: boolean;
+}): Promise<{
+    arkTxid: string;
+    amount: number;
+}>;
+/**
+ * Wait for the solver-funded lockup to appear at the covenant script.
+ *
+ * Same conventions as `awaitRfqResolution`: a `pollMs` interval, an optional
+ * unix-seconds `deadline`, and a thrown error carrying a stable `reason` when
+ * the deadline passes.
+ */
+declare function awaitLockupFunding(indexer: RefundIndexer, swapPkScript: Uint8Array, options?: {
+    pollMs?: number;
+    deadline?: number;
+}): Promise<readonly LockupVtxo[]>;
+/**
+ * The one-call composition: wait for the solver's funding, then push the
+ * claim. The polling deadline gates the WAIT only — once the lockup is
+ * funded, the claim itself is gated by nothing but the solver's own refund
+ * deadline (`refund_locktime` from the quote), which is the number the
+ * caller's deadline should be measured against.
+ *
+ * The wait returns on the first output seen, so a funding the indexer
+ * surfaces piecemeal reaches {@link pushClaim}'s value gate short and throws
+ * {@link LockupAmountMismatchError}. Nothing was signed, so retrying once the
+ * rest lands is safe — and that is also the answer to a genuinely underfunded
+ * lockup, which never gets past the gate at all.
+ */
+declare function claimReceiveLockup(indexer: RefundIndexer, ark: ClaimArkProvider, input: Parameters<typeof pushClaim>[1] & {
+    /** The covenant's scriptPubKey, from the request flow's `swapPkScript`. */
+    swapPkScript: Uint8Array;
+    pollMs?: number;
+    deadline?: number;
+}): Promise<{
+    arkTxid: string;
+    amount: number;
+}>;
+
+/** The contract type a swap lockup registers under. `@arkade-os/sdk`'s handler
+ * for `VHTLC.ScriptV2` — the covenant script this corridor builds. */
+declare const SWAP_LOCKUP_CONTRACT_TYPE = "vhtlc-v2";
+declare const SWAP_LOCKUP_CONTRACT_LABEL = "Arkade RFQ swap lockup";
+declare const SWAP_LOCKUP_CONTRACT_KIND = "rfq-swap-lockup";
+/** The write seam registration needs, narrowed to the one method — the same
+ * injection style as `SwapContractRegistry`, and satisfied by a real
+ * `ContractManager` (`await wallet.getContractManager()`). */
+type LockupContractWriter = Pick<IContractManager, "createContract">;
+/**
+ * The lockup could not be written locally.
+ *
+ * Deliberately NOT a {@link SwapRefusal} or an {@link AddressMismatch}: those
+ * say "the quote is bad, never fund it", while this says "the quote is fine and
+ * your own store failed".
+ *
+ * The throw is the safe point: nothing is funded, and on the receive legs the
+ * invoice never left the function, so the abandoned quote is inert and simply
+ * retrying the request is the recovery. `script` travels beside `address` so a
+ * caller that still holds the swap — `RfqSwapManager`'s `ensureRegistered`, or
+ * one resuming from its own record — can retry `registerLockupContract` alone
+ * instead of re-quoting. It is NOT enough to resume a request that threw here:
+ * that caller never received the invoice or `secrets`.
+ */
+declare class LockupRegistrationFailed extends Error {
+    /** The lockup address that was never registered — never fund it: nothing
+     * is watching it. */
+    readonly address: string;
+    /** The covenant the row would have been written from — the other half of
+     * `registerLockupContract`, so the write is retryable without a quote. */
+    readonly script: InstanceType<typeof VHTLC.ScriptV2>;
+    constructor(script: InstanceType<typeof VHTLC.ScriptV2>, address: string, cause: unknown);
+}
+/**
+ * Register a lockup covenant so its VTXOs are watched, annotatable and — via
+ * `vhtlc-v2`'s own handler, which is never generically spendable — kept out of
+ * ordinary coin selection.
+ *
+ * The row carries script-level facts only. Per-swap identity and key material
+ * stay in the swap record: rows are keyed by script and first-writer-wins, so
+ * anything per-swap written here is stale from the second swap onward.
+ *
+ * Takes the derived script rather than a script hex plus params, so the row
+ * cannot describe a script other than the one it is keyed by.
+ *
+ * Throws {@link LockupRegistrationFailed}, so a caller can tell a local
+ * storage problem from a reason to walk away from the quote.
+ */
+declare function registerLockupContract(contracts: LockupContractWriter, script: InstanceType<typeof VHTLC.ScriptV2>, address: string): Promise<void>;
+
+/**
+ * Where a monitored swap stands.
+ *
+ * `claimable` and `claimed` are the states of a swap the TRADER has something
+ * to claim on: the L1 fill on an onchain send, and the solver-funded lockup on
+ * a receive. Only `lightning_send` has neither — there the solver claims the
+ * lockup, and the trader's only move is the refund.
+ */
+type RfqSwapState = 
+/** Live; nothing actionable yet. On a receive leg this covers the whole
+ * stretch before the solver funds anything. */
+"pending"
+/** There is something for the trader to take, and the window to take it is
+ * open: the confirmed L1 fill on an onchain send, or a lockup funded for at
+ * least `expectedAmount` on a receive. */
+ | "claimable"
+/**
+ * The trader's claim has been made — its L1 broadcast on an onchain send,
+ * its Arkade submission on a receive.
+ *
+ * **On a receive this is a local belief and not a chain fact**, which is
+ * why it is not terminal: `settled` is the chain's answer, and `refunded`
+ * is still reachable from here if the claim never lands and the solver
+ * takes the lockup back.
+ */
+ | "claimed"
+/**
+ * This wallet will not act, and only the counterparty can change that.
+ *
+ * On a send leg: the Arkade refund cannot be pushed from here — no secrets
+ * on the record, a descriptor from another seed, or nothing wired to act —
+ * so the lockup comes back only if the counterparty claims it or the wallet
+ * that can sign it is restored. On a receive leg: the trader holds no
+ * refund at all, so this is a lockup that cannot be claimed — funded for
+ * less than the swap agreed (publishing `P` for it is the whole attack
+ * `LockupAmountMismatchError` exists to refuse), or one whose claim window
+ * shut unclaimed. {@link RfqSwapCommon.blockedReason} says which.
+ *
+ * **Not terminal, and not a dead end.** The money is still at the lockup,
+ * so the counterparty's move is still observable and still ends the swap;
+ * and the refusal is re-checked every pass, so restoring the right wallet,
+ * wiring the callbacks, or the solver topping the lockup up returns the
+ * swap to `pending` and resumes the normal drive. For an onchain-send swap
+ * it says nothing about the L1 half, which keeps being driven and claimed.
+ */
+ | "needs_counterparty"
+/**
+ * Terminal: the lockup was spent by a hash-verified claim. Read off chain,
+ * never reported.
+ *
+ * On a send leg that claim is the counterparty's, and it is proof the
+ * counterparty completed its side. On a receive leg it is the TRADER's own
+ * — matched by the hash and not by our txid, so a claim that lands without
+ * us still counts (see {@link RfqSwapManager}).
+ */
+ | "settled"
+/**
+ * Terminal: the lockup was spent by something other than a claim.
+ *
+ * On a send leg that is the money coming back, by the solver's hand or the
+ * trader's. **On a receive leg it is a LOSS**: the lockup was the solver's
+ * money, every non-claim leaf is the solver's, and a swap that ends here
+ * ended with the trader's incoming payment never arriving. It is also where
+ * a receive swap ends when its window closes with nothing left to observe —
+ * see {@link RfqSwapManager}.
+ */
+ | "refunded"
+/** Terminal: an action failed and its window closed. */
+ | "failed";
+/** The states after which the manager stops monitoring a swap. Deliberately
+ * without `needs_counterparty`: retiring on it would unwatch a funded lockup
+ * whose claim is still the thing that ends the swap. */
+declare const RFQ_SWAP_TERMINAL_STATES: readonly ["settled", "refunded", "failed"];
+declare const isRfqSwapTerminal: (state: RfqSwapState) => boolean;
+/**
+ * What the manager needs to register a swap's lockup with the wallet, so the
+ * indexer pushes its funding and its spend instead of being asked every few
+ * seconds.
+ *
+ * Both fields are things the caller already holds. `script` is the very object
+ * `pushRefundWithoutReceiver` and `pushClaim` take, so a caller wired to act has
+ * it in hand; `address` is the request entrypoint's own return value. The
+ * address is taken rather than re-derived on purpose — the row's address must be
+ * the one that was actually funded, and a local re-derivation would silently use
+ * the SDK's default network, which is the exact bug `registerOfferContract`
+ * guards against.
+ */
+interface RfqSwapLockup {
+    /** The covenant. Its `pkScript` MUST equal the record's `lockupPkScript`. */
+    script: InstanceType<typeof VHTLC.ScriptV2>;
+    /** The Arkade address that was funded. */
+    address: string;
+}
+interface RfqSwapCommon {
+    /** The negotiation id — this record's identity. */
+    rfqId: string;
+    state: RfqSwapState;
+    /** The Arkade lockup's scriptPubKey — `swapPkScript` from any of the four
+     * request entrypoints. This is what the manager watches to decide the swap:
+     * it is the only handle on the covenant whose spend witness says whether
+     * the swap settled or came back. */
+    lockupPkScript: Uint8Array;
+    /** The covenant behind {@link lockupPkScript}, when the caller wants the
+     * lockup registered with a contract manager. Optional: without it the
+     * manager still watches the swap on its timer, it just cannot subscribe.
+     * See {@link RfqSwapManagerDeps.contracts}. */
+    lockup?: RfqSwapLockup;
+    /** `sha256(P)`, hex — the quote's `payment_hash`. The claim leaf can only
+     * be spent by revealing a value that hashes to this, which is what makes a
+     * settlement provable rather than reported. For an onchain send this is
+     * the SAME hash the L1 `htlc` carries: one `P` unlocks both legs. */
+    paymentHash: string;
+    /**
+     * `refund_locktime` from the quote, unix seconds.
+     *
+     * Whose deadline it is inverts with the direction, and so does what to do
+     * about it. On a send leg it is the TRADER's: the lockup is the trader's
+     * money and this gates the refund that takes it back, so it is a moment to
+     * act AFTER. On a receive leg it is the SOLVER's: the trader has no refund
+     * leaf at all, and this is the moment to have claimed BEFORE.
+     */
+    refundLocktime: number;
+    createdAt: number;
+    updatedAt: number;
+    /** Set once the trader's own `refundWithoutReceiver` push landed. */
+    refundArkTxid?: string;
+    /** Why `state` is `failed`. */
+    failure?: string;
+    /** Why `state` is `needs_counterparty`. Distinct from {@link failure},
+     * which means an action was attempted and did not work. */
+    blockedReason?: string;
+}
+/** `arkade:BTC->lightning:BTC`. Nothing for the trader to claim: the solver
+ * claims the lockup with the preimage it learns by paying the invoice — which
+ * is exactly why that spend's witness is proof the payment landed. */
+interface LightningSendSwap extends RfqSwapCommon {
+    kind: "lightning_send";
+}
+/** `arkade:BTC->onchain:BTC`. Carries the L1 half the trader must claim. */
+interface OnchainSendSwap extends RfqSwapCommon {
+    kind: "onchain_send";
+    /** The locally derived HTLC from `requestOnchainSend` — the manager reads
+     * `pkScript`, `paymentHash` and `refundLocktime` off it to classify. */
+    htlc: OnchainHtlc;
+    /** `profile.min_confirmations` from the quote. */
+    minConfirmations: number;
+    /** The fill's outpoint, learned on first sighting. Without it a SPENT
+     * HTLC reads as never funded — see {@link classifyOnchainHtlc}. */
+    funding?: {
+        txid: string;
+        vout: number;
+    };
+    /** Our L1 claim's txid. */
+    claimTxid?: string;
+}
+/**
+ * `lightning:BTC->arkade:BTC`. The inverted leg: the SOLVER funds the lockup
+ * and the TRADER claims it, and that claim is what publishes `P` and lets the
+ * solver settle the payer's held Lightning HTLC.
+ *
+ * Two consequences shape how this record is driven, both of them absent from
+ * the send legs:
+ *
+ * - **There is no trader-side refund.** Every non-claim leaf of this covenant
+ *   is the solver's, so the manager never calls
+ *   {@link RfqSwapManagerCallbacks.refundArkade} for one of these. A swap that
+ *   is not claimed is simply lost — the solver reclaims at
+ *   {@link RfqSwapCommon.refundLocktime} and the payer is refunded when the
+ *   held HTLC lapses.
+ * - **The claim is the whole swap, and it is on a deadline.** The trader must
+ *   be online for it: covclaimd cannot claim this covenant today, so the claim
+ *   packet's offline path does not run.
+ */
+interface LightningReceiveSwap extends RfqSwapCommon {
+    kind: "lightning_receive";
+    /**
+     * What the lockup must carry — the quote's `to_amount`, captured at REQUEST
+     * time and persisted with the record.
+     *
+     * **Not re-derivable, and not optional.** Captured at claim time it would
+     * be whatever the solver funded, which is the dust-funding attack rather
+     * than a check on it. A record that reaches the manager without a finite
+     * value here is reported `needs_counterparty` and never claimed: a
+     * comparison against `undefined` or `NaN` is false, so an unusable
+     * comparand does not fail the value gate, it deletes it.
+     */
+    expectedAmount: number;
+    /** Our Arkade claim's txid, once submitted. Set from the callback's return
+     * and never from a chain read — the chain's answer is `settled`. */
+    claimArkTxid?: string;
+}
+/**
+ * A monitored swap.
+ *
+ * This is a live record, not a serialization format: `lockupPkScript` and
+ * `htlc` hold derived `Uint8Array`s, and
+ * {@link RfqSwapManagerCallbacks.saveSwap} is where a caller projects it into
+ * whatever it stores. Rebuild it on restart the way it was made —
+ * `lightningSendVtxoScript` / `receiveVtxoScript` / `onchainHtlcScript` over
+ * the quote's binding fields — and hand the result to
+ * {@link RfqSwapManager.start}.
+ *
+ * **`onchain:BTC->arkade:BTC` is deliberately not a member yet.** Its Arkade
+ * half is the same solver-funded lockup as {@link LightningReceiveSwap}'s, but
+ * it also has an L1 half the trader funds and must take back itself
+ * (`buildHtlcRefund` at the HTLC's own `htlc_locktime`), which is a second
+ * deadline, a second observation seam and a second action callback. Adding the
+ * lockup half alone would produce a manager that silently lets that L1 refund
+ * window pass — the one failure mode {@link RfqSwapManager} refuses elsewhere
+ * by name (see `driveOnchain`'s missing-`ChainSource` check). Until the L1
+ * refund is driven too, that corridor is better served by the request and claim
+ * functions directly than by a monitor that covers half of it.
+ */
+type RfqSwap = LightningSendSwap | OnchainSendSwap | LightningReceiveSwap;
+/** What the manager should do next about an onchain-send swap's L1 half. */
+type OnchainSendAction = 
+/** Not funded yet, or not confirmed deep enough. */
+"wait"
+/** Funded, confirmed, and far enough from the refund leaf to claim safely. */
+ | "claim"
+/** The claim is off the table for good; the money comes back through the
+ * Arkade lockup instead. */
+ | "claim_window_closed"
+/** Our claim already landed (only the trader holds P). */
+ | "claimed"
+/** The solver took its L1 refund — the fill is gone. */
+ | "swept";
+/**
+ * The decision a "poll status, refund on timeout" loop gets wrong.
+ *
+ * {@link OnchainHtlcPhase} runs `unfunded -> awaiting_confirmations ->
+ * claimable -> (refundable | claimed | swept)`, and `refundable` does NOT mean
+ * "time to refund the L1 HTLC" — the trader has no key on that leaf; it is the
+ * SOLVER's refund, and reaching it means the trader's claim was missed. So the
+ * L1 claim has to be driven before it, and from it the only remaining move is
+ * the Arkade-side refund.
+ *
+ * There is a second, quieter trap between those two functions:
+ * `classifyOnchainHtlc` reports `claimable` right up until median-time-past
+ * reaches `refundLocktime`, while `claimOnchainFill` refuses from
+ * {@link ONCHAIN_CLAIM_MARGIN_SECONDS} before it — because broadcasting
+ * publishes P, and doing that into the counterparty's live refund window risks
+ * losing the race AND giving away the preimage. Driving straight off the phase
+ * would therefore spend that whole margin throwing `claim_window_closed` at
+ * every poll and never fall back. This function applies the margin, so
+ * "claimable" here means claimable by `claimOnchainFill` too.
+ */
+declare function nextOnchainAction(input: {
+    phase: OnchainHtlcPhase;
+    /** `htlc.refundLocktime` — when the solver's L1 refund leaf opens. */
+    htlcLocktime: number;
+    /** Unix seconds. */
+    now: number;
+}): OnchainSendAction;
+/** What the trader's own `refundWithoutReceiver` push returned, or `null` when
+ * the lockup held nothing to return. */
+type ArkadeRefundResult = {
+    arkTxid: string;
+    amount: number;
+} | null;
+/**
+ * The money-moving half, injected. The manager decides when; these do it.
+ *
+ * Neither action gets a retry loop of its own here — see the module doc. Do
+ * NOT wire `refundArkade` to `refundIfUnresolved`: that function is the
+ * single-swap version of this whole class and brings its own status polling
+ * and its own MTP retry loop, which would nest inside the manager's. Wire it
+ * to `findLockupVtxos` + `pushRefundWithoutReceiver`, which is the atomic push
+ * `refundIfUnresolved` itself calls.
+ *
+ * Resolve the sender key through `senderIdentityForSwapRecord`: it is
+ * what turns "this wallet cannot sign this swap" into
+ * {@link RefundNotLocallyPossibleError}, which the manager reports as
+ * `needs_counterparty` instead of retrying for the whole refund window.
+ */
+interface RfqSwapManagerCallbacks {
+    /** Build and broadcast the L1 claim. See `claimOnchainFill`. */
+    claimOnchain: (swap: OnchainSendSwap, utxo: ChainUtxo) => Promise<{
+        txid: string;
+    }>;
+    /**
+     * Claim the solver-funded lockup on a receive leg, revealing `P`. Wire it
+     * to `pushClaim` — the outputs are supplied, so `findLockupVtxos` has
+     * already been called and `claimReceiveLockup`'s wait would only sit on a
+     * lockup the manager has just seen.
+     *
+     * **Pass `expectedAmount` and `partiallyClaimed` straight through.** The
+     * manager checks the funded value before calling this, but that check
+     * decides WHEN to act; `pushClaim`'s decides whether `P` is published, and
+     * it is the one that runs with nothing between it and the signature. Two
+     * checks, one of which is load-bearing — do not drop the inner one because
+     * the outer one exists.
+     *
+     * Required rather than optional, like {@link claimOnchain}: a receive swap
+     * monitored with nothing wired to claim it is a swap that quietly expires,
+     * and a compile error is the right way to learn that.
+     */
+    claimLockup: (swap: LightningReceiveSwap, vtxos: readonly LockupVtxo[], options: {
+        /** A claim of ours is already out, so `P` is public and the value
+         * gate has nothing left to protect — pass this to `pushClaim` so a
+         * funding that arrived piecemeal can still be swept. */
+        partiallyClaimed: boolean;
+    }) => Promise<{
+        arkTxid: string;
+        amount: number;
+    }>;
+    /** Push `refundWithoutReceiver` for every output at the lockup. See
+     * `pushRefundWithoutReceiver`; return `null` for an empty lockup. Never
+     * called for a {@link LightningReceiveSwap} — that leg's refund leaf is the
+     * solver's. */
+    refundArkade: (swap: RfqSwap) => Promise<ArkadeRefundResult>;
+    /**
+     * Whether a local refund is possible at all — the record's secrets, against
+     * this wallet. Called every pass, including *before* the refund window
+     * opens, so a swap nobody can refund says so while the solver can still
+     * act, instead of at the deadline; and so restoring the right wallet lifts
+     * the state again. Never called for a receive swap: there is no local
+     * refund there to probe for.
+     *
+     * Optional: omit to answer "yes" and learn at push time, from
+     * {@link RefundNotLocallyPossibleError}. Local by contract — no network
+     * call belongs here.
+     */
+    canRefundArkade?: (swap: RfqSwap) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /** Persist the record. Called after any pass that changed it. */
+    saveSwap: (swap: RfqSwap) => Promise<void>;
+}
+/** The actions the manager executes on a caller's behalf. */
+type RfqSwapActionName = "claimOnchain" | "claimLockup" | "refundArkade";
+interface RfqSwapManagerEvents {
+    /** Every state change, including ones that read as going backwards.
+     * `claimed -> claimable` is legal and expected on a receive swap the solver
+     * funds piecemeal: a lockup topped up after a claim is a new claimable
+     * event, and the label says so before the sweep goes out. Treat these
+     * states as a description of what to do next, not as a progress bar. */
+    onSwapUpdate?: (swap: RfqSwap, previous: RfqSwapState) => void;
+    /** Fired once, when a swap leaves monitoring `settled` or `refunded`.
+     * A swap that ends `failed` reports through `onSwapFailed` instead — the
+     * two are mutually exclusive. */
+    onSwapCompleted?: (swap: RfqSwap) => void;
+    /** Fired for any action that threw — including ones the manager will retry
+     * on the next pass — and once more when the swap finally ends `failed`. */
+    onSwapFailed?: (swap: RfqSwap, error: Error) => void;
+    onActionExecuted?: (swap: RfqSwap, action: RfqSwapActionName) => void;
+}
+type SwapUpdateListener = NonNullable<RfqSwapManagerEvents["onSwapUpdate"]>;
+type SwapCompletedListener = NonNullable<RfqSwapManagerEvents["onSwapCompleted"]>;
+type SwapFailedListener = NonNullable<RfqSwapManagerEvents["onSwapFailed"]>;
+type ActionExecutedListener = NonNullable<RfqSwapManagerEvents["onActionExecuted"]>;
+interface RfqSwapManagerConfig {
+    /** Drive claims and refunds automatically (default: true). With this off
+     * the manager still watches and reports, so a caller can act by hand off
+     * `claimable`. */
+    enableAutoActions?: boolean;
+    /** How often to run a pass, ms. Default 5000 — the same interval
+     * `awaitOnchainFill` and `refundIfUnresolved` poll at. */
+    pollIntervalMs?: number;
+    /** Injected for tests; defaults to wall clock, in unix seconds — the same
+     * convention `refundIfUnresolved` uses. */
+    now?: () => number;
+    events?: RfqSwapManagerEvents;
+}
+/** The contract-manager surface this needs, narrowed for injection — the same
+ * seam style as {@link LockupSpendIndexer} and `refund.ts`'s
+ * {@link RefundArkProvider}, and satisfied structurally by a real
+ * `ContractManager` (`await wallet.getContractManager()`). */
+type SwapContractRegistry = Pick<IContractManager, "createContract" | "getContracts" | "onContractEvent" | "setContractWatchState">;
+/** The observation seams. None is owned by the manager, and none holds keys —
+ * same philosophy as `onchainHtlc.ts`'s `ChainSource`. There is no
+ * `RfqTransport` here on purpose: nothing this manager decides depends on the
+ * solver answering (see the module doc). */
+interface RfqSwapManagerDeps {
+    /** Arkade access. Required: this is how a swap's resolution is determined,
+     * for both legs. */
+    indexer: LockupSpendIndexer;
+    /** L1 access. Required to monitor onchain-send swaps; a lightning-only
+     * caller can leave it out. */
+    chain?: ChainSource;
+    /**
+     * The wallet's contract manager, when there is one. Optional in the same
+     * way {@link chain} is: a caller with no wallet, or one that only wants the
+     * timer, still gets a fully working manager — the subscription is a
+     * LATENCY optimization and nothing depends on it.
+     *
+     * Supplying it buys two things. The lockup gets REGISTERED, which is what
+     * puts it in the wallet's own contract set at all — a prerequisite for
+     * anything that has to act on the lockup before its batch expires, since an
+     * expired lockup is swept and loses every cooperative path. And the indexer
+     * PUSHES its funding and its spend, so a settlement is noticed when it
+     * happens rather than up to `pollIntervalMs` later.
+     *
+     * Prefer `await wallet.getContractManager()` over constructing one, the way
+     * `createOffer` does.
+     */
+    contracts?: SwapContractRegistry;
+}
+/**
+ * Watches a set of live RFQ swaps and drives each to its end.
+ *
+ * One pass per swap, in this order, every
+ * {@link RfqSwapManagerConfig.pollIntervalMs} — and additionally the moment a
+ * contract event names that swap's lockup, which changes only WHEN a pass runs,
+ * never what it concludes (see {@link subscribe}):
+ *
+ * 0. **Register the lockup**, if a contract manager was supplied and it is not
+ *    registered yet. Best-effort; never blocks the steps below.
+ * 1. **Ask the chain what became of the lockup** — {@link readLockupFate}. A
+ *    spend whose witness HASHES to the quote's `payment_hash` ends the swap
+ *    `settled`; a lockup fully spent by anything else ends it `refunded`.
+ *    Anything the indexer could not answer is `unknown`, which is NOT an
+ *    answer: the pass carries on to the steps below, whose deadlines an indexer
+ *    outage has no bearing on.
+ * 2. **Drive the trader's claim.** On an onchain send that is the L1 fill — see
+ *    {@link nextOnchainAction}. On a receive it is the lockup itself, and it
+ *    ends the pass: that leg has no step 3.
+ * 3. **Take the lockup back**, send legs only, once `refundLocktime` has passed
+ *    and step 1 has not ended the swap. This runs for onchain-send too,
+ *    including after a successful claim: the trader's lockup is still funded and
+ *    still theirs to recover if the solver never comes for it. When no local
+ *    refund is possible at all — no secrets, another wallet's descriptor,
+ *    nothing wired — the swap reports `needs_counterparty` instead of retrying
+ *    a push that cannot work.
+ *
+ * **What step 1 proves depends on the direction.** On a send leg every non-claim
+ * leaf pays the trader's own committed address or needs the trader's own
+ * signature, so "spent, but not by a hash-verified claim" means the money came
+ * back. On a receive leg those leaves are the SOLVER's and the claim leaf is the
+ * trader's, so the same two readings mean the opposite things — `settled` is the
+ * trader's own claim landing, `refunded` is the solver taking back a lockup the
+ * trader failed to claim. The read is identical; only the state docs differ.
+ *
+ * Two things about the receive arm that are easy to get wrong, and are asserted
+ * in the tests rather than left to be inferred:
+ *
+ * - **A claim is matched by its preimage, never by our txid.** The covenant's
+ *   `nonInteractiveClaim` leaf is pinned to the trader's own payout script, so a
+ *   claim that lands without us — covclaimd, the day it works — still pays the
+ *   trader and is still `settled`. Matching on the txid we submitted would turn
+ *   that success into an anomaly.
+ * - **`LockupFate.fate === "claimed"` maps to the state `settled`, never to the
+ *   state `claimed`.** The two words live one layer apart: the fate is the
+ *   chain's, the state is ours, and the state `claimed` means only that we
+ *   submitted something.
+ */
+declare class RfqSwapManager {
+    private readonly deps;
+    private readonly config;
+    private callbacks;
+    private readonly swapUpdateListeners;
+    private readonly swapCompletedListeners;
+    private readonly swapFailedListeners;
+    private readonly actionExecutedListeners;
+    private readonly monitored;
+    /** Monitored swaps by lockup script hex, so a contract event — which names
+     * a script and nothing else — can find the swap it belongs to. */
+    private readonly byLockupScript;
+    /**
+     * Swaps whose lockup registration has been SETTLED one way or another,
+     * mapped to whether a contract row actually resulted. Membership is what
+     * stops a per-pass retry from becoming a per-pass round trip; the value is
+     * what keeps a swap that could never be registered from later trying to
+     * retire a row that does not exist, which would report a spurious failure
+     * on a swap that in fact succeeded.
+     */
+    private readonly registered;
+    /**
+     * Swaps whose `refundArkade` answered {@link RefundNotLocallyPossibleError}
+     * in this process. Membership stops the push from being re-issued every
+     * pass — it cannot start working on its own, and re-issuing it is the
+     * grind `needs_counterparty` exists to remove. Only
+     * {@link RfqSwapManagerCallbacks.canRefundArkade} clears it, so a caller
+     * with no probe learns again on the next start, when the wallet that can
+     * sign may well have been restored.
+     */
+    private readonly refundRefused;
+    /**
+     * The last error a receive swap's claim callback threw, by rfqId.
+     *
+     * Kept only to tell two terminal outcomes apart once the claim window
+     * shuts: a swap whose claim was attempted and kept failing ends `failed`
+     * with that reason, while one that simply never became claimable ends
+     * `refunded`. Without it a broken claim callback would resolve a caller's
+     * {@link waitForSwapCompletion} as an ordinary unwind.
+     *
+     * Process-local, like {@link refundRefused}: after a restart the same swap
+     * ends `refunded` instead, which costs the caller a reason and nothing else
+     * — every throw was already reported through `onSwapFailed` as it happened.
+     */
+    private readonly lastClaimError;
+    /**
+     * The lockup outpoints a receive swap's claim callback has already been
+     * handed, by rfqId.
+     *
+     * What this exists to prevent: a claim SUCCEEDS, and for the next few
+     * passes the indexer still lists those outputs as unspent. Without a
+     * record of what was already claimed, every one of those passes would
+     * re-submit the same spend, fail against the server, and report a swap
+     * that in fact worked as failing. With one, a re-claim happens only when
+     * an outpoint appears that was never claimed — a lockup funded piecemeal,
+     * which is legitimate and which `partiallyClaimed` exists for.
+     *
+     * Process-local: after a restart a swap with a live claim tries once more.
+     * That is the recovery case rather than the spam one — a claim that never
+     * landed leaves its outputs unspent, and one that did leaves a single
+     * rejection.
+     */
+    private readonly claimedOutpoints;
+    /** Live `onContractEvent` subscription, held so `stop()` can drop it. */
+    private unsubscribeContracts;
+    /** Terminal records, kept so a late {@link waitForSwapCompletion} still
+     * answers instead of throwing "not found". Cleared by {@link removeSwap}. */
+    private readonly finished;
+    private readonly waiters;
+    /** Records changed during the current pass, flushed through `saveSwap`. */
+    private readonly dirty;
+    /** Race guard: one action at a time per swap. */
+    private readonly inProgress;
+    private timer;
+    private running;
+    constructor(deps: RfqSwapManagerDeps, config?: RfqSwapManagerConfig);
+    /** Wire the money-moving half. Without it the manager only watches. */
+    setCallbacks(callbacks: RfqSwapManagerCallbacks): void;
+    onSwapUpdate(listener: SwapUpdateListener): () => void;
+    onSwapCompleted(listener: SwapCompletedListener): () => void;
+    onSwapFailed(listener: SwapFailedListener): () => void;
+    onActionExecuted(listener: ActionExecutedListener): () => void;
+    /**
+     * Load records and begin monitoring. Runs one pass immediately — a caller
+     * resuming after a restart may be well past a deadline already — then
+     * every `pollIntervalMs`. Records that are already terminal are kept only
+     * so {@link waitForSwapCompletion} can answer for them.
+     *
+     * Calling it again while running loads the records and returns rather than
+     * re-arming — dropping them silently would strand a funded swap on a
+     * caller's harmless double-start.
+     */
+    start(swaps?: readonly RfqSwap[]): Promise<void>;
+    /**
+     * Stop monitoring and clear the timer. In-flight actions are not
+     * cancellable and run to completion; outstanding
+     * {@link waitForSwapCompletion} promises are left pending, since
+     * stop/start is a pause rather than a cancellation.
+     *
+     * The contract subscription is dropped too — an open stream with nothing
+     * reacting to it is a leak, and {@link start} puts it back. What is NOT
+     * undone is the contract registration: those rows are the wallet's, they
+     * outlive this manager's lifecycle, and dropping them would unwatch a
+     * lockup that is still funded.
+     */
+    stop(): Promise<void>;
+    /** Begin monitoring a swap. Polled immediately when the manager is running,
+     * so a just-funded swap does not wait out a whole interval. */
+    addSwap(swap: RfqSwap): Promise<void>;
+    /** Forget a swap entirely, monitored or finished.
+     *
+     * Its contract row is left alone: registration is a wallet-level fact about
+     * a script that may still hold money, and this call says only that THIS
+     * manager stops driving the swap. Retiring the row is reserved for a swap
+     * that reached a terminal state, where the lockup is provably done. */
+    removeSwap(rfqId: string): Promise<void>;
+    /** Every swap still being monitored. */
+    getPendingSwaps(): Promise<RfqSwap[]>;
+    hasSwap(rfqId: string): Promise<boolean>;
+    /** True while an action for this swap holds the per-swap lock. */
+    isProcessing(rfqId: string): Promise<boolean>;
+    getStats(): Promise<{
+        isRunning: boolean;
+        monitoredSwaps: number;
+        finishedSwaps: number;
+        inProgress: number;
+        pollIntervalMs: number;
+    }>;
+    /**
+     * Run one monitoring pass over every swap now.
+     *
+     * {@link start} calls this on an interval, but it is public on purpose: a
+     * caller that sleeps its process (a mobile app resuming, a service worker
+     * waking) wants a pass on that event rather than at the next tick. Passes
+     * do not overlap per swap — the in-progress lock makes a concurrent call a
+     * no-op for any swap already being worked on.
+     */
+    poll(): Promise<void>;
+    /**
+     * Resolve once this swap's PAYOUT is decided — which for onchain-send is
+     * the L1 claim, not the end of the record's life: once `claimTxid` is set
+     * the trader has the coins it swapped for, and what remains is the manager
+     * watching the Arkade lockup close. That holds however the record is
+     * labelled afterwards, `needs_counterparty` included. Lightning-send has no
+     * such split and resolves at `settled`/`refunded`, and so does lightning
+     * receive — see {@link isPayoutDecided} for why its own claim txid does not
+     * decide it.
+     *
+     * Rejects only on `failed`. `refunded` resolves: on a send leg a refund is
+     * an outcome the caller asked this manager to drive, not an exception. On a
+     * receive leg it is the swap being lost, which is still an answer and not
+     * an error — read `state`, do not infer success from resolution.
+     */
+    waitForSwapCompletion(rfqId: string): Promise<RfqSwapOutcome>;
+    private track;
+    /** Drops the swap from BOTH indexes. The event index is the one that stops
+     * a late event finding a swap that is gone; `pollSwap`'s own
+     * `monitored` check would also catch it, and deliberately still does —
+     * either alone is sufficient, which is what keeps a future change to one of
+     * them from silently re-driving a cancelled swap. */
+    private untrack;
+    /**
+     * Turn the indexer's push into an extra reason to run a pass — and nothing
+     * more.
+     *
+     * **This is deliberately not a source of truth.** An event names a script;
+     * the reaction is to run the ordinary pass for the swap at that script, and
+     * that pass re-reads the lockup through {@link readLockupFate} exactly as
+     * the timer's pass does. So an event that is missed, duplicated, reordered
+     * or outright FORGED can only cost or save latency — it can never change
+     * what this manager believes about a swap, and it can never on its own
+     * cause a claim or a refund. That property is what makes it safe to bolt a
+     * best-effort stream onto a money path, and it must survive any future
+     * change here: the moment an event is BELIEVED rather than merely acted on,
+     * a relay outage becomes a correctness problem instead of a latency one.
+     *
+     * The timer stays armed regardless, and is the failsafe. Every deadline
+     * that moves money — `refundLocktime`, the L1 claim window — is an absolute
+     * timelock that passes whether or not a single event ever arrives.
+     */
+    private subscribe;
+    /**
+     * Register this swap's lockup with the wallet's contract manager, once.
+     *
+     * The backstop, not the primary site: `requestLightningSend` /
+     * `requestOnchainSend` register before the caller can fund, so this covers
+     * swaps whose records predate that — and costs nothing when it does not,
+     * since `createContract` is first-writer-wins.
+     *
+     * Best-effort by design: a failure here is reported and retried on the next
+     * pass, and never aborts the pass it is part of. Registration buys latency
+     * and puts the lockup in the wallet's contract set; it decides nothing. The
+     * money path below it reads the indexer directly and is gated on timelocks
+     * that a missing contract row has no bearing on, so failing the pass over
+     * this would trade a real deadline for a bookkeeping one.
+     */
+    private ensureRegistered;
+    /** Stop watching a finished swap's lockup. Retained, not deleted: the row
+     * is what keeps the lockup's own VTXOs annotatable and its history
+     * readable, while `retained` is what drops it from the subscription and
+     * the poll — a settled swap that stayed watched would cost the wallet a
+     * script for its whole life. Best-effort — the swap is over either way. */
+    private retireContract;
+    private arm;
+    private pollSwap;
+    private runPass;
+    /**
+     * The receive leg's whole state machine: claim the solver-funded lockup
+     * while the window is open, and recognise the shapes in which it can be
+     * lost.
+     *
+     * **The window closes at `refundLocktime`, on wall clock, with no margin.**
+     * Both halves of that are deliberate. It closes there because publishing
+     * `P` into the solver's live refund window risks losing the race and
+     * handing over the preimage anyway — the hazard `ONCHAIN_CLAIM_MARGIN_SECONDS`
+     * guards on the L1 side. It takes no margin because the two situations are
+     * not alike: that one budgets for confirmation depth, while this claim is an
+     * offchain spend that lands in seconds. Wall clock is already the
+     * conservative reading — the solver's leaf is a CLTV, which matures against
+     * median-time-past, and MTP trails wall clock — so the real window extends
+     * PAST this deadline rather than ending before it. Every second of margin
+     * subtracted here is a second of live claim window given away for nothing.
+     *
+     * **The trader has no move after it.** Nothing here can take the lockup
+     * back, so once the window shuts the swap is the solver's to resolve and
+     * this manager's job is to watch it happen and then stop.
+     */
+    private driveReceiveClaim;
+    /**
+     * Claim what the solver funded, once it is enough.
+     *
+     * The value gate here decides WHEN to act. `pushClaim`'s decides whether
+     * `P` is published, and runs with nothing between it and the signature —
+     * the check that matters is the inner one, and this is not a reason to
+     * relax it.
+     */
+    private claimIfFunded;
+    /** `handled` ends the pass; `continue` falls through to the refund gate. */
+    private driveOnchain;
+    private driveArkadeRefund;
+    /** Whether any of these outputs has never been handed to the claim
+     * callback — the only reason to claim a lockup a second time. */
+    private hasUnclaimedOutpoint;
+    private rememberClaimed;
+    /**
+     * L1 progress, which past the refund window must not overwrite a refusal.
+     * The two halves are independent — a claimed fill says nothing about
+     * whether this wallet can take the Arkade lockup back — and `claimed` is
+     * re-asserted from chain on every pass, so without this a blocked swap
+     * would flip between the two states forever. The claim itself always runs;
+     * only the label defers, and only once the refund is the live half.
+     */
+    private setOnchainState;
+    /** The probe's refusal reason, or `undefined` when a local refund is
+     * possible as far as anyone here can tell. A probe that throws is treated
+     * as a refusal: a capability check that cannot answer is not a yes. */
+    private probeRefusal;
+    /** Report that no local refund will happen, without ending the swap. */
+    private block;
+    /** The way back out, taken as soon as the swap becomes actionable again.
+     * Back to what the record can prove, not to `pending` unconditionally: a
+     * swap that already made its claim has a txid for it, and reporting that
+     * swap as `pending` would un-say something true. */
+    private unblock;
+    private touch;
+    private setState;
+    /** Terminal failure. The `onSwapFailed` emission is left to
+     * {@link finalize}, so this does not double-report. */
+    private fail;
+    private emitFailed;
+    private emitAction;
+    /** Whether the record is now persisted — false only when `saveSwap` threw. */
+    private save;
+    /**
+     * Drop a terminal swap from monitoring and report it exactly once.
+     *
+     * `onSwapCompleted` and `onSwapFailed` are mutually exclusive here, unlike
+     * Boltz's manager, which fires completion for every swap that leaves
+     * monitoring including the failed ones — a listener named "completed" that
+     * also fires on failure is a trap worth not inheriting.
+     */
+    private finalize;
+    private settleWaiters;
+}
+/** What {@link RfqSwapManager.waitForSwapCompletion} reports. `txid` is the
+ * trader's own claim — L1 for a claimed onchain send, Arkade for a claimed
+ * receive — or the ark txid for a refund the trader pushed; a solver-side
+ * settlement or refund carries none, and a receive swap that ended `refunded`
+ * carries none either, however far its claim got (see {@link outcomeOf}). So
+ * a `txid` here always names something that happened, and `state` remains the
+ * only thing to read for whether the swap paid out. */
+interface RfqSwapOutcome {
+    state: RfqSwapState;
+    txid?: string;
+}
+
+export { type ArkadeRefundResult, AssetSwap, AssetSwapRepository, ChainSource, ChainUtxo, type ClaimArkProvider, type ClaimPacketInput, type DiscoverMarketsOptions, IndexedDbAssetSwapRepository, type LightningReceiveSwap, type LightningSendSwap, LockupAmountMismatchError, type LockupContractWriter, type LockupFate, LockupNeedsRecoveryError, LockupRegistrationFailed, type LockupSpendIndexer, type LockupVtxo, MarketsCacheEntry, OFFER_PACKET_TYPE, type Offer, type OfferContractRetirer, type OfferSwapWatcher, OnchainHtlc, OnchainHtlcPhase, type OnchainSendAction, type OnchainSendSwap, type PlanError, QUOTE_OPTIONS, REFUND_MTP_LAG_SECONDS, RFQ_RESOLVED_STATES, RFQ_SWAP_TERMINAL_STATES, type RefundArkProvider, type RefundIndexer, type RefundOutcome, type RestoreIndexer, RfqStatus, type RfqSwap, type RfqSwapActionName, type RfqSwapLockup, RfqSwapManager, type RfqSwapManagerCallbacks, type RfqSwapManagerConfig, type RfqSwapManagerDeps, type RfqSwapManagerEvents, type RfqSwapOutcome, type RfqSwapState, RfqTransport, SWAP_LOCKUP_CONTRACT_KIND, SWAP_LOCKUP_CONTRACT_LABEL, SWAP_LOCKUP_CONTRACT_TYPE, type SealedClaimPacket, type SpendKind, type SwapContractRegistry, type Tx, type WatchOfferSwapsParams, awaitLockupFunding, awaitRfqResolution, cancelOffer, claimReceiveLockup, classifyDepositSpend, classifySpend, createOffer, decodeOffer, discoverMarkets, encodeOffer, findLockupVtxos, findMarket, isRfqSwapTerminal, isRfqTerminal, makeCachedFeedFetch, nextOnchainAction, offerVtxoScript, pushClaim, pushRefundWithoutReceiver, readLockupFate, refundIfUnresolved, registerLockupContract, restoreAssetSwaps, retireSettledOfferContracts, sealClaimPacket, spendTxidsOf, spendUpdate, swapPrograms, validatePlan, watchOfferSwaps };