@arkade-os/swap 0.0.12 → 0.1.0-rc.1

package/dist/node/index.d.ts

@@ -0,0 +1,1055 @@
+import { SQLExecutor } from '@arkade-os/sdk/repositories/sqlite';
+import { Corridor as Corridor$1, DiscoveredMarket } from '@arkade-os/solver-discovery';
+import { VHTLC, NetworkName } from '@arkade-os/sdk';
+
+/**
+ * The platform's per-user configuration directory.
+ *
+ * The three conventions, in the order each platform expects:
+ *
+ * - Linux and the BSDs follow the XDG Base Directory spec — `$XDG_CONFIG_HOME`
+ *   when set to an absolute path, else `~/.config`. A relative value is
+ *   ignored, which the spec requires rather than suggests.
+ * - macOS uses `~/Library/Application Support`.
+ * - Windows uses `%APPDATA%`, falling back to the roaming path under the home
+ *   directory when the variable is missing — as it is in some service contexts.
+ */
+declare const configDir: (env?: NodeJS.ProcessEnv) => string;
+/**
+ * The default database path for one network.
+ *
+ * Returned rather than created: opening it is what creates the directory, and a
+ * caller that only wants to know where the file would be — to report it, to
+ * back it up, to delete it — should not have to make one as a side effect.
+ */
+declare const swapDatabasePath: (network: string, env?: NodeJS.ProcessEnv) => string;
+
+type AssetSwapStatus = "pending" | "cancelling" | "fulfilled" | "cancelled" | "recoverable" | "awaiting_fill" | "claimable" | "claimed" | "refunded_l1";
+/**
+ * The record fields a wallet-provisioned secret becomes — what
+ * {@link swapSecretsToRecord} emits, and what every record type carrying swap
+ * secrets embeds.
+ *
+ * A named type rather than four fields restated per record: the mapper and the
+ * records it feeds must agree exactly, and a record that silently omits one of
+ * these round-trips a swap whose preimage cannot be re-derived. Embedding makes
+ * the omission a compile error instead.
+ *
+ * **Only `preimageHex` is secret.** `signingDescriptor` and `preimageSaltHex`
+ * are public derivation inputs — they must survive a field-mapped backend, but
+ * they leak nothing without the seed.
+ */
+interface SwapSecretsProjection {
+    /**
+     * The wallet descriptor this swap's sender key comes from — a fresh HD
+     * child, or a static wallet's `tr(pubkey)`. Public — the signer
+     * re-derives from the wallet, so the record carries no key material.
+     */
+    signingDescriptor?: string;
+    /** P, hex, when it cannot be re-derived from the seed at all: the user
+     * supplied it, or the signer cannot sign deterministically. The swap's only
+     * claim secret when present. */
+    preimageHex?: string;
+    /**
+     * The salt P derives from, hex, on the salted arm — what a static wallet
+     * gets instead of storing P. **Public**, and unlike every other field here
+     * it is minted per swap: it is what stops one repeating key from handing
+     * every swap the same preimage.
+     */
+    preimageSaltHex?: string;
+}
+interface AssetSwap extends SwapSecretsProjection {
+    /** Funding txid — the swap's identity. */
+    id: string;
+    /** 'btc' or a 68-hex asset id. */
+    fromAsset: string;
+    toAsset: string;
+    /** Atomic amounts as strings (bigint is not JSON-safe). */
+    fromAmount: string;
+    /** The covenant wantAmount — a floor, the fill pays >= this. */
+    toAmount: string;
+    swapAddress: string;
+    /** Hex pkScript of the swap contract — the indexer monitoring key. */
+    swapPkScript: string;
+    /** TLV offer — needed to rebuild the contract for cancel. */
+    offerHex: string;
+    fundingTxid: string;
+    spentTxid?: string;
+    status: AssetSwapStatus;
+    createdAt: number;
+    completedAt?: number;
+    /** RFQ pair string, e.g. `arkade:BTC->onchain:BTC`. */
+    pair?: string;
+    /** `sha256(P)`, hex. Public, and how a restore confirms a candidate
+     * derivation is the right one. */
+    paymentHash?: string;
+    /** The L1 HTLC's pkScript, hex — the chain-watch key. */
+    htlcPkScriptHex?: string;
+    htlcLocktime?: number;
+    /** The L1 funding txid, once observed. */
+    l1Txid?: string;
+}
+
+interface OnchainHtlc {
+    address: string;
+    /** `0x5120…` — the P2TR output script. */
+    pkScript: Uint8Array;
+    leaves: {
+        claim: Uint8Array;
+        refund: Uint8Array;
+    };
+    /** Serialized control blocks per leaf, ready for a script-path witness. */
+    controlBlocks: {
+        claim: Uint8Array;
+        refund: Uint8Array;
+    };
+    paymentHash: string;
+    refundLocktime: number;
+}
+
+/**
+ * Where a monitored RFQ swap stands, and which of those states end it.
+ *
+ * Its own module rather than a corner of `swapManager.ts` because the
+ * dependency runs the other way: the record layer decides retention from
+ * {@link isRfqSwapTerminal}, and the manager persists through the record
+ * layer. With the vocabulary here, neither has to import the other at runtime.
+ * `swapManager.ts` re-exports all three names, so nothing about the public
+ * surface moved.
+ */
+/**
+ * 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. `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 `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 `RfqSwapManager`.
+ */
+ | "refunded"
+/** Terminal: an action failed and its window closed. */
+ | "failed";
+
+/**
+ * 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.
+     *
+     * True of the three corridors that exist today and only of them: a hashlock
+     * belongs to a CORRIDOR, and a banco-style one settles without any. The
+     * stored record already says so — the hash lives in `profile.hashlock`, not
+     * on `RfqSwapRecord` — and this field follows onto the per-corridor swap
+     * types when the first such corridor lands. Do not read the current shape as
+     * settled.
+     */
+    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. */
+    refundTxid?: string;
+    /**
+     * The ark transactions that SPENT the lockup, stamped from the chain read
+     * that ended the swap — `LockupFate.spends`, whichever verdict it reached.
+     *
+     * The counterparty's move, on every leg but one: a solver claim on a send,
+     * a solver reclaim on a receive, and — the exception — the trader's own
+     * claim when a receive settles. What they have in common is that no local
+     * action produced them, so nothing else on this record can name them:
+     * {@link refundTxid} names only a push this wallet made, and
+     * `claimTxid` only a submission it made.
+     *
+     * Stamped so a terminal record answers "which transaction ended this" from
+     * storage. Without it the only source is another read of the lockup — a
+     * network round trip per terminal swap, which is what activity correlation
+     * has to pay on the offline-first path where it is least affordable.
+     *
+     * Absent when the swap ended without a chain verdict, or when the indexer
+     * named the checkpoint but not the ark transaction — the same `txid`
+     * `LockupSpend` declares optional, for the same reason.
+     */
+    lockupSpendTxids?: string[];
+    /** Why `state` is `failed`. */
+    failure?: string;
+    /**
+     * Last local claim error while the receive swap is still retryable.
+     *
+     * Distinct from terminal `failure`: this records a claim attempt that failed
+     * before the window closed. If the window later closes without a submitted
+     * claim, it becomes the terminal failure reason.
+     */
+    claimFailure?: 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;
+    /** Where {@link RfqSwapManagerCallbacks.claimOnchain} pays; optional only
+     * so records predating its profile slot still restore. */
+    payoutPkScript?: Uint8Array;
+    /** 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`. */
+    claimTxid?: string;
+}
+
+/**
+ * The swap kinds this projection covers — all three the manager monitors.
+ *
+ * `onchain_send` carries an L1 half nothing else can rebuild. Its Arkade lockup
+ * has a contract row like the others, but the HTLC is Bitcoin L1, not an Arkade
+ * contract, so no row exists for it; and `OnchainHtlc` exposes only derived
+ * values — `address`, `pkScript`, `leaves`, `controlBlocks` — never the
+ * `claimKey`/`refundKey` `onchainHtlcScript` takes as inputs. So they ride in
+ * that corridor's {@link RfqSwapOrigin.profile}, and without them a restored
+ * swap would let its L1 refund window pass unwatched.
+ */
+type PersistableRfqSwap = LightningSendSwap | LightningReceiveSwap | OnchainSendSwap;
+/** The immutable request-time half, and only what EVERY corridor has. Hex for
+ * everything binary, so the record is plain JSON and survives any
+ * structured-clone backend unchanged. */
+interface RfqSwapOrigin {
+    /**
+     * Which corridor this is. Resolves the handler that owns {@link profile};
+     * see `rfqCorridor.ts`.
+     *
+     * The manager's own union, not an open string: `RfqSwapManager` branches on
+     * `kind` to decide what to drive, so a corridor it does not know could be
+     * persisted and rebuilt here and then never driven — which is the failure
+     * this whole file is arranged to make impossible.
+     */
+    kind: PersistableRfqSwap["kind"];
+    /**
+     * The Arkade address that was funded.
+     *
+     * Both the swap's handle on its covenant — {@link lockupContractParams}
+     * looks the contract row up by the script it decodes to — and, being taken
+     * from the entry point rather than re-derived, the check that the
+     * parameters a caller supplies belong to THIS swap.
+     */
+    lockupAddress: string;
+    /**
+     * The corridor's own half, as plain JSON — written by the caller from the
+     * request result, kept current by the handler's `project`.
+     *
+     * Opaque here on purpose. Nothing in this file, the repository or the
+     * IndexedDB store interprets it, which is what lets a new corridor ship
+     * without touching any of them. It carries the corridor's keys as well as
+     * its state: `signer` (which wallet key signs this leg) and, on a corridor
+     * locked to a preimage, `hashlock` — see `rfqProfileParts.ts`, and write
+     * both with `rfqSecretsProfile` rather than by hand.
+     *
+     * Not a consumer scratchpad: every write merges it as `{ ...profile,
+     * ...handler.project(swap) }`, so a consumer key colliding with one the
+     * handler projects is silently overwritten on every pass.
+     */
+    profile: Record<string, unknown>;
+    /** Consumer display metadata. The rebuild ignores it — `RfqSwapCommon`
+     * carries no amount of its own. */
+    amount?: number;
+    /**
+     * The ark transaction that funded {@link lockupAddress}.
+     *
+     * Origin, not manager state: the caller broadcasts the funding and knows
+     * its txid, while the manager watches the lockup by script and never
+     * learns it. So it is written once at record creation, like {@link amount},
+     * and no corridor `project` emits it.
+     */
+    fundingTxid?: string;
+}
+/** The stored record: the origin plus the manager's mutable state. */
+interface RfqSwapRecord extends RfqSwapOrigin {
+    rfqId: string;
+    state: RfqSwapState;
+    createdAt: number;
+    updatedAt: number;
+    refundTxid?: string;
+    /** The ark transactions that spent the lockup, stamped by the manager from
+     * the chain read that ended the swap. See
+     * `RfqSwapCommon.lockupSpendTxids`. */
+    lockupSpendTxids?: string[];
+    failure?: string;
+    /** Last local receive-claim error while the swap is still retryable. */
+    claimFailure?: string;
+    blockedReason?: string;
+}
+
+declare const ATOMIC_DECIMAL: unique symbol;
+/** Atomic units written out: the form records and the wire hold. */
+type AtomicDecimal = string & {
+    readonly [ATOMIC_DECIMAL]: true;
+};
+
+/**
+ * Asset identity for the v2 client: CAIP-19 with the rail as the CAIP-2
+ * namespace — `<rail>:<network>/<asset-ns>:<reference>`.
+ *
+ * The rail is the namespace rather than the settlement chain because sameness
+ * across rails is then a comparison on the asset part instead of a shared
+ * string: `arkade:bitcoin/slip44:0` and `bitcoin:bitcoin/slip44:0` are one BTC
+ * on two rails, and nothing has to agree on a single id for them. Arkade has no
+ * CAIP-2 namespace and no bitcoin-chain identity to nest under, so
+ * `bip122:…/arkade:…` would assert a relationship it does not have.
+ *
+ * These ids parse under CAIP-19 and resolve under no published namespace spec:
+ * `arkade`, `bitcoin` and `bolt11` are registered in no CASA registry. That is
+ * the price of naming rails instead of chains, and it costs nothing here — this
+ * module is the grammar, and what an id *means* is the alias layer's job.
+ */
+
+/**
+ * A CAIP-2 namespace this client can spell. Closed rather than open to the
+ * CAIP-2 character class, so a rail nobody implements is a parse failure here
+ * rather than a lookup miss three layers down.
+ *
+ * `bolt11` is lightning: CAIP-2 caps a namespace at eight characters, which
+ * `lightning` overruns, and floors it at three, which `ln` misses. It names the
+ * instrument the rail carries today; BOLT12 is a separate corridor when it
+ * ships.
+ *
+ * `eip155` is grammar and nothing else. §9's EVM corridor is deferred, and §9
+ * exists to prove the seams hold, so its own examples have to parse; the
+ * refusal belongs where a route is chosen, not where a string is read, and the
+ * alias layer is where it happens.
+ */
+declare const RAILS: readonly ["arkade", "bitcoin", "bolt11", "eip155"];
+type Rail = (typeof RAILS)[number];
+/** The rails whose CAIP-2 reference is a bitcoin network rather than a chain id. */
+declare const BITCOIN_RAILS: readonly ["arkade", "bitcoin", "bolt11"];
+type BitcoinRail = (typeof BITCOIN_RAILS)[number];
+/**
+ * The network half of a bitcoin-family chain part: core's own
+ * {@link NetworkName}, because the wallet is the only source of the network —
+ * v2 accepts no server URL anywhere — and this is the vocabulary a wallet
+ * resolves to.
+ *
+ * It is one wider than discovery's `NETWORKS`, which omits `testnet`. That
+ * difference belongs to the alias layer and not to the grammar: an asset on
+ * testnet exists whether or not anyone publishes a market index for it, so
+ * amputating the identity to match the index would make a network the SDK fully
+ * supports unnameable.
+ */
+type NetworkRef = NetworkName;
+type BitcoinAssetId<R extends BitcoinRail> = `${R}:${NetworkRef}/${string}:${string}`;
+/**
+ * A public asset id.
+ *
+ * A template literal type and not `string`, which is what makes the other three
+ * asset spellings in this package — core's 68-hex `asset.AssetId#toString()`,
+ * discovery's `AssetInfo.id`, the RFQ leg's `arkade:BTC` — a compile error in a
+ * slot that wants a public id, rather than a wrong pair string three layers
+ * down. The rail parameter carries that further: `AssetId<"arkade">` accepts no
+ * `bitcoin:` string, which is what makes an endpoint whose corridor and asset
+ * disagree a compile error (see `route.ts`).
+ *
+ * Deliberately not branded — `client.quote({ give: "arkade:bitcoin/slip44:0" })`
+ * must stay writable, and the spec's own examples are written that way — so the
+ * shape is what the type checks and {@link parseAssetId} is the gate for
+ * everything else. A value out of a record or off the wire is a `string`: parse
+ * it, never cast it.
+ */
+type AssetId<R extends Rail = Rail> = R extends BitcoinRail ? BitcoinAssetId<R> : `eip155:${number}/${string}:${string}`;
+
+/**
+ * The corridor axis, and its bijection with the rail namespaces.
+ *
+ * One axis, two vocabularies: discovery speaks `arkade | lightning | onchain`
+ * and an asset id's CAIP-2 namespace is `arkade | bolt11 | bitcoin`. They agree
+ * on one member of three. Collapsing them was the alternative and it loses
+ * either way — take the rail names and every market lookup translates on the
+ * way out to discovery; take the corridor names and `lightning:` overruns
+ * CAIP-2's eight-character namespace cap.
+ *
+ * So both stay, and the disagreement is spent once, here: `Corridor` is
+ * discovery's type verbatim, {@link railOfCorridor} is total, and `route.ts`
+ * ties an endpoint's corridor to its asset's rail in the type system so the two
+ * cannot disagree in a value.
+ */
+
+/**
+ * The corridor a leg settles on.
+ *
+ * Aliased from discovery rather than re-declared: it is discovery's vocabulary,
+ * the alias layer has to speak it, and a re-declaration would drift silently
+ * the day discovery adds a corridor.
+ */
+type Corridor = Corridor$1;
+/**
+ * A corridor id: the three implemented corridors plus §9's EVM chains.
+ *
+ * The template arm stays open against the registry's closed enum on purpose —
+ * which chains a registry lists is a listing decision, not an id-grammar one.
+ */
+type CorridorId = Corridor | `eip155:${number}`;
+
+/**
+ * The two string aliases the v2 surface is written in.
+ *
+ * Aliases rather than branded types: they document what a field carries at the
+ * places §3.1's `Quote` reads (`lock.hash`, `solver`) without making every
+ * literal go through a constructor. Core exports neither, so nothing here is a
+ * duplicate.
+ */
+/** Lowercase hex, no `0x` prefix — the encoding `@scure/base`'s `hex` emits. */
+type Hex = string;
+/** A secp256k1 public key as {@link Hex}: x-only (32 bytes) or compressed (33). */
+type Pubkey = Hex;
+
+/**
+ * What a quote is: the order, fully resolved, plus the provenance that says who
+ * priced it and where that card came from.
+ *
+ * M1 named these shapes and left them to whichever milestone decided their
+ * semantics; this is that milestone, so `QuoteId`, `QuoteInput`, `Quote`,
+ * `MarketRef` and `AuctionProvenance` are declared here rather than beside the
+ * types they are built out of. Nothing in this module has behaviour — the quote
+ * path assembles these, `accept()` (M4) consumes them.
+ *
+ * The one rule worth restating at the top: a `Quote` is binding terms plus the
+ * evidence for them. Every field is either something the caller must act on
+ * (the two obligations, the artifact, the deadline) or something they must be
+ * able to audit afterwards (the market, the solver, the checks that passed).
+ * Nothing internal rides along — no covenant, no secret, no transport.
+ */
+
+/**
+ * A quote's identity, minted by the client at quote time.
+ *
+ * Client-minted everywhere, not just where the wire offers no id: a feed-priced
+ * offer quote has no solver-minted id at all, and `accept()` is idempotent by
+ * quote id *and only* by quote id (§3.2), so an identity that exists on one
+ * backend and not the other could not carry that rule. An alias rather than a
+ * brand, matching `Hex` and `Pubkey` beside it.
+ */
+type QuoteId = string;
+/** Which backend priced a quote. The card decides it; no client switch does. */
+type MarketBackend = "rfq" | "feed";
+/** Where a snapshot came from, and how fresh it is. */
+interface SnapshotRef {
+    /** Unix ms the markets were read from their sources. */
+    readonly fetchedAt: number;
+    /**
+     * The registry answered in this read, so the cards are registry-served
+     * rather than replayed out of local storage.
+     *
+     * `false` is not an error: a stale snapshot still resolves and still prices
+     * a feed-priced quote — it is marked, not refused. What it cannot do is
+     * supply the key an addressed RFQ's responder is checked against, because
+     * that field is unvalidated cache content (`isMarketShaped` revalidates
+     * four fields and trusts the rest).
+     */
+    readonly live: boolean;
+    /** How the markets were obtained. */
+    readonly source: "live" | "cache" | "injected";
+    /** The registry URL behind it, or `undefined` for an injected snapshot. */
+    readonly registry?: string;
+}
+/**
+ * Which card priced a quote, and from which registry.
+ *
+ * A union rather than a bag of optionals, because §10's published RFQ is the
+ * one place the sentence "the market picks the backend" stops: a quote closed
+ * out of an open auction has a market *key* and no card behind it, so every
+ * card-derived field is absent at once rather than one at a time. Sizing that
+ * arm now costs a discriminant and keeps the addressed arm total.
+ */
+type MarketRef = CardMarketRef | AuctionMarketRef;
+interface CardMarketRef {
+    readonly kind: "card";
+    /**
+     * The canonical market key, `<corridor>:<id>/<corridor>:<id>`, derived under
+     * rfq-protocol.md §2's leg order — arkade first when exactly one leg is
+     * arkade, lexicographic otherwise — and never read off the card's own
+     * base/quote order. The two agree for every card the registry's reducer
+     * validated, and a card published outside it is exactly where the silent
+     * miss lives.
+     */
+    readonly key: string;
+    readonly backend: MarketBackend;
+    /** The registry URL, or the label a locally pinned card was loaded under. */
+    readonly source: string;
+    readonly sourceType: "registry" | "local";
+    /** The solver's name, as the card publishes it. Display, never identity. */
+    readonly solver: string;
+    /** The card's signing key. Absent on spot cards, which need no rendezvous. */
+    readonly discoveryPubkey?: Pubkey;
+    /** The card's display label, e.g. `BTC/lightning:BTC`. Display only. */
+    readonly pair: string;
+    readonly snapshot: SnapshotRef;
+}
+/** §10, reserved: a quote closed out of a published auction has no card. */
+interface AuctionMarketRef {
+    readonly kind: "auction";
+    readonly key: string;
+    readonly backend: "rfq";
+}
+
+/**
+ * What survives a crash, and the public shape `accept()` hands back.
+ *
+ * Two types, one key. {@link SwapRecord} is the storage form — JSON-safe by
+ * declaration, every amount a canonical decimal string — and {@link Swap} is the
+ * answer a caller reads, with `bigint` amounts and the resolved `Route`. The
+ * conversion between them is §D's record-boundary codec, and it is not a third
+ * law: `toAtomicDecimal`/`fromAtomicDecimal` already ship in `./amount`, minted
+ * by M1 and used by M3's wire adapter, so both sites emit the same canonical
+ * form — atomic units, unsigned, no leading zeros, never a scaled display
+ * decimal.
+ *
+ * **The key is the quote id, on every route.** That is what makes persist-first
+ * representable at all: v1's `AssetSwap.id` *is* the funding txid
+ * (`store.ts:70-71`), so a record could not exist before the money did, and
+ * `coverage.ts` carries a process-local issuance mark precisely to paper over
+ * the gap. Here the record precedes the funding and `fundingTxid` is a later,
+ * best-effort write.
+ *
+ * **JSON-safe means no `bigint` anywhere, at any depth.** The SQLite and Realm
+ * backends `JSON.stringify` the record whole, so a `bigint` throws on two
+ * backends and round-trips on the third — the asymmetry
+ * `test/repository.test.ts` refuses to paper over. Every amount here is an
+ * {@link AtomicDecimal}; `test/client/record.types.ts` proves the absence
+ * structurally rather than by review.
+ */
+
+/**
+ * Which family a record belongs to, and the discriminant M5's `RawState` keys
+ * on.
+ *
+ * Not a cosmetic tag. v1's two families occupied one `string` id space by
+ * accident — an offer record's id a funding txid, a corridor record's an
+ * `rfqId` — and keying both on `QuoteId` closes that collision (§B). The tag is
+ * what M6's public id carries, and what lets M5 branch its outcome table
+ * without a repository read.
+ */
+type SwapFamily = "offer" | "rfq";
+/** One leg's obligation, in the form a record holds it. */
+interface RecordedLeg {
+    readonly asset: AssetId;
+    /** Atomic units as a canonical decimal string — never a `bigint`. */
+    readonly amount: AtomicDecimal;
+}
+/**
+ * An endpoint as the record holds it: the corridor, the asset, the instrument.
+ *
+ * `Instrument`'s invoice arm carries a `bigint` amount, so it cannot be stored
+ * as declared — {@link RecordedInstrument} is the same union with that one field
+ * in decimal form. The rest is field for field identical, which is what keeps the
+ * comparison in `acceptConflict` honest.
+ */
+interface RecordedEndpoint {
+    readonly corridor: CorridorId;
+    readonly asset: AssetId;
+    readonly instrument: RecordedInstrument;
+}
+/** {@link Instrument}, with the invoice arm's amount in decimal form. */
+type RecordedInstrument = {
+    readonly kind: "wallet";
+} | {
+    readonly kind: "address";
+    readonly address: string;
+} | {
+    readonly kind: "invoice";
+    readonly bolt11: string;
+    readonly paymentHash: Hex;
+    readonly amount?: AtomicDecimal;
+    readonly expiresAt: number;
+};
+/** {@link Artifact}, with the deposit arm's amount in decimal form. */
+type RecordedArtifact = {
+    readonly kind: "invoice";
+    readonly bolt11: string;
+} | {
+    readonly kind: "deposit";
+    readonly corridor: CorridorId;
+    readonly address: string;
+    readonly asset: AssetId;
+    readonly amount: AtomicDecimal;
+    readonly expiresAt?: number;
+};
+/**
+ * The half both families carry.
+ *
+ * Every field is either something `AcceptConflict` compares (§3.2's list), or
+ * something M5 named as a cross-milestone ask, or the two timestamps. Nothing
+ * is here for display: a record carries what no covenant and no chain read can
+ * give back, which is the same rule `RfqSwapRecord` is arranged by.
+ */
+interface SwapRecordCommon {
+    /** The client-minted quote id — the primary key, per C1 and §B. */
+    readonly id: QuoteId;
+    readonly family: SwapFamily;
+    /**
+     * Both endpoints, instruments included — `AcceptConflict` items 1 and 3.
+     *
+     * Nested under `route` so the record's field names are `Quote`'s field
+     * names: the conflict check walks the two shapes together, and a record
+     * that spelled the same fact differently would make every comparison a
+     * translation.
+     */
+    readonly route: {
+        readonly give: RecordedEndpoint;
+        readonly take: RecordedEndpoint;
+    };
+    /** The two obligations — `AcceptConflict` item 2. */
+    readonly give: RecordedLeg;
+    readonly take: RecordedLeg;
+    /** The spread, as the quote precomputed it. */
+    readonly fee: RecordedLeg;
+    /**
+     * Which card priced this, from which registry, how fresh — stored WHOLE.
+     *
+     * A trimmed projection could not rebuild the type {@link Swap.market}
+     * promises: `CardMarketRef` requires `kind`, `pair` and `snapshot` beside
+     * the fields a summary would keep. Every member is a string, number or
+     * boolean, so the union round-trips through JSON untouched, and `snapshot`
+     * is restated as read at accept rather than restamped — a past `fetchedAt`
+     * beside the recorded `live` is the honest answer about how fresh the card
+     * was when this swap was accepted.
+     */
+    readonly market: MarketRef;
+    /**
+     * The committed counterparty, from the quote's covenant role.
+     *
+     * NOT `CardMarketRef.solver`, which is the card's display name. Two
+     * different facts that v1 spelled with one word: this one is a key that
+     * ends up in a covenant leaf, the other is a label. `AcceptConflict`
+     * compares this one.
+     */
+    readonly solver?: Pubkey;
+    /** The quote's own deadline, unix seconds — what makes a stalled accept a
+     * benign abandon rather than a live obligation. */
+    readonly expiresAt: number;
+    /**
+     * The one thing a counterparty must see, when this route has one.
+     *
+     * Durable because a duplicate accept must return the SAME invoice, and the
+     * invoice lives on the quote object — nowhere in the corridor profile. A
+     * caller that re-accepts after a restart has no quote object left, so
+     * without this field the only honest answer would be a second invoice,
+     * which §3.2 forbids by name.
+     */
+    readonly artifact?: RecordedArtifact;
+    /**
+     * The transaction that funded this swap, once known.
+     *
+     * A later, best-effort write, and the field that separates M5's `accepted`
+     * from `funding`. Set-where-absent is a benign resume and never an
+     * `AcceptConflict` — §3.2 says so by name.
+     */
+    readonly fundingTxid?: string;
+    /**
+     * Last local receive-claim error while the swap is still retryable. If the
+     * claim window later closes without a submitted claim, this becomes the
+     * terminal failure reason after restore.
+     */
+    readonly claimFailure?: string;
+    /** Terminal failure reason. */
+    readonly failure?: string;
+    /** Refusal reason while `state` is `needs_counterparty`. */
+    readonly blockedReason?: string;
+    /** Unix **seconds**, both — the unit `RfqSwapRecord` carries and
+     * `shouldRetainRfqSwap` compares against, not `AssetSwap`'s milliseconds. */
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+/**
+ * `arkade <-> arkade`: the offer covenant, and what cancels it.
+ *
+ * `offerHex` is the whole covenant — `cancelOffer` needs nothing else to
+ * rebuild it — so this arm stores no tree parameters of its own.
+ */
+interface OfferSwapRecord extends SwapRecordCommon {
+    readonly family: "offer";
+    /** v1's raw status vocabulary, which M5's `RawState` reads verbatim. */
+    readonly status: AssetSwapStatus;
+    /** The TLV offer, hex. The only input `cancelOffer` needs. */
+    readonly offerHex: string;
+    readonly swapAddress: string;
+    /** The covenant's scriptPubKey, hex — the indexer's monitoring key, and
+     * what §F's reconcile matches a discovered deposit against. */
+    readonly swapPkScript: string;
+    readonly spentTxid?: string;
+    readonly completedAt?: number;
+}
+/**
+ * The three corridor routes: a VHTLC lockup, its clocks and its secrets.
+ *
+ * **No covenant tree here.** Every lockup registers a contract row before its
+ * address can be funded, and that row already holds the parameters, keyed by
+ * the script they derive — a key `createContract` refuses to write unless the
+ * params reproduce it. Storing the tree a second time would be two sources for
+ * one covenant. `accept()` is what writes that row (see `./accept.ts`), which
+ * is why a persisted record always has one.
+ */
+interface CorridorSwapRecord extends SwapRecordCommon {
+    readonly family: "rfq";
+    /** v1's raw state vocabulary, read verbatim by M5's `RawState`. */
+    readonly state: RfqSwapState;
+    /**
+     * Which corridor, in the manager's own vocabulary.
+     *
+     * `PersistableRfqSwap["kind"]` rather than a `Corridor`: it is a route pair
+     * — `lightning_send` and `lightning_receive` are one corridor from opposite
+     * ends — and it is what resolves the handler that owns {@link profile}.
+     */
+    readonly kind: PersistableRfqSwap["kind"];
+    /** The solver's own id for the negotiation, echoed back on the wire. */
+    readonly rfqId: string;
+    /** The Arkade address that was funded, and the swap's handle on its
+     * covenant row. */
+    readonly lockupAddress: string;
+    /** Its pkScript, hex — the row's key, and §F's matching key. */
+    readonly lockupPkScript: string;
+    /** The hash both covenants commit to. `sha256(P)`, hex. */
+    readonly lock: {
+        readonly hash: Hex;
+    };
+    /** When the trader's value comes back if the swap does not complete. */
+    readonly refundLocktime: number;
+    /**
+     * The corridor's own half, as plain JSON.
+     *
+     * v1's opaque bag (`rfqRecord.ts:108-123`), written with `rfqSecretsProfile`
+     * and read by `rfqCorridorHandlers.hydrate` — reused rather than
+     * reinvented, so M5 rebuilds through machinery that already exists and a new
+     * corridor still ships without touching this file. It is also what carries
+     * `expectedAmount`, the claim value gate's request-time input.
+     *
+     * Amounts inside it follow v1's shapes (`expectedAmount` is a `number`),
+     * which is JSON-safe and therefore fine: the decimal-string law governs
+     * this record's OWN amount fields, not the bag it carries forward.
+     *
+     * **This is also where the swap's secrets live** — `profile.signer` and,
+     * on a leg locked to a preimage, `profile.hashlock`. Deliberately not a
+     * second copy at the record's top level: `rfqClaimSecretOf` and
+     * `preimageForSwapRecord` already read them from here, and two homes for
+     * one claim secret is two things to keep in step with one of them always
+     * empty. At most one of `preimageHex`/`preimageSaltHex` is ever written,
+     * and which arm exists is decided by the wallet's provisioning result, not
+     * here.
+     */
+    readonly profile: Record<string, unknown>;
+    readonly refundTxid?: string;
+    readonly lockupSpendTxids?: readonly string[];
+}
+/** Everything `accept()` persists, both families in one key space. */
+type SwapRecord = OfferSwapRecord | CorridorSwapRecord;
+
+/** A registry discovery result held for reuse. Refetchable — unlike a swap
+ * record, losing it costs one network round trip — but it must survive a cold
+ * boot: serving it stale is what keeps quoting alive while a registry is down. */
+interface MarketsCacheEntry {
+    markets: DiscoveredMarket[];
+    fetchedAt: number;
+}
+/**
+ * Everything the package persists, following the monorepo repository
+ * convention: versioned interface, AsyncDisposable, one backend per platform.
+ * Consumers construct exactly one of these; there is no second storage seam.
+ *
+ * Durable records (swaps) and rebuildable state (the restore scan's txid
+ * cursor, the markets cache) live side by side because they share a
+ * lifetime: all three belong to one wallet on one device, and a consumer
+ * that wipes one wants all three gone.
+ *
+ * ponytail: no query filters — every consumer reads all swaps and filters
+ * in memory; add a filter type when a consumer needs subset queries.
+ */
+interface AssetSwapRepository extends AsyncDisposable {
+    /** 5 adds the v2 swap-record store — one row per accepted swap, keyed by
+     * the client-minted quote id. 4 added `getRfqSwap`; 3 added the other RFQ
+     * methods below; 2 was the released shape — swaps, scan cursor, markets,
+     * with `preimageSaltHex` on the swap record — so an implementor built
+     * against any of them cannot satisfy this one silently. */
+    readonly version: 5;
+    /** Insert or replace a swap by id. Store the record whole: `preimageHex`
+     * and `preimageSaltHex` both leave the swap unclaimable if a field-mapped
+     * backend drops them — the first is the only claim secret of a swap whose
+     * signer cannot derive, the second the public input every other static
+     * wallet's preimage derives from.
+     *
+     * Records must be **JSON-safe**: the SQLite and Realm backends serialize
+     * the record to JSON, so a `Date` in a consumer-added field comes back a
+     * string, a `Set`/`Map` comes back empty, and a `bigint` throws here —
+     * none of which happens on IndexedDB's structured clone. `AssetSwap` as
+     * declared is JSON-safe; keep added fields that way. */
+    saveSwap(swap: AssetSwap): Promise<void>;
+    /** All stored swaps, in no particular order — `getAssetSwaps` is the
+     * canonical newest-first read. */
+    getAllSwaps(): Promise<AssetSwap[]>;
+    /**
+     * Insert or replace a monitored RFQ swap by `rfqId`.
+     *
+     * Store the record WHOLE. Every field is a covenant tree parameter or the
+     * manager's own state, and a field-mapped backend that drops one round-trips
+     * a record whose covenant `rebuildRfqSwap` cannot reproduce — which surfaces
+     * as a refund that cannot be signed, long after the write.
+     */
+    saveRfqSwap(record: RfqSwapRecord): Promise<void>;
+    /** One record by key. `undefined` on a miss — retention prunes terminal
+     * records, so absence is ordinary and not an error. */
+    getRfqSwap(rfqId: string): Promise<RfqSwapRecord | undefined>;
+    /** Every stored RFQ swap record, in no particular order. */
+    getAllRfqSwaps(): Promise<RfqSwapRecord[]>;
+    /** Drop one, once it is past retention — see `shouldRetainRfqSwap`. */
+    removeRfqSwap(rfqId: string): Promise<void>;
+    /**
+     * Insert or replace a v2 swap record by its quote id.
+     *
+     * The store the v2 client's `accept()` writes, and the reason this
+     * interface is at 5. Separate from `swaps` rather than sharing it: the v1
+     * read path drops any row carrying neither `offerHex` nor `paymentHash`
+     * (`getAssetSwapsOrThrow`), silently and as corrupt, so a v2 record in that
+     * store would be pinned by a v1 predicate — and the two histories are meant
+     * to be disjoint for the deprecation window anyway. A v1 reader not seeing
+     * v2 rows is the design, asserted in the conformance suite rather than
+     * tolerated.
+     *
+     * Store the record WHOLE, and note that it is **JSON-safe by declaration**:
+     * every amount on it is a canonical decimal string, precisely so the SQLite
+     * and Realm backends' `JSON.stringify` and IndexedDB's structured clone
+     * agree. A `bigint` reaching here would throw on two backends and
+     * round-trip on the third.
+     */
+    saveSwapRecord(record: SwapRecord): Promise<void>;
+    /** One record by quote id. `undefined` on a miss — which is the ordinary
+     * answer for a first `accept()`, and what makes it idempotent. */
+    getSwapRecord(id: string): Promise<SwapRecord | undefined>;
+    /** Every stored v2 record, in no particular order. */
+    getAllSwapRecords(): Promise<SwapRecord[]>;
+    /** Drop one, once it is past retention. */
+    removeSwapRecord(id: string): Promise<void>;
+    /**
+     * Sent txids already checked for offer packets (see restore.ts).
+     *
+     * **Shared across both record families, deliberately.** This is not
+     * record-family data — it marks txids of transactions a scan has answered,
+     * whatever family a later record belongs to — and both families walk the
+     * same sent-txid set during the deprecation window. Two cursors would have
+     * each side re-walking deposits the other already answered.
+     */
+    getScannedTxids(): Promise<Set<string>>;
+    markTxidsScanned(txids: Iterable<string>): Promise<void>;
+    /** Cached registry markets, or undefined on a miss. Shared across both
+     * record families for the reason the cursor is: the key is network-and-
+     * registry, not a store, and two caches would serve two staleness clocks
+     * for one registry. */
+    getCachedMarkets(network: string, registry: string): Promise<MarketsCacheEntry | undefined>;
+    saveCachedMarkets(network: string, registry: string, entry: MarketsCacheEntry): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/**
+ * An executor that owns its connection.
+ *
+ * `SQLExecutor` declares no lifecycle — the interface is three query methods,
+ * because every other implementation wraps a connection the consumer already
+ * opened. This one opens the file itself, so it is the one that has something
+ * to close.
+ */
+interface NodeSqlExecutor extends SQLExecutor {
+    /** Close the underlying database handle. Idempotent. */
+    close(): Promise<void>;
+}
+/**
+ * Open (creating if absent) a SQLite database at `path`.
+ *
+ * **One instance per file, held for the process's life.** `runInTransaction`
+ * keys its write chain on the executor *object* through a `WeakMap`, so a
+ * second executor over the same file forks the chain and two "transactions" can
+ * interleave on one connection. Every repository on a database must be handed
+ * the same instance — which is what {@link nodeSwapRepository} does for the
+ * common case.
+ *
+ * The parent directory is created on open: the config dir exists on any real
+ * machine but `arkade/swaps` under it does not, and failing on a first run for
+ * a directory the caller never chose would be a poor default.
+ */
+declare const createNodeSqlExecutor: (path: string) => NodeSqlExecutor;
+interface NodeSwapRepositoryOptions {
+    /**
+     * Which network's database. Used to build the default path — pass the same
+     * name the wallet reports.
+     */
+    readonly network: string;
+    /** An explicit path, overriding the platform default. */
+    readonly path?: string;
+    /** Table-name prefix, passed through to the SQLite backend. */
+    readonly prefix?: string;
+}
+/**
+ * The Node storage default, connection included.
+ *
+ * This is where D1/D2's ownership rule lands: the returned repository's
+ * `[Symbol.asyncDispose]` closes the connection **it** opened, and an injected
+ * repository is disposed by whoever built it — which is already true of every
+ * other backend, whose disposal is a no-op precisely because the consumer owns
+ * the handle.
+ *
+ * Hanging ownership on the repository rather than on a client lifecycle method
+ * is deliberate: the v2 client has no `stop()` or `dispose()` yet — the
+ * lifecycle is the next milestone's — and a connection that could only be
+ * closed through a method that does not exist would leak until the process
+ * ended.
+ *
+ * ```ts
+ * await using repository = nodeSwapRepository({ network: "mainnet" });
+ * const client = createSwapClient({ wallet, repository });
+ * ```
+ */
+declare const nodeSwapRepository: (options: NodeSwapRepositoryOptions) => AssetSwapRepository;
+
+export { type NodeSqlExecutor, type NodeSwapRepositoryOptions, configDir, createNodeSqlExecutor, nodeSwapRepository, swapDatabasePath };