@arkade-os/swap 0.0.4 → 0.0.6

package/README.md

@@ -2,10 +2,10 @@
 
 Client-side [Arkade Intents](https://arkade.money) asset swaps: discover markets, quote and
 validate, create offers, track them, cancel them, and rebuild the whole record set from chain after
-a wallet restore. Framework-free TypeScript over `@arkade-os/sdk`: the core API and
-`InMemoryAssetSwapRepository` use no DOM and no Node-specific APIs, so they run in Node, the
-browser, and React Native alike. `IndexedDbAssetSwapRepository` is the one exception — it needs a
-platform-provided or polyfilled IndexedDB.
+a wallet restore. Framework-free TypeScript over `@arkade-os/sdk`: the core API uses no DOM and no
+Node-specific APIs, so it runs in Node, the browser, and React Native alike. Four storage backends
+ship — in-memory (anywhere, nothing outlives the process), IndexedDB (browser), SQLite and Realm
+(React Native, on subpath entry points) — see "Storage backends" below.
 
 ## Roles
 
@@ -100,11 +100,78 @@ arkade:BTC|asset` (quote, then take by funding an offer from layer 1).
 
 Everything the package persists — swap records, the restore-scan cursor, and the markets cache —
 goes through a single `AssetSwapRepository`, following the Arkade repository convention
-(versioned interface, `AsyncDisposable`, one backend per platform). Two backends ship here:
-`InMemoryAssetSwapRepository` and `IndexedDbAssetSwapRepository` (built on the SDK's shared
-IndexedDB manager, like the Boltz plugin's repositories). Construct one and pass it wherever the
-package asks for a repository; `discoverMarkets` also accepts none, for a one-shot uncached
-discovery.
+(versioned interface, `AsyncDisposable`, one backend per platform). Construct one and pass it
+wherever the package asks for a repository; `discoverMarkets` also accepts none, for a one-shot
+uncached discovery.
+
+## Storage backends
+
+| Backend                        | Import from                           | For                                             |
+| ------------------------------ | ------------------------------------- | ----------------------------------------------- |
+| `InMemoryAssetSwapRepository`  | `@arkade-os/swap`                     | tests, one-shot scripts — nothing survives exit |
+| `IndexedDbAssetSwapRepository` | `@arkade-os/swap`                     | the browser (or a polyfilled IndexedDB)         |
+| `SQLiteAssetSwapRepository`    | `@arkade-os/swap/repositories/sqlite` | React Native, over your SQLite driver           |
+| `RealmAssetSwapRepository`     | `@arkade-os/swap/repositories/realm`  | React Native, over your Realm instance          |
+
+Neither subpath adds a dependency: they take the SDK's structural `SQLExecutor` / `RealmLike`
+handles, so you pass the database you already opened.
+
+**Records are stored whole.** The SQLite and Realm backends serialize each record to **JSON** in a
+`data` column, with only `status` / `createdAt` mapped out for querying — so a field they do not
+know about survives, which is what the `quote`-shaped extension in `MIGRATION.md` relies on. JSON is
+the boundary, though, and it is narrower than IndexedDB's structured clone: a `Date` in a
+consumer-added field comes back an ISO **string**, a `Set` or `Map` comes back empty, and a `bigint`
+makes `saveSwap` **throw**. `AssetSwap` itself is JSON-safe by design (amounts are strings); keep
+your own added fields that way too.
+
+### SQLite
+
+```ts
+import { SQLiteAssetSwapRepository } from "@arkade-os/swap/repositories/sqlite";
+import { SQLiteWalletRepository, type SQLExecutor } from "@arkade-os/sdk/repositories/sqlite";
+
+const db = await SQLite.openDatabaseAsync("wallet.db"); // expo-sqlite
+// Build the executor ONCE and hand this same instance to every repository on
+// the database: the SDK serializes transactions in a chain keyed by this
+// object, so a per-repository literal splits the chain and two BEGIN
+// IMMEDIATEs can interleave.
+const executor: SQLExecutor = {
+    run: (sql, params) => db.runAsync(sql, params ?? []),
+    get: (sql, params) => db.getFirstAsync(sql, params ?? []),
+    all: (sql, params) => db.getAllAsync(sql, params ?? []),
+};
+
+const swaps = new SQLiteAssetSwapRepository(executor);
+const wallet = new SQLiteWalletRepository(executor); // same instance
+```
+
+Sharing the executor is **necessary** for that serialization, not sufficient for atomicity across
+all wallet storage: it disciplines the repositories that enter the chain — this one,
+`SQLiteIntentRepository`, `SQLiteVirtualTxRepository`, and the wallet repository's migration path —
+and nothing else. `SQLiteWalletRepository` and `SQLiteContractRepository` still write raw, so their
+writes can land inside whatever transaction happens to be open.
+
+Three tables land in your database, prefixed `arkade_`: `arkade_asset_swaps`,
+`arkade_asset_swap_scanned_txids`, `arkade_asset_swap_markets`. Pass `{ prefix: "myapp_" }` if your
+app already owns those names.
+
+### Realm
+
+```ts
+import Realm from "realm";
+import { AssetSwapRealmSchemas, RealmAssetSwapRepository } from "@arkade-os/swap/repositories/realm";
+import { ArkRealmSchemas } from "@arkade-os/sdk/repositories/realm";
+
+const realm = await Realm.open({
+    schema: [...ArkRealmSchemas, ...AssetSwapRealmSchemas, ...yourOwnSchemas],
+    schemaVersion: YOUR_VERSION, // these schemas are new: bump yours when adding them
+});
+const swaps = new RealmAssetSwapRepository(realm);
+```
+
+Three classes land in your Realm namespace: `ArkadeAssetSwap`, `ArkadeAssetSwapScannedTxid`,
+`ArkadeAssetSwapMarketsCache`. Unlike SQLite there is no prefix option — a Realm schema name is
+baked into the schema objects you register — so reconcile against your own models by name.
 
 ## Creating an offer
 
@@ -436,34 +503,42 @@ descriptor, which is public, and `contractSigner(wallet, descriptor)` recovers t
 
 What each swap stores, and what is recoverable:
 
-| Wallet answers with | Spending key          | Preimage (when the leg needs one) | Secret at rest    |
-| ------------------- | --------------------- | --------------------------------- | ----------------- |
-| fresh HD descriptor | re-derives from seed  | derives deterministically         | none              |
-| static `tr(pubkey)` | the wallet's identity | random, stored on the record      | the preimage only |
-
-The preimage split follows the **descriptor's shape**, not the wallet's type: an HD child
-descriptor is unique to its swap, so `sha256(sign_det(...))` is safe; a static descriptor is the
-same key for every swap, so a derived preimage would repeat across swaps — one solver learning its
-own preimage would learn every other swap's — and a per-swap random preimage is stored instead.
-`mustPersistPreimage` says which you got. A stored preimage is the one secret at rest in the
-design, and it is never a private key.
+| Wallet answers with       | Spending key          | Preimage (when the leg needs one)     | Secret at rest    |
+| ------------------------- | --------------------- | ------------------------------------- | ----------------- |
+| fresh HD descriptor       | re-derives from seed  | derives deterministically             | none              |
+| static `tr(pubkey)`       | the wallet's identity | derives from a public per-swap salt   | none              |
+| a signer that cannot sign |                       |                                       |                   |
+| deterministically         | the wallet's identity | random, stored on the record          | the preimage only |
+
+The preimage split follows the **descriptor's shape**, not the wallet's type. An HD child
+descriptor is unique to its swap, so `sha256(sign_det(...))` over the key alone is safe. A static
+descriptor is the same key for every swap, so that derivation would repeat across swaps — one
+solver learning its own preimage would learn every other swap's — and the uniqueness has to come
+from the message instead: the SDK mints 32 random bytes per swap, signs a **salted** message, and
+stores the salt in the clear.
+
+**The salt is not a secret.** Knowing it yields nothing without the seed, which is the whole
+difference from the preimage it replaces: the record goes from carrying a per-swap _secret_ to a
+per-swap _public_ value, exactly what `signingDescriptor` already is. Recoverability is unchanged
+in shape — keep the record and the swap recovers from the seed.
+
+Only a signer that cannot sign deterministically at all — an external or extension signer — still
+gets a random stored preimage. `mustPersistPreimage` says which you got, and it is the only thing
+to branch on. A stored preimage remains the one secret at rest in the design, and it is never a
+private key.
 
 ```ts
 const swap = await requestOnchainSend(/* … */);
-// `swapSecretsToRecord` stores the public descriptor always, and `preimageHex`
-// only when the wallet said it cannot re-derive P.
+// `swapSecretsToRecord` stores the public descriptor always, then whichever of
+// `preimageSaltHex` (derivable) or `preimageHex` (not) the wallet produced.
 await saveSwap({ ...record, ...swapSecretsToRecord(swap.secrets) });
 
-// Later, from the seed plus that descriptor. Only ask for a preimage the
-// corridor gave us one for: a lightning send's P belongs to the payee, so
-// this throws on those records rather than inventing something the chain will
-// never match. `LIGHTNING_SEND_PAIR` is exported from this package.
-if (record.signingDescriptor && record.pair !== LIGHTNING_SEND_PAIR) {
-    const preimage = await contractPreimage(
-        wallet,
-        record.signingDescriptor,
-        record.preimageHex ? hex.decode(record.preimageHex) : undefined,
-    );
+// Later, from the seed plus the record's public fields. Only ask for a
+// preimage the corridor gave us one for: a lightning send's P belongs to the
+// payee, so this throws on those records rather than inventing something the
+// chain will never match. `LIGHTNING_SEND_PAIR` is exported from this package.
+if (record.pair !== LIGHTNING_SEND_PAIR) {
+    const preimage = await preimageForSwapRecord(wallet, record);
 }
 
 // For a refund, take the composition instead of the guard: it turns all three
@@ -481,21 +556,45 @@ terminal: the lockup stays funded and watched, a solver claim still ends the swa
 `pending`. The manager reports the same state when nothing is wired to act (`enableAutoActions:
 false`, or no callbacks) and the window has passed.
 
+`preimageForSwapRecord` is the read path to wire, not a hand-rolled `contractPreimage` call: it
+knows which of the record's fields are derivation inputs, and it verifies the result against
+`paymentHash`. A caller that forgets to pass the salt gets a _wrong_ preimage from a wallet that can
+derive, not an error — and that surfaces as an opaque script failure at claim time.
+
+Every refusal is a `PreimageNotRecoverableError` carrying a `reason`: `no-secrets` (the record
+predates the descriptor), `malformed-record`, `not-derivable` (nothing to derive from, or a key this
+wallet does not hold), or `hash-mismatch` (derived, but wrong — a tampered salt or the wrong seed).
+Branch on `reason`, never on message text. It is deliberately **not**
+`RefundNotLocallyPossibleError`: that one means no local refund is possible and `RfqSwapManager`
+reports `needs_counterparty` for it, which is a different verdict from a claim-path read failing.
+
 A caller-supplied preimage keeps `signingDescriptor` for the sender key and stores only
 `preimageHex` as secret material.
 
 On an HD wallet each swap **allocates** its own descriptor rather than peeking at the current one:
 two swaps sharing a descriptor derive the _identical_ preimage, so one solver learning its own
-preimage would learn the other swap's. (Static wallets share their one descriptor by design — that
-is why their preimages are stored per swap, never derived.) On restore, `adoptContractDescriptor`
+preimage would learn the other swap's. (Static wallets share their one descriptor by design — the
+per-swap salt is what separates their preimages instead.) On restore, `adoptContractDescriptor`
 (from `@arkade-os/sdk`) moves the wallet's watermark past a restored record's index so it cannot be
 handed out twice; a static descriptor names no index and adopts as a no-op.
 
-The derivation is `sha256(signSchnorrDeterministic(sha256("Arkade-RFQ-Preimage-v1" ‖ xonly(32) ‖
-u32le(0))))`, mirroring NArk's Boltz scheme (`SwapsManagementService.cs:128-160`) with an
-RFQ-scoped tag. NArk has no RFQ corridor yet, so this tag defines the scheme rather than matching
-one; it is deliberately distinct from the Boltz tag so one wallet key cannot derive the same
-preimage for both corridors.
+Two derivations, picked by the descriptor's shape:
+
+```
+HD child      sha256(sign_det(sha256("Arkade-RFQ-Preimage-v1"             ‖ xonly(32) ‖ u32le(0))))
+static/salted sha256(sign_det(sha256("Arkade-Contract-Preimage-Salted-v1" ‖ xonly(32) ‖ salt(32))))
+```
+
+The first mirrors NArk's Boltz scheme (`SwapsManagementService.cs:128-160`) with an RFQ-scoped tag.
+NArk has no RFQ corridor yet, so this tag defines the scheme rather than matching one; it is
+deliberately distinct from the Boltz tag so one wallet key cannot derive the same preimage for both
+corridors.
+
+The salted tag is corridor-generic where the first is not, and that asymmetry is deliberate: the v1
+tags must be per-corridor because v1 pins its message index, leaving the tag as the only separation
+between two corridors reaching the same key. The salted form mints a fresh salt per swap, so no two
+swaps share a message within a corridor or across two — the salt carries the separation, and the tag
+names the layer rather than the corridor.
 
 **Not covered:** seed-only discovery after the swap repository is wiped. An unspent L1 HTLC reveals
 too little public quote data to rediscover, so the record remains required.
@@ -508,9 +607,71 @@ before later-funded addresses are found. Keep the swap repository in backups (re
 each record's descriptor via `adoptContractDescriptor`), or raise `gapLimit` on seed-only restores
 after heavy swap use.
 
+## Upgrading from 0.0.3
+
+0.0.1–0.0.3 are published. Under npm's 0.0.x rules `^0.0.3` resolves to exactly 0.0.3, so nothing
+auto-upgrades into the changes below — but a consumer that does upgrade meets them all in one jump,
+so they are written as one migration rather than per-release fragments.
+
+**Key provisioning moved into the SDK.** `packages/swap/src/secrets.ts` is gone. `deriveSwapSecrets`,
+`randomSwapSecrets`, `preimageForRfqSecrets`, `senderIdentityForRfqSecrets`, `rfqSecretsToRecord`,
+`rfqSecretsOfRecord`, `isPerSwapDescriptor`, `RFQ_PREIMAGE_TAG` and `SwapSecrets` no longer exist.
+Import `provisionRefundKey`, `provisionClaimSecret`, `contractSigner`, `contractPreimage`,
+`isPerArtifactDescriptor` and `ARKADE_SWAP_PREIMAGE_TAG` from `@arkade-os/sdk` instead;
+`swapSecretsToRecord` and `senderIdentityForSwapRecord` stay in this package. No consumer branches
+on wallet type any more, and no swap record can carry a private key.
+
+**`contractPreimage` takes an options object.** `contractPreimage(wallet, descriptor, stored?)`
+became `contractPreimage(wallet, descriptor, { stored?, salt? })`. Prefer `preimageForSwapRecord`,
+which reads both fields off the record and verifies against `paymentHash`.
+
+**Static wallets derive their preimage instead of storing it.** New records from such wallets carry
+`preimageSaltHex` and no `preimageHex`; `mustPersistPreimage` is now `false` for them, so the
+"persist the preimage" warning stops firing. Nothing at rest is secret unless the signer cannot sign
+deterministically at all.
+
+**`AssetSwap` gains `preimageSaltHex?`, and `AssetSwapRepository.version` is `2`.** External
+repository implementations must recompile — deliberately, because a field-mapped backend that drops
+`preimageSaltHex` leaves the swap unclaimable exactly as one dropping `preimageHex` does. Records
+written by 0.0.1–0.0.3 need no rewrite and no migration: the field is optional, older rows resolve
+through their stored `preimageHex` or their HD descriptor, and `DB_VERSION` is unchanged.
+
 ## Breaking changes on this branch (pre-release migration notes)
 
-The package is pre-release; these notes replace a changelog for consumers tracking the branch.
+Notes from before 0.0.1, kept for consumers who tracked the branch.
+
+- **Every derived address changed again, in both corridors — the unilateral ladder was re-spaced.**
+  `unilateralRefundDelay` now sits **level with** `claimDelay` instead of one 512s step above it,
+  and `unilateralRefundWithoutReceiverDelay` sits `SOLO_REFUND_HEADROOM_SECONDS` (4096s, newly
+  exported) above it instead of two steps. The old ladder spaced all three leaves one step apart as
+  though they were interchangeable rungs; they are not. Only `unilateralRefundWithoutReceiver` is a
+  solo path for the funder, so it is the only one whose timing can steal, and one 512s tick was
+  never enough for a claimant to complete a unilateral exit in. The two-signature refund needs no
+  separation at all, since neither party can spend that leaf alone. This tracks the reference
+  solver's [lightning-swap-service#81](https://github.com/arkade-os/lightning-swap-service/pull/81);
+  the two derivations must produce **the same three delay values** for the same operator, which is
+  what keeps the derived addresses identical. **Deployment must be coordinated** on the same terms
+  as the entry below: for a quote not yet funded, a mismatch refuses it at `verifyLockupAddress`
+  rather than losing funds.
+
+  **An in-flight lockup funded before the upgrade needs care, and the entry below understates
+  this.** The delays are not quote fields and are not persisted on the swap record
+  (`AssetSwap` keeps `swapPkScript`, not `claimDelay`), and `RfqSwap`'s own doc tells callers to
+  *rebuild* the script on restart from the quote's binding fields — which re-derives the delays
+  under whatever ladder is compiled in. So a trader who funded on `0.0.4`, upgraded, and restarted
+  rebuilds a **new** address, and `refundIfUnresolved` finds no VTXOs there and returns
+  `nothing_to_refund` — a terminal-sounding answer for money still locked at the old script, with
+  `refundLocktime` still ticking. Until the delays are persisted and rebuilt from the stored value,
+  drain in-flight lockups before upgrading, or rebuild the old script from the pre-upgrade delays
+  by hand. This is a pre-existing gap that any address-moving change hits, not one this change
+  introduces.
+
+  `unilateralClaimDelay`'s BIP68 ceiling tightened to reserve the full headroom rather than two
+  steps. Note this guard alone is **not** mirrored in the reference solver, which still rejects
+  only above `0xffff * 512`: for an operator `unilateralExitDelay` in `(33549824, 33553920]`
+  seconds the trader throws here while the solver quotes and then fails deeper in its own script
+  build. Both refuse, at different seams with different messages, so it is a diagnosability wart
+  rather than a fund risk — and the window is unreachable in practice (~388 days).
 
 - **`secrets.ts` is gone; key provisioning moved into `@arkade-os/sdk`.** This package no longer
   derives, mints, or names keys. It asks the SDK for what the leg needs — `provisionRefundKey(wallet)`

package/dist/{chunk-DLM6BVTB.js → chunk-Q4FAYBXS.js}

@@ -546,21 +546,22 @@ var relayTransport = (relayUrl, options) => {
   };
 };
 var SEQUENCE_GRANULARITY_SECONDS = 512;
+var SOLO_REFUND_HEADROOM_SECONDS = 8 * SEQUENCE_GRANULARITY_SECONDS;
 var unilateralClaimDelay = (serverExitDelaySeconds) => {
   if (!Number.isFinite(serverExitDelaySeconds) || serverExitDelaySeconds < SEQUENCE_GRANULARITY_SECONDS) {
     throw new Error(
       `server exit delay must be at least ${SEQUENCE_GRANULARITY_SECONDS}s of seconds, got ${serverExitDelaySeconds}`
     );
   }
-  if (serverExitDelaySeconds > (65535 - 2) * SEQUENCE_GRANULARITY_SECONDS) {
+  if (serverExitDelaySeconds > 65535 * SEQUENCE_GRANULARITY_SECONDS - SOLO_REFUND_HEADROOM_SECONDS) {
     throw new Error(
-      `server exit delay ${serverExitDelaySeconds}s exceeds what BIP68 can encode once the two refund tiers are stacked above it`
+      `server exit delay ${serverExitDelaySeconds}s exceeds what BIP68 can encode once the solo refund's headroom is stacked above it`
     );
   }
   return Math.ceil(serverExitDelaySeconds / SEQUENCE_GRANULARITY_SECONDS) * SEQUENCE_GRANULARITY_SECONDS;
 };
-var unilateralRefundDelay = (claimDelay) => claimDelay + SEQUENCE_GRANULARITY_SECONDS;
-var unilateralRefundWithoutReceiverDelay = (claimDelay) => claimDelay + 2 * SEQUENCE_GRANULARITY_SECONDS;
+var unilateralRefundDelay = (claimDelay) => claimDelay;
+var unilateralRefundWithoutReceiverDelay = (claimDelay) => claimDelay + SOLO_REFUND_HEADROOM_SECONDS;
 function lightningSendVtxoScript(params) {
   const seconds = (value) => ({
     type: "seconds",
@@ -1169,6 +1170,7 @@ export {
   assertFundable,
   httpTransport,
   relayTransport,
+  SOLO_REFUND_HEADROOM_SECONDS,
   unilateralClaimDelay,
   unilateralRefundDelay,
   unilateralRefundWithoutReceiverDelay,

package/dist/chunk-WGRU2DBF.js

@@ -0,0 +1,38 @@
+// src/repository.ts
+var marketsCacheKey = (network, registry) => `arkade-intents-markets-${network}-${registry}`;
+var InMemoryAssetSwapRepository = class {
+  version = 2;
+  swaps = /* @__PURE__ */ new Map();
+  scanned = /* @__PURE__ */ new Set();
+  markets = /* @__PURE__ */ new Map();
+  async saveSwap(swap) {
+    this.swaps.set(swap.id, swap);
+  }
+  async getAllSwaps() {
+    return [...this.swaps.values()];
+  }
+  async getScannedTxids() {
+    return new Set(this.scanned);
+  }
+  async markTxidsScanned(txids) {
+    for (const txid of txids) this.scanned.add(txid);
+  }
+  async getCachedMarkets(network, registry) {
+    return this.markets.get(marketsCacheKey(network, registry));
+  }
+  async saveCachedMarkets(network, registry, entry) {
+    this.markets.set(marketsCacheKey(network, registry), entry);
+  }
+  async clear() {
+    this.swaps.clear();
+    this.scanned.clear();
+    this.markets.clear();
+  }
+  async [Symbol.asyncDispose]() {
+  }
+};
+
+export {
+  marketsCacheKey,
+  InMemoryAssetSwapRepository
+};