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

package/dist/{repository-DlLvj_y6.d.ts → repository-oeW8KZo1.d.cts}

@@ -1,6 +1,6 @@
-import { DiscoveredMarket } from '@arkade-os/solver-discovery';
-import { IWallet, ProvisionedKey, ProvisionedClaimSecret, RestArkProvider, RestIndexerProvider, VHTLC, Identity, IContractManager } from '@arkade-os/sdk';
-import { B as RfqStatus, R as RfqTransport, a as OnchainHtlc, f as ChainUtxo, C as ChainSource, v as OnchainHtlcPhase } from './rfq-DzsmhXX3.js';
+import { Corridor as Corridor$1, DiscoveredMarket } from '@arkade-os/solver-discovery';
+import { IWallet, ProvisionedKey, ProvisionedClaimSecret, ArkProvider, RestIndexerProvider, VHTLC, Identity, IContractManager, NetworkName } from '@arkade-os/sdk';
+import { D as RfqStatus, R as RfqTransport, a as OnchainHtlc, g as ChainUtxo, C as ChainSource, w as OnchainHtlcPhase } from './rfq-D0KGjmnn.cjs';
 
 type AssetSwapStatus = "pending" | "cancelling" | "fulfilled" | "cancelled" | "recoverable" | "awaiting_fill" | "claimable" | "claimed" | "refunded_l1";
 /** The sentinel asset id for BTC itself, as opposed to a 68-hex asset id.
@@ -210,10 +210,17 @@ declare function awaitRfqResolution(transport: RfqTransport, rfqId: string, opti
     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. */
+/**
+ * What a push needs from the operator: the broadcast pair, plus the info read
+ * that supplies `checkpointTapscript`.
+ *
+ * Narrow on purpose. A wallet's own connection satisfies it —
+ * `getArkadeBroadcaster()` for the pair and `getArkadeInfo()` for the read — so
+ * a plugin composes one from the wallet it already has and never opens a second
+ * connection of its own (#734). A full `ArkProvider` still fits, structurally.
+ */
+type SwapOperator = Pick<ArkProvider, "getInfo" | "submitTx" | "finalizeTx">;
 type RefundIndexer = Pick<RestIndexerProvider, "getVtxos">;
 /** A still-refundable virtual output sitting at the swap lockup. */
 interface LockupVtxo {
@@ -237,12 +244,6 @@ interface LockupVtxo {
      * Opposite, but not exhaustive: an unrolled output satisfies neither, and
      * {@link findLockupVtxos} drops those before they reach this type at all.
      *
-     * `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
@@ -260,8 +261,7 @@ interface LockupVtxo {
  *
  * **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
+ * `IVtxoManager.recoverVtxos()`. 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 —
@@ -278,8 +278,7 @@ interface LockupVtxo {
  *   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".
+ *   this output.
  */
 declare class LockupNeedsRecoveryError extends Error {
     readonly name = "LockupNeedsRecoveryError";
@@ -292,11 +291,10 @@ declare class LockupNeedsRecoveryError extends Error {
      * 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.
+     * Exposed as a value, not only inside the message, so a caller can skip
+     * pre-CLTV recoverable outputs 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);
@@ -315,8 +313,7 @@ declare class LockupNeedsRecoveryError extends Error {
  * 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`).
+ * like a resolved swap.
  *
  * **Visible is not the same as refundable.** A `recoverable` output cannot be
  * spent offchain at all — see {@link LockupVtxo.recoverable} — so this set is
@@ -370,7 +367,7 @@ interface LockupSpend {
     checkpointTxid: string;
     /** The ark transaction that spent the above checkpoint output. What
      * history correlation matches on; absent when the indexer omitted it. */
-    arkTxid?: string;
+    txid?: string;
 }
 type LockupFate = 
 /** At least one output at the lockup is still unspent. Not over. */
@@ -501,8 +498,8 @@ declare function readLockupFate(indexer: LockupSpendIndexer, input: {
  * 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>;
+declare function pushRefundWithoutReceiver(operator: SwapOperator, input: {
+    contract: InstanceType<typeof VHTLC.ScriptV2>;
     /** The `sender` signer. Build it from the swap record with
      * {@link senderIdentityForSwapRecord} — on an HD wallet that resolves
      * from the seed, with no stored key bytes anywhere, and every way the
@@ -514,7 +511,7 @@ declare function pushRefundWithoutReceiver(ark: RefundArkProvider, input: {
     /** Defaults to the contract's own committed refund destination. */
     refundPkScript?: Uint8Array;
 }): Promise<{
-    arkTxid: string;
+    txid: string;
     amount: number;
 }>;
 /**
@@ -536,7 +533,7 @@ type RefundOutcome =
 /** The trader took it back via `refundWithoutReceiver`. */
  | {
     outcome: "refunded";
-    arkTxid: string;
+    txid: string;
     amount: number;
     status: RfqStatus | null;
 }
@@ -562,7 +559,18 @@ type RefundOutcome =
  * The lockup was unilaterally exited: its outputs sit onchain under the VHTLC
  * script, where no offchain refund can reach them. Returned rather than
  * retried: no amount of waiting changes where the money lives. Complete the
- * unroll and spend the outputs onchain — then there is nothing left to refund.
+ * unroll and spend the named outputs onchain.
+ *
+ * **`outpoints` is not necessarily the whole lockup, and `exited` does not
+ * mean "nothing left to refund".** A lockup funded by more than one UTXO
+ * reports `exited` as soon as ANY of them has been exited, and `outpoints`
+ * names only those; a still-live sibling is left unrefunded, and this call
+ * will not come back for it — the outcome is terminal, so the caller's retry
+ * loop ends here. That is deliberate rather than an oversight: `RfqSwapManager`
+ * reports the same lockup `exited` on the same any-output rule, and the two
+ * must not disagree. It does make the surviving outputs the caller's to
+ * pursue, through an independent onchain or offchain recovery path that this
+ * function will not reach.
  *
  * Distinct from {@link RefundOutcome} `needs_recovery` on purpose: that
  * variant's remedy is recovery into a fresh batch, which is a spend no batch
@@ -619,9 +627,9 @@ type RefundOutcome =
  * 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: LockupSpendIndexer, input: {
+declare function refundIfUnresolved(transport: RfqTransport, operator: SwapOperator, indexer: LockupSpendIndexer, input: {
     rfqId: string;
-    script: InstanceType<typeof VHTLC.ScriptV2>;
+    contract: InstanceType<typeof VHTLC.ScriptV2>;
     /** @see pushRefundWithoutReceiver */
     sender: Identity;
     /**
@@ -787,7 +795,7 @@ interface RfqSwapCommon {
     createdAt: number;
     updatedAt: number;
     /** Set once the trader's own `refundWithoutReceiver` push landed. */
-    refundArkTxid?: string;
+    refundTxid?: string;
     /**
      * The ark transactions that SPENT the lockup, stamped from the chain read
      * that ended the swap — `LockupFate.spends`, whichever verdict it reached.
@@ -796,8 +804,8 @@ interface RfqSwapCommon {
      * 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 refundArkTxid} names only a push this wallet made, and
-     * `claimArkTxid` only a submission it made.
+     * {@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
@@ -805,12 +813,20 @@ interface RfqSwapCommon {
      * 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 `arkTxid`
+     * named the checkpoint but not the ark transaction — the same `txid`
      * `LockupSpend` declares optional, for the same reason.
      */
-    lockupSpendArkTxids?: string[];
+    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;
@@ -875,7 +891,7 @@ interface LightningReceiveSwap extends RfqSwapCommon {
     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;
+    claimTxid?: string;
 }
 /**
  * A monitored swap.
@@ -886,8 +902,8 @@ interface LightningReceiveSwap extends RfqSwapCommon {
  * writes and rebuilds these itself, through
  * {@link RfqSwapManager.restoreFromRepository}. A caller keeping its own store
  * projects it in {@link RfqSwapManagerCallbacks.saveSwap} instead, rebuilds it
- * on restart the way it was made — `lightningSendVtxoScript` /
- * `receiveVtxoScript` / `onchainHtlcScript` over the quote's binding fields —
+ * on restart the way it was made — `lightningSendContract` /
+ * `lightningReceiveContract` / `onchainHtlcScript` over the quote's binding fields —
  * and hands the result to {@link RfqSwapManager.start}.
  *
  * **`onchain:BTC->arkade:BTC` is deliberately not a member yet.** Its Arkade
@@ -945,7 +961,7 @@ declare function nextOnchainAction(input: {
 /** What the trader's own `refundWithoutReceiver` push returned, or `null` when
  * the lockup held nothing to return. */
 type ArkadeRefundResult = {
-    arkTxid: string;
+    txid: string;
     amount: number;
 } | null;
 /**
@@ -996,7 +1012,7 @@ interface RfqSwapManagerCallbacks {
          * funding that arrived piecemeal can still be swept. */
         partiallyClaimed: boolean;
     }) => Promise<{
-        arkTxid: string;
+        txid: string;
         amount: number;
     }>;
     /**
@@ -1110,7 +1126,7 @@ interface RfqSwapManagerConfig {
 }
 /** 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
+ * `RefundIndexer`, and satisfied structurally by a real
  * `ContractManager` (`await wallet.getContractManager()`). */
 type SwapContractRegistry = Pick<IContractManager, "createContract" | "getContracts" | "onContractEvent" | "setContractWatchState">;
 /**
@@ -1311,20 +1327,6 @@ declare class RfqSwapManager {
      * 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.
@@ -1490,6 +1492,17 @@ declare class RfqSwapManager {
     removeSwap(rfqId: string): Promise<void>;
     /** Every swap still being monitored. */
     getPendingSwaps(): Promise<RfqSwap[]>;
+    /**
+     * Every swap this manager holds — {@link getPendingSwaps} plus the ones
+     * that already ended. The two sets are disjoint: a swap leaves `monitored`
+     * as it enters `finished`.
+     *
+     * The finished half is what this process has seen, which after
+     * {@link restoreFromRepository} is the stored history minus what retention
+     * pruned. A manager that has restored nothing answers with the live swaps
+     * alone.
+     */
+    getAllSwaps(): Promise<RfqSwap[]>;
     hasSwap(rfqId: string): Promise<boolean>;
     /** True while an action for this swap holds the per-swap lock. */
     isProcessing(rfqId: string): Promise<boolean>;
@@ -1651,7 +1664,7 @@ declare class RfqSwapManager {
     /**
      * Record which ark transactions ended the lockup.
      *
-     * Only the ones the indexer actually named: `LockupSpend.arkTxid` is
+     * Only the ones the indexer actually named: `LockupSpend.txid` is
      * optional, and a checkpoint txid is not what history correlates on — a
      * record carrying one would name a transaction the wallet's own activity
      * never shows. Fewer txids is the right failure here.
@@ -1695,10 +1708,9 @@ declare class RfqSwapManager {
     /**
      * 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.
+     * `onSwapCompleted` and `onSwapFailed` are mutually exclusive here: a
+     * listener named "completed" that also fires on failure is a trap, so a
+     * swap that leaves monitoring reports through exactly one of them.
      */
     private finalize;
     private settleWaiters;
@@ -1798,7 +1810,7 @@ interface RfqSwapOrigin {
      * learns it. So it is written once at record creation, like {@link amount},
      * and no corridor `project` emits it.
      */
-    fundingArkTxid?: string;
+    fundingTxid?: string;
 }
 /** The stored record: the origin plus the manager's mutable state. */
 interface RfqSwapRecord extends RfqSwapOrigin {
@@ -1806,14 +1818,39 @@ interface RfqSwapRecord extends RfqSwapOrigin {
     state: RfqSwapState;
     createdAt: number;
     updatedAt: number;
-    refundArkTxid?: string;
+    refundTxid?: string;
     /** The ark transactions that spent the lockup, stamped by the manager from
      * the chain read that ended the swap. See
-     * `RfqSwapCommon.lockupSpendArkTxids`. */
-    lockupSpendArkTxids?: string[];
+     * `RfqSwapCommon.lockupSpendTxids`. */
+    lockupSpendTxids?: string[];
     failure?: string;
+    /** Last local receive-claim error while the swap is still retryable. */
+    claimFailure?: string;
     blockedReason?: string;
 }
+/**
+ * A stored record read under the current field names.
+ *
+ * Four fields were renamed after `0.0.9`: `fundingArkTxid`, `refundArkTxid`,
+ * `lockupSpendArkTxids`, and the receive corridor's `profile.claimArkTxid`. All
+ * four arrived together with record persistence itself in `0.0.8`, so `0.0.8`
+ * and `0.0.9` are the only versions that ever wrote them. Backends store the
+ * record WHOLE, so such a store still holds the old names on disk and the
+ * current code reads every one of them as `undefined`.
+ *
+ * Called by every function here that takes a record, so a consumer needs no
+ * boot-time migration of its own; and because the old keys never reach the
+ * object handed back, the next write persists the record without them.
+ *
+ * What it buys, in descending order of sharpness: a receive leg with a partial
+ * claim already out keeps its `claimTxid`, so the value gate stays disarmed
+ * rather than re-blocking the rest of a lockup whose preimage is public;
+ * `refunded` swaps report an outcome txid again; and activity answers from the
+ * record instead of falling back to a lockup read per query. It is NOT a
+ * re-refund fix — `refunded` is terminal, and `restoreFromRepository` puts a
+ * terminal record straight into `finished` without ever driving it.
+ */
+declare function normalizeRfqSwapRecord(record: RfqSwapRecord): RfqSwapRecord;
 /** First write, at the moment the caller hands the swap to the manager. */
 declare function createRfqSwapRecord(origin: RfqSwapOrigin, swap: PersistableRfqSwap): RfqSwapRecord;
 /**
@@ -1822,8 +1859,9 @@ declare function createRfqSwapRecord(origin: RfqSwapOrigin, swap: PersistableRfq
  * The mutable half is REPLACED, not merged. `managerState` omits a key the live
  * swap no longer carries, so spreading it over the old record could only ever
  * set these fields, never clear them. The manager clears them on purpose: it
- * deletes `blockedReason` when a swap leaves `needs_counterparty`, precisely
- * because a stale `blockedReason` reads as a live refusal.
+ * deletes `blockedReason` when a swap leaves `needs_counterparty` and
+ * `claimFailure` when a swap becomes terminal, precisely because stale mutable
+ * reasons read as live refusal or retry state.
  */
 declare function updateRfqSwapRecord(record: RfqSwapRecord, swap: PersistableRfqSwap): RfqSwapRecord;
 /**
@@ -1832,9 +1870,9 @@ declare function updateRfqSwapRecord(record: RfqSwapRecord, swap: PersistableRfq
  * A record IS an origin plus manager state, so `record` where an
  * {@link RfqSwapOrigin} is wanted type-checks — and is a bug. Spread into
  * {@link createRfqSwapRecord} it carries the OLD state's `failure`,
- * `blockedReason` and `refundArkTxid` past `managerState`, which omits a field
- * the live swap no longer has and therefore cannot clear one. That is the same
- * trap {@link updateRfqSwapRecord} strips those three fields to avoid; this is
+ * `blockedReason`, `claimFailure` and `refundTxid` past `managerState`, which omits
+ * fields the live swap no longer has and therefore cannot clear them. That is the same
+ * trap {@link updateRfqSwapRecord} strips those mutable fields to avoid; this is
  * how a caller holding only a record gets an origin that is safe to keep.
  *
  * What `RfqSwapManager.restoreFromRepository` remembers for each record it
@@ -1869,6 +1907,924 @@ declare function rebuildRfqSwap(record: RfqSwapRecord, params: LockupParams): Pe
  */
 declare function shouldRetainRfqSwap(record: RfqSwapRecord, now: number): boolean;
 
+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 `<asset-ns>:<reference>` half of an id — what sameness compares. */
+type AssetPart = `${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 rail namespace a corridor's assets are spelled on. */
+type RailOf<C extends CorridorId> = C extends "arkade" ? "arkade" : C extends "lightning" ? "bolt11" : C extends "onchain" ? "bitcoin" : "eip155";
+
+/**
+ * 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;
+
+/**
+ * One outcome vocabulary, and the translation that produces it.
+ *
+ * The protocol keeps two state machines — `RfqSwapState` for the corridors and
+ * `AssetSwapStatus` for offers — and v1 handed both to every consumer, who then
+ * wrote `family === "offer" ? swap.status : swap.state` and decided what each
+ * word meant. {@link Outcome} is that decision, made once.
+ *
+ * **The axis is not send-versus-receive: it is whose lockup the pass reads.**
+ * On `arkade -> lightning` and `arkade -> onchain` the arkade lockup is the
+ * trader's, so a non-claim spend of it returns the trader's money. On
+ * `lightning -> arkade` it is the solver's, so the identical chain read means
+ * the trader's incoming payment never arrived. `refunded` and `lapsed` are that
+ * one difference, and the reason this enum refuses to inherit the protocol's
+ * word: on the receive leg the state the wire calls `refunded` is a LOSS.
+ *
+ * The ownership is not restated here. {@link LIGHTNING_DRIVE} and
+ * {@link ONCHAIN_DRIVE} already declare it per route side — that is what M2
+ * minted `CorridorPass` for — so this module reads it off them and a corridor
+ * that changes its mind is a compile error rather than a second table to keep
+ * in step.
+ *
+ * Three outcomes come from neither machine, and they are the record's and the
+ * clock's: `accepted` and `funding` describe a record the drive holds no live
+ * state for, and `refunding` a send leg past its deadline with a push in
+ * flight. All three still carry the raw word their machine holds, because
+ * {@link SwapUpdate.detail} is `RawState` and `RawState` is the raw word.
+ */
+
+/**
+ * What happened to a swap, in one vocabulary for both families.
+ *
+ * Trader-centric by definition. Fourteen members, §3.5's, and the two that
+ * carry the whole point are `refunded` — the trader's value came back — and
+ * `lapsed`, the solver reclaiming a lockup the trader failed to claim.
+ */
+type Outcome = 
+/** Persisted, and its funding has not been broadcast. */
+"accepted"
+/** The funding is broadcast and the drive has not adopted the swap yet. */
+ | "funding"
+/** The trader's lockup is funded and the swap is live. */
+ | "funded"
+/** Waiting on the counterparty: an unpaid invoice, an unfilled offer. */
+ | "open"
+/** An offer covenant was filled. */
+ | "filled"
+/** The trader's own claim is confirmed on chain. */
+ | "claimed"
+/** A lightning send settled: the solver's hash-verified spend IS the
+ * invoice being paid. */
+ | "paid" | "cancelling" | "cancelled"
+/** A send leg past `refundLocktime` with a refund push in flight. */
+ | "refunding"
+/** The trader's value came back. Send legs only, ever. */
+ | "refunded"
+/** A receive leg the trader never claimed: the solver took the lockup back
+ * and the incoming payment never arrived. */
+ | "lapsed"
+/** Surfaced, never silently retried, and never terminal. */
+ | "needs_recovery"
+/** An action failed and its window closed. */
+ | "failed";
+/**
+ * The untranslated protocol word, for support and audit.
+ *
+ * A tagged union over the two families rather than a bare string, so M6's
+ * cancel path reads the family split off the update one lookup earlier than a
+ * repository read. The reason strings are deliberately NOT here: `failure` and
+ * `blockedReason` arrive on the record as fields, not as vocabulary, and
+ * {@link Swap} is where a consumer reads them.
+ *
+ * `wire`, `htlc` and `fate` are the supporting vocabularies a pass consults.
+ * They are declared because the shape is fixed here rather than left to the
+ * first consumer that wants one, and populated by nothing today: the manager
+ * surfaces neither the L1 phase nor the lockup fate on its update callback, and
+ * the solver's own `RfqStatus` is a self-report no drive pass reads at all.
+ */
+type RawState = {
+    readonly family: "rfq";
+    readonly state: RfqSwapState;
+    readonly wire?: RfqStatus["state"];
+    readonly htlc?: OnchainHtlcPhase;
+    readonly fate?: LockupFate;
+} | {
+    readonly family: "offer";
+    readonly status: AssetSwapStatus;
+};
+/** What `onUpdate` delivers. */
+interface SwapUpdate {
+    readonly swap: Swap;
+    readonly outcome: Outcome;
+    readonly detail: RawState;
+}
+/** What every listener registration hands back. */
+type Unsubscribe = () => void;
+
+/**
+ * A route is two endpoints, each an asset on a corridor, plus the instrument
+ * that settles it.
+ *
+ * Two invariants live in the types rather than in a check. An endpoint's
+ * corridor and its asset cannot disagree, because {@link Endpoint} is a union
+ * with one member per corridor and each member types its asset as
+ * {@link AssetOn} of that one corridor. And `onchain -> arkade` is not in
+ * {@link Route} at all, so once a route has been resolved the misroute is a
+ * compile error; before resolution it is `UnsupportedRoute`, thrown ahead of
+ * RFQ disclosure, artifact creation, persistence and funding.
+ */
+
+/**
+ * A leg's concrete settlement locus. Direction comes from give versus take,
+ * never from the instrument.
+ *
+ * `{ kind: "wallet" }` is the only instrument the SDK holds signing authority
+ * over, which is why it is the only one nobody passes: `accept()` spends the
+ * balance and lands the claim on wallet legs and merely watches the others. The
+ * supply law is that the caller provides non-wallet take instruments (that is
+ * what `to` is), the quote provides non-wallet give instruments (that is
+ * exactly what the artifact is), and every remaining slot resolves to `wallet`.
+ *
+ * `wallet` is an explicit variant rather than an absent field because absence
+ * would mean two unrelated things — wallet-by-default and not-yet-resolved —
+ * and a receive leg lives in the second state until the quote returns.
+ */
+type Instrument = {
+    kind: "wallet";
+} | {
+    kind: "address";
+    address: string;
+} | {
+    kind: "invoice";
+    bolt11: string;
+    paymentHash: Hex;
+    amount?: bigint;
+    expiresAt: number;
+};
+/**
+ * The asset ids corridor `C` can carry.
+ *
+ * On the three bitcoin-family corridors the corridor names no network, so the
+ * tie is the rail alone. On an EVM corridor it is more than that: `eip155:8453`
+ * *is* the CAIP-2 chain part its assets are spelled with, so the asset id has to
+ * start with the corridor id verbatim. Enforcing only the rail there would admit
+ * `eip155:1/erc20:…` on a Base corridor — the same near-miss `sameAsset` refuses
+ * one layer up, an address being a chain's fact and not a token's.
+ */
+type AssetOn<C extends CorridorId> = C extends Corridor ? AssetId<RailOf<C>> : `${C}/${AssetPart}`;
+/**
+ * An asset on a corridor, with the instrument that settles it.
+ *
+ * `corridor` is a cross-check rather than an input: every id already carries
+ * its rail. Typing `asset` against that rail is what makes the cross-check free
+ * — there is no value in which the two disagree.
+ *
+ * Distributed over `C` rather than written as one object whose two fields both
+ * mention it: `{ corridor: C; asset: AssetOn<C> }` at `C = CorridorId` widens
+ * *each field independently* to its own union, and correlates nothing —
+ * `{ corridor: "arkade", asset: "bitcoin:…" }` satisfies it. The conditional
+ * makes `Endpoint` the union of the four single-corridor shapes instead, so the
+ * pairing survives the default type argument, which is the case every unwitnessed
+ * `Endpoint` in a signature lands on.
+ */
+type Endpoint<C extends CorridorId = CorridorId> = C extends CorridorId ? {
+    corridor: C;
+    asset: AssetOn<C>;
+    /** Resolved by the client, never constructed by callers. */
+    instrument: Instrument;
+} : never;
+/** Shorthand for one corridor's endpoint, as the route union spells it. */
+type Ep<C extends CorridorId> = Endpoint<C>;
+/**
+ * The implemented routes, as a closed union.
+ *
+ * `onchain -> arkade` is deliberately absent until the manager owns the
+ * trader's L1 refund path end to end.
+ */
+type Route = {
+    give: Ep<"arkade">;
+    take: Ep<"arkade">;
+} | {
+    give: Ep<"arkade">;
+    take: Ep<"lightning">;
+} | {
+    give: Ep<"lightning">;
+    take: Ep<"arkade">;
+} | {
+    give: Ep<"arkade">;
+    take: Ep<"onchain">;
+};
+/**
+ * The one thing a counterparty must see, when a route has one.
+ *
+ * The deposit variant carries no `chain` field. §3.4 reserved one and Q12 made
+ * it redundant: the chain part lives inside `asset`, and a second, untyped
+ * spelling of it is a fact two fields can disagree about with nothing checking.
+ * `corridor` stays because it is the typed axis `route.ts` already ties to the
+ * asset's rail — a cross-check, where `chain?: string | number` was a copy.
+ */
+type Artifact = {
+    kind: "invoice";
+    bolt11: string;
+} | DepositArtifact;
+/**
+ * The deposit half of {@link Artifact}, distributed over the corridor for the
+ * reason {@link Endpoint} is: `corridor` is only a cross-check if a value cannot
+ * spell it against an asset from another corridor.
+ */
+type DepositArtifact<C extends CorridorId = CorridorId> = C extends CorridorId ? {
+    kind: "deposit";
+    corridor: C;
+    address: string;
+    asset: AssetOn<C>;
+    amount: bigint;
+    expiresAt?: number;
+} : never;
+
+/** Which side of the trade an amount pins, in v2's vocabulary. */
+type AmountOn = "give" | "take";
+
+/**
+ * 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;
+/**
+ * A caller's spelling of an asset: a public id, or a ticker the alias layer
+ * canonicalizes against the registry.
+ *
+ * `AssetId | (string & {})` rather than `string`, so an editor still completes
+ * the id form and a mistyped id still shows up as one — `AssetId | string`
+ * collapses to `string` and takes both with it.
+ */
+type AssetRef = AssetId | (string & {});
+/**
+ * Everything a caller supplies. §4's bottom line: two asset ids or one
+ * destination string, one amount, which side it pins, and — on receives, where
+ * no instrument exists yet — a corridor.
+ */
+interface QuoteInput {
+    /** Omitted when the route determines it: the give leg is the wallet's. */
+    give?: AssetRef;
+    /** Omitted when `to` determines it — a corridor that carries BTC only does. */
+    take?: AssetRef;
+    /** A self-describing instrument: bolt11, an Arkade address, or `bc1…`. */
+    to?: string;
+    /** Receive flows only: names the corridor when no instrument can exist yet. */
+    via?: CorridorId;
+    /** Atomic units. Exactly one amount may be pinned — see `amountOn`. */
+    amount?: bigint;
+    /** Which leg `amount` pins. Required with `amount`, and refused with an
+     * invoice, which pins one already. */
+    amountOn?: AmountOn;
+}
+/** 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";
+}
+/**
+ * One bid seen in a published auction (§10, Q9).
+ *
+ * Typed against ts-sdk #777's shipped draft rather than invented: a bid is a
+ * counter-amount on the leg the client did not fix, attributed to the event key
+ * that signed it — which is NOT the covenant's `solver_pubkey`, a role key the
+ * quote fills from a different field.
+ */
+interface RankedBid {
+    /** The event key that signed the bid. Attribution, not a covenant role. */
+    readonly bidder: Pubkey;
+    /** The counter-amount, on the leg the client left free. */
+    readonly amount: bigint;
+    readonly amountOn: AmountOn;
+    readonly expiresAt: number;
+}
+/**
+ * The auction a published-RFQ quote was closed out of (§10, Q9).
+ *
+ * Reserved and inert: `quote()` never populates it, and Q9 froze the name so
+ * the shape it will take cannot be occupied by something else in the meantime.
+ */
+interface AuctionProvenance {
+    /** The market key the open request was tagged with. */
+    readonly marketKey: string;
+    /** The bid that was closed with. */
+    readonly winner: RankedBid;
+    /** Every other bid seen before the window closed. */
+    readonly losers: readonly RankedBid[];
+    /** Unix seconds the bid window closed. */
+    readonly closedAt: number;
+}
+/** One leg's obligation: an asset, and exactly how much of it. */
+interface QuoteLeg {
+    readonly asset: AssetId;
+    readonly amount: bigint;
+}
+/**
+ * The order, fully resolved.
+ *
+ * Both amounts are exact obligations with the fee already inside them, which is
+ * what `fee` restates rather than adds: it is the spread, precomputed, so a
+ * verb (M7) can compare it to a ceiling without re-deriving it from a price.
+ */
+interface Quote {
+    readonly id: QuoteId;
+    /** Both endpoints resolved, instruments included. */
+    readonly route: Route;
+    /** What the trader gives, fee included. */
+    readonly give: QuoteLeg;
+    /** What the trader takes. */
+    readonly take: QuoteLeg;
+    /** Corridor routes: the hash both covenants commit to. */
+    readonly lock?: {
+        readonly hash: Hex;
+    };
+    /** Which card priced this, from which registry, how fresh. */
+    readonly market: MarketRef;
+    /** RFQ routes: the committed counterparty, from the quote's covenant role. */
+    readonly solver?: Pubkey;
+    /** §10 only, and never populated today. */
+    readonly auction?: AuctionProvenance;
+    /** Unix seconds. Non-optional on both backends — a feed-priced quote has no
+     * wire expiry to inherit, so the client mints one from the feed's freshness. */
+    readonly expiresAt: number;
+    /**
+     * Corridor routes: when the trader's value comes back if the swap does not
+     * complete.
+     *
+     * Optional on the type because an asset swap has no refund clock at all —
+     * an offer covenant never expires — and non-optional in practice on every
+     * corridor route, where the wire's own field is optional and the client
+     * refuses a quote without it.
+     */
+    readonly refundLocktime?: number;
+    /** The one thing a counterparty must see, when this route has one. */
+    readonly artifact?: Artifact;
+    /** The spread, denominated on the leg where it is exact. */
+    readonly fee: {
+        readonly amount: bigint;
+        readonly asset: AssetId;
+    };
+}
+/**
+ * An endpoint as `resolve()` can answer for it, before any disclosure.
+ *
+ * Not an `Endpoint`: that type's instrument is non-optional, deliberately, and a
+ * receive leg has none until the quote returns — the instrument IS the artifact
+ * the solver mints. Absence here means exactly that one thing, because the
+ * wallet case is spelled `{ kind: "wallet" }` rather than left out.
+ */
+interface ResolvedEndpoint {
+    readonly corridor: Corridor;
+    readonly asset: AssetId;
+    /** Absent only while the leg's instrument does not exist yet. */
+    readonly instrument?: Instrument;
+}
+/** The amount a caller (or an invoice) pinned, and which leg it pins. */
+interface PinnedAmount {
+    readonly value: bigint;
+    readonly on: AmountOn;
+    /** What pinned it, for the diagnostic an `AmountMismatch` carries. */
+    readonly source: "caller" | "invoice";
+}
+/**
+ * What `resolve()` answers: the route's shape, the market that would price it,
+ * and what the active snapshot actually serves.
+ *
+ * `eligible` is reported alongside rather than folded into an error because
+ * zero is not a failure of resolution: the destination parsed, the corridor pair
+ * is implemented, and nothing about the route is wrong — there is simply no
+ * market for it on this snapshot. `quote()` is where that becomes
+ * `UnsupportedRoute`, since a quote cannot proceed past market selection.
+ */
+interface RouteResolution {
+    readonly give: ResolvedEndpoint;
+    readonly take: ResolvedEndpoint;
+    /** The card that would price it: the first eligible one after policy. */
+    readonly market?: MarketRef;
+    /** How many markets serve this pair on the active snapshot, after policy. */
+    readonly eligible: number;
+    /** Where the market data came from, and how fresh it is. */
+    readonly snapshot: SnapshotRef;
+    /** The amount pinned so far, when the input pinned one. */
+    readonly amount?: PinnedAmount;
+}
+
+/**
+ * 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";
+/**
+ * The public swap id: the family tag over the client-minted quote id,
+ * `offer:<QuoteId>` / `rfq:<QuoteId>`, as {@link Swap.id} carries it.
+ *
+ * The tag is presentation, not a second identity — storage, the drive and
+ * `accept()`'s idempotency stay keyed on the bare quote id. But a branded
+ * string erases at runtime, so the tag is not cosmetic either: it makes
+ * `NotCancellable` a parse of the prefix — a corridor id refused with no
+ * repository read, an offer id distinguished from a corridor id the way the v1
+ * read could not be — and it retypes the id a caller hands around, so
+ * `cancel(swap.id)` and `recover(swap.id)` stop being two spellings of one
+ * thing. An id arriving untagged from `/protocol`'s re-exported readers takes
+ * the same one read the tagged form takes.
+ */
+type AssetSwapId = `${SwapFamily}:${QuoteId}`;
+/** 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 swap, as a caller reads it.
+ *
+ * The quote's terms plus what has happened to them. `bigint` amounts and the
+ * resolved `Route`, because this is the public answer and the record is the
+ * storage form — §D's codec is the boundary between the two.
+ *
+ * `artifact` stays optional: M7's `ReceiveRequest` is `Swap & { artifact:
+ * Artifact }`, and an intersection cannot narrow a field that is already
+ * required. `id` is the tagged public form {@link AssetSwapId} — minted from
+ * `record.family` by {@link swapOf} — while storage, the drive and `accept()`'s
+ * idempotency stay keyed on the bare quote id.
+ *
+ * {@link outcome} and the two reason strings are M5's, and they are here rather
+ * than on `SwapUpdate.detail` because `detail` is typed `RawState` — the raw
+ * machine word and nothing else. The reasons live on `SwapRecordCommon`, the
+ * internal record, so without this a consumer told a swap `needs_recovery` had
+ * nowhere to read WHY.
+ */
+interface Swap {
+    readonly id: AssetSwapId;
+    readonly family: SwapFamily;
+    /** Where this swap stands, in the one vocabulary both families share. */
+    readonly outcome: Outcome;
+    /** Both endpoints resolved, instruments included. */
+    readonly route: Route;
+    /** What the trader gives, fee included. */
+    readonly give: QuoteLeg;
+    /** What the trader takes. */
+    readonly take: QuoteLeg;
+    /** The spread, denominated on the leg where it is exact. */
+    readonly fee: QuoteLeg;
+    readonly market: MarketRef;
+    readonly solver?: Pubkey;
+    /** Corridor routes: the hash both covenants commit to. */
+    readonly lock?: {
+        readonly hash: Hex;
+    };
+    /** Corridor routes: when the trader's value comes back. */
+    readonly refundLocktime?: number;
+    readonly artifact?: Artifact;
+    readonly expiresAt: number;
+    /** Absent until the funding is broadcast and its txid written. */
+    readonly fundingTxid?: string;
+    /**
+     * Why the swap `failed`, when it did.
+     *
+     * Carried across from the record rather than derived: the outcome says
+     * WHICH terminal state, and only the record says why.
+     */
+    readonly failure?: string;
+    /**
+     * Why this wallet will not act, while the outcome is `needs_recovery`.
+     *
+     * Also what makes a suppressed configuration block legible: under
+     * `drive: "manual"` or `"readonly"` the three configuration refusals are
+     * not translated to `needs_recovery`, and this is where the reason is
+     * still read.
+     */
+    readonly blockedReason?: string;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+
 /** 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. */
@@ -1878,9 +2834,8 @@ interface MarketsCacheEntry {
 }
 /**
  * Everything the package persists, following the monorepo repository
- * convention (versioned interface, AsyncDisposable, one backend per
- * platform — see the Boltz plugin's SwapRepository). Consumers construct
- * exactly one of these; there is no second storage seam.
+ * 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
@@ -1888,15 +2843,15 @@ interface MarketsCacheEntry {
  * that wipes one wants all three gone.
  *
  * ponytail: no query filters — every consumer reads all swaps and filters
- * in memory; mirror the Boltz plugin's GetSwapsFilter when a consumer needs
- * subset queries.
+ * in memory; add a filter type when a consumer needs subset queries.
  */
 interface AssetSwapRepository extends AsyncDisposable {
-    /** 4 adds `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 either cannot satisfy
-     * this one silently. */
-    readonly version: 4;
+    /** 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
@@ -1928,17 +2883,55 @@ interface AssetSwapRepository extends AsyncDisposable {
     getAllRfqSwaps(): Promise<RfqSwapRecord[]>;
     /** Drop one, once it is past retention — see `shouldRetainRfqSwap`. */
     removeRfqSwap(rfqId: string): Promise<void>;
-    /** Sent txids already checked for offer packets (see restore.ts). */
+    /**
+     * 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. */
+    /** 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>;
 }
 declare class InMemoryAssetSwapRepository implements AssetSwapRepository {
-    readonly version: 4;
+    readonly version: 5;
     private readonly swaps;
+    private readonly records;
     private readonly rfqSwaps;
     private readonly scanned;
     private readonly markets;
@@ -1948,6 +2941,10 @@ declare class InMemoryAssetSwapRepository implements AssetSwapRepository {
     getRfqSwap(rfqId: string): Promise<RfqSwapRecord | undefined>;
     getAllRfqSwaps(): Promise<RfqSwapRecord[]>;
     removeRfqSwap(rfqId: string): Promise<void>;
+    saveSwapRecord(record: SwapRecord): Promise<void>;
+    getSwapRecord(id: string): Promise<SwapRecord | undefined>;
+    getAllSwapRecords(): Promise<SwapRecord[]>;
+    removeSwapRecord(id: string): Promise<void>;
     getScannedTxids(): Promise<Set<string>>;
     markTxidsScanned(txids: Iterable<string>): Promise<void>;
     getCachedMarkets(network: string, registry: string): Promise<MarketsCacheEntry | undefined>;
@@ -1956,4 +2953,4 @@ declare class InMemoryAssetSwapRepository implements AssetSwapRepository {
     [Symbol.asyncDispose](): Promise<void>;
 }
 
-export { isRfqSwapTerminal as $, type AssetSwapRepository as A, BTC_ASSET_ID as B, type RfqSwapActionName as C, type RfqSwapLockup as D, RfqSwapManager as E, type RfqSwapManagerCallbacks as F, type RfqSwapManagerConfig as G, type RfqSwapManagerDeps as H, InMemoryAssetSwapRepository as I, type RfqSwapManagerEvents as J, type RfqSwapOrigin as K, type LockupVtxo as L, type MarketsCacheEntry as M, RfqSwapOriginRequired as N, type OnchainSendAction as O, type PersistableRfqSwap as P, type RfqSwapOutcome as Q, type RfqSwapRecord as R, type SwapSecretsProjection as S, type RfqSwapRecordStore as T, type SwapContractRegistry as U, addAssetSwap as V, awaitRfqResolution as W, createRfqSwapRecord as X, findLockupVtxos as Y, getAssetSwaps as Z, getAssetSwapsOrThrow as _, type AssetSwap as a, isRfqTerminal as a0, nextOnchainAction as a1, preimageForSwapRecord as a2, pushRefundWithoutReceiver as a3, readLockupFate as a4, rebuildRfqSwap as a5, refundIfUnresolved as a6, rfqSwapOriginOf as a7, shouldRetainRfqSwap as a8, swapSecretsToRecord as a9, updateAssetSwap as aa, updateAssetSwapBestEffort as ab, updateRfqSwapRecord as ac, type RefundArkProvider as b, type RefundIndexer as c, type RfqSwap as d, type ArkadeRefundResult as e, type LockupSpendIndexer as f, type RfqSwapState as g, type AssetSwapStatus as h, type AvailableRfqSwapManagerCallbacks as i, type LightningReceiveSwap as j, type LightningSendSwap as k, type LockupFate as l, LockupNeedsRecoveryError as m, type LockupParams as n, type LockupSpend as o, type OnchainSendSwap as p, type PreimageBlockedReason as q, PreimageNotRecoverableError as r, REFUND_MTP_LAG_SECONDS as s, RFQ_RESOLVED_STATES as t, RFQ_SWAP_RETENTION_SECONDS as u, RFQ_SWAP_TERMINAL_STATES as v, type RefundOutcome as w, type RfqRestoreFailure as x, type RfqRestoreOptions as y, type RfqRestoreResult as z };
+export { type RfqSwapRecordStore as $, type AssetSwapRepository as A, BTC_ASSET_ID as B, REFUND_MTP_LAG_SECONDS as C, RFQ_RESOLVED_STATES as D, RFQ_SWAP_RETENTION_SECONDS as E, RFQ_SWAP_TERMINAL_STATES as F, type RefundOutcome as G, type RfqRestoreFailure as H, InMemoryAssetSwapRepository as I, type RfqRestoreOptions as J, type RfqRestoreResult as K, type LockupVtxo as L, type MarketsCacheEntry as M, type RfqSwapActionName as N, type Outcome as O, type PersistableRfqSwap as P, type QuoteInput as Q, type RfqSwapRecord as R, type SwapSecretsProjection as S, type RfqSwapLockup as T, type Unsubscribe as U, type RfqSwapManagerConfig as V, type RfqSwapManagerDeps as W, type RfqSwapManagerEvents as X, type RfqSwapOrigin as Y, RfqSwapOriginRequired as Z, type RfqSwapOutcome as _, type AssetSwap as a, type SwapContractRegistry as a0, addAssetSwap as a1, awaitRfqResolution as a2, createRfqSwapRecord as a3, findLockupVtxos as a4, getAssetSwaps as a5, getAssetSwapsOrThrow as a6, isRfqSwapTerminal as a7, isRfqTerminal as a8, nextOnchainAction as a9, normalizeRfqSwapRecord as aa, preimageForSwapRecord as ab, pushRefundWithoutReceiver as ac, readLockupFate as ad, rebuildRfqSwap as ae, refundIfUnresolved as af, rfqSwapOriginOf as ag, shouldRetainRfqSwap as ah, swapSecretsToRecord as ai, updateAssetSwap as aj, updateAssetSwapBestEffort as ak, updateRfqSwapRecord as al, type SwapRecord as b, type AssetSwapStatus as c, type Swap as d, type RouteResolution as e, type Quote as f, type SwapUpdate as g, type RefundIndexer as h, type SwapOperator as i, type RfqSwap as j, type ArkadeRefundResult as k, type LockupSpendIndexer as l, type RfqSwapState as m, RfqSwapManager as n, type RfqSwapManagerCallbacks as o, type AvailableRfqSwapManagerCallbacks as p, type LightningReceiveSwap as q, type LightningSendSwap as r, type LockupFate as s, LockupNeedsRecoveryError as t, type LockupParams as u, type LockupSpend as v, type OnchainSendAction as w, type OnchainSendSwap as x, type PreimageBlockedReason as y, PreimageNotRecoverableError as z };