@arkade-os/swap 0.0.5 → 0.0.7

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
 
@@ -223,7 +290,9 @@ message anywhere: **acceptance is funding**.
   offline. The solver observes the funding on-chain, pays the invoice, and claims with the
   preimage — which lands publicly in the claim witness as the receipt. A failed swap refunds by
   covenant to the trader's address, pushable by anyone, no trader keys or state.
-- **Arkade ↔ arkade** (BTC↔asset, asset↔asset): the trader accepts a quote by creating and funding
+- **Arkade ↔ arkade** (BTC↔asset, asset↔asset): an arkade asset leg names the asset id itself —
+  `arkade:<68-hex>`, built with `arkadeAssetLeg` (the deprecated coarse `ARKADE_ASSET` is served by
+  no solver). The trader accepts a quote by creating and funding
   an **offer** (layer 1) bound to the quoted terms before `valid_until`. The offer covenant only
   releases the deposit to a fill that delivers the quoted amount, so the solver fills or nothing
   moves; an unfilled offer is cancelled cooperatively. The quote wire shape ships here; the

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
+};

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

@@ -311,9 +311,10 @@ var solverHex = (value, field) => {
   }
 };
 var ARKADE_BTC = "arkade:BTC";
-var ARKADE_ASSET = "arkade:ASSET";
 var LIGHTNING_BTC = "lightning:BTC";
 var ONCHAIN_BTC = "onchain:BTC";
+var arkadeAssetLeg = (id) => `arkade:${id.toString()}`;
+var ARKADE_ASSET = "arkade:ASSET";
 var rfqPair = (from, to) => `${from}->${to}`;
 var LIGHTNING_SEND_PAIR = rfqPair(ARKADE_BTC, LIGHTNING_BTC);
 var LIGHTNING_RECEIVE_PAIR = rfqPair(LIGHTNING_BTC, ARKADE_BTC);
@@ -354,23 +355,34 @@ var lightningSendRequest = (input) => ({
   }
 });
 var arkadeSwapRequest = (input) => {
-  if (Boolean(input.wantAsset) === Boolean(input.offerAsset)) {
-    throw new Error("set exactly one of wantAsset (BTC->asset) or offerAsset (asset->BTC)");
+  if (!input.wantAsset && !input.offerAsset) {
+    throw new Error(
+      "set exactly one of wantAsset (BTC->asset) or offerAsset (asset->BTC) \u2014 with neither set both legs are BTC, which is not a swap"
+    );
   }
+  if (input.wantAsset && input.offerAsset) {
+    throw new Error(
+      "set exactly one of wantAsset (BTC->asset) or offerAsset (asset->BTC) \u2014 asset->asset is nameable on the wire but no solver quotes it yet"
+    );
+  }
+  const pair = rfqPair(
+    input.offerAsset ? arkadeAssetLeg(input.offerAsset) : ARKADE_BTC,
+    input.wantAsset ? arkadeAssetLeg(input.wantAsset) : ARKADE_BTC
+  );
+  assertPairLength(pair);
   return {
     v: 1,
     type: "rfq_request",
     rfq_id: input.rfqId,
-    pair: rfqPair(
-      input.offerAsset ? ARKADE_ASSET : ARKADE_BTC,
-      input.wantAsset ? ARKADE_ASSET : ARKADE_BTC
-    ),
+    pair,
     amount_side: input.amountSide,
     amount: input.amount,
-    profile: {
-      ...input.offerAsset && { offer_asset: hex3.encode(input.offerAsset.serialize()) },
-      ...input.wantAsset && { want_asset: hex3.encode(input.wantAsset.serialize()) }
-    }
+    // The pair is the only place the asset ids appear. Repeating them here
+    // would be a key the solver's `.strict()` profile schema does not
+    // declare, and an undeclared key is `unsupported_payload` — a refusal,
+    // not an ignored extra. Empty, not absent: `profile` is required on
+    // every other request shape this wire carries.
+    profile: {}
   };
 };
 var MIN_HEADROOM_SECONDS = 90 * 60;
@@ -384,6 +396,14 @@ var assertFinite = (value, reason, label) => {
     throw gateError(reason, `${label} is not a finite number (${String(value)})`);
   }
 };
+var MAX_PAIR_LENGTH = 158;
+var assertPairLength = (pair) => {
+  if (pair.length > MAX_PAIR_LENGTH) {
+    throw new Error(
+      `pair is ${pair.length} characters, over the wire's ${MAX_PAIR_LENGTH}-character limit`
+    );
+  }
+};
 var verifyLockupAddress = (quote, derivedAddress) => {
   const quoted = quote.profile?.lockup_address;
   if (derivedAddress !== quoted) throw new AddressMismatch(derivedAddress, quoted);
@@ -423,14 +443,20 @@ var assertFundable = (input) => {
     }
   }
 };
-var expectQuote = (payload, rfqId) => {
+var expectQuote = (payload, rfqId, requestedPair) => {
   const p = payload;
   if (p?.type === "rfq_refusal") throw new SwapRefusal(p.reason ?? "unknown", p.rfq_id ?? rfqId);
   if (p?.type !== "rfq_quote" || p.rfq_id !== rfqId) {
     throw new Error(`unexpected reply: ${p?.type ?? "no payload"}`);
   }
+  if (requestedPair !== void 0 && p.pair !== requestedPair) {
+    throw new Error(
+      `solver quoted ${JSON.stringify(p.pair)}, not the requested ${requestedPair}`
+    );
+  }
   return payload;
 };
+var pairOf = (payload) => typeof payload.pair === "string" ? payload.pair : void 0;
 var httpTransport = (baseUrl, options = {}) => {
   const fetchImpl = options.fetchImpl ?? fetch;
   const readJson = async (response, what) => {
@@ -450,7 +476,11 @@ var httpTransport = (baseUrl, options = {}) => {
         headers: { "content-type": "application/json" },
         body: JSON.stringify(payload)
       });
-      return expectQuote(await readJson(response, "quote request"), String(payload.rfq_id));
+      return expectQuote(
+        await readJson(response, "quote request"),
+        String(payload.rfq_id),
+        pairOf(payload)
+      );
     },
     async status(rfqId) {
       const response = await fetchImpl(`${baseUrl}/v1/rfq/${rfqId}`, { method: "GET" });
@@ -527,7 +557,8 @@ var relayTransport = (relayUrl, options) => {
     async requestQuote(payload) {
       return expectQuote(
         await roundTrip(payload, String(payload.rfq_id)),
-        String(payload.rfq_id)
+        String(payload.rfq_id),
+        pairOf(payload)
       );
     },
     async status(rfqId) {
@@ -1151,9 +1182,10 @@ export {
   LockupRegistrationFailed,
   registerLockupContract,
   ARKADE_BTC,
-  ARKADE_ASSET,
   LIGHTNING_BTC,
   ONCHAIN_BTC,
+  arkadeAssetLeg,
+  ARKADE_ASSET,
   rfqPair,
   LIGHTNING_SEND_PAIR,
   LIGHTNING_RECEIVE_PAIR,
@@ -1168,6 +1200,8 @@ export {
   MIN_HEADROOM_SECONDS,
   verifyLockupAddress,
   assertFundable,
+  expectQuote,
+  pairOf,
   httpTransport,
   relayTransport,
   SOLO_REFUND_HEADROOM_SECONDS,

package/dist/index.cjs

@@ -67,6 +67,7 @@ __export(index_exports, {
   SWAP_LOCKUP_CONTRACT_TYPE: () => SWAP_LOCKUP_CONTRACT_TYPE,
   SwapRefusal: () => SwapRefusal,
   addAssetSwap: () => addAssetSwap,
+  arkadeAssetLeg: () => arkadeAssetLeg,
   arkadeSwapRequest: () => arkadeSwapRequest,
   assertFundable: () => assertFundable,
   assertReceivable: () => assertReceivable,
@@ -128,6 +129,7 @@ __export(index_exports, {
   senderIdentityForSwapRecord: () => senderIdentityForSwapRecord,
   spendTxidsOf: () => spendTxidsOf,
   spendUpdate: () => spendUpdate,
+  swapActivityResolver: () => swapActivityResolver,
   swapPrograms: () => swapPrograms,
   swapSecretsToRecord: () => swapSecretsToRecord,
   unilateralClaimDelay: () => unilateralClaimDelay,
@@ -1445,9 +1447,10 @@ var solverHex = (value, field) => {
   }
 };
 var ARKADE_BTC = "arkade:BTC";
-var ARKADE_ASSET = "arkade:ASSET";
 var LIGHTNING_BTC = "lightning:BTC";
 var ONCHAIN_BTC = "onchain:BTC";
+var arkadeAssetLeg = (id) => `arkade:${id.toString()}`;
+var ARKADE_ASSET = "arkade:ASSET";
 var rfqPair = (from, to) => `${from}->${to}`;
 var LIGHTNING_SEND_PAIR = rfqPair(ARKADE_BTC, LIGHTNING_BTC);
 var LIGHTNING_RECEIVE_PAIR = rfqPair(LIGHTNING_BTC, ARKADE_BTC);
@@ -1488,23 +1491,34 @@ var lightningSendRequest = (input) => ({
   }
 });
 var arkadeSwapRequest = (input) => {
-  if (Boolean(input.wantAsset) === Boolean(input.offerAsset)) {
-    throw new Error("set exactly one of wantAsset (BTC->asset) or offerAsset (asset->BTC)");
+  if (!input.wantAsset && !input.offerAsset) {
+    throw new Error(
+      "set exactly one of wantAsset (BTC->asset) or offerAsset (asset->BTC) \u2014 with neither set both legs are BTC, which is not a swap"
+    );
+  }
+  if (input.wantAsset && input.offerAsset) {
+    throw new Error(
+      "set exactly one of wantAsset (BTC->asset) or offerAsset (asset->BTC) \u2014 asset->asset is nameable on the wire but no solver quotes it yet"
+    );
   }
+  const pair = rfqPair(
+    input.offerAsset ? arkadeAssetLeg(input.offerAsset) : ARKADE_BTC,
+    input.wantAsset ? arkadeAssetLeg(input.wantAsset) : ARKADE_BTC
+  );
+  assertPairLength(pair);
   return {
     v: 1,
     type: "rfq_request",
     rfq_id: input.rfqId,
-    pair: rfqPair(
-      input.offerAsset ? ARKADE_ASSET : ARKADE_BTC,
-      input.wantAsset ? ARKADE_ASSET : ARKADE_BTC
-    ),
+    pair,
     amount_side: input.amountSide,
     amount: input.amount,
-    profile: {
-      ...input.offerAsset && { offer_asset: import_base8.hex.encode(input.offerAsset.serialize()) },
-      ...input.wantAsset && { want_asset: import_base8.hex.encode(input.wantAsset.serialize()) }
-    }
+    // The pair is the only place the asset ids appear. Repeating them here
+    // would be a key the solver's `.strict()` profile schema does not
+    // declare, and an undeclared key is `unsupported_payload` — a refusal,
+    // not an ignored extra. Empty, not absent: `profile` is required on
+    // every other request shape this wire carries.
+    profile: {}
   };
 };
 var MIN_HEADROOM_SECONDS = 90 * 60;
@@ -1518,6 +1532,14 @@ var assertFinite = (value, reason, label) => {
     throw gateError(reason, `${label} is not a finite number (${String(value)})`);
   }
 };
+var MAX_PAIR_LENGTH = 158;
+var assertPairLength = (pair) => {
+  if (pair.length > MAX_PAIR_LENGTH) {
+    throw new Error(
+      `pair is ${pair.length} characters, over the wire's ${MAX_PAIR_LENGTH}-character limit`
+    );
+  }
+};
 var verifyLockupAddress = (quote, derivedAddress) => {
   const quoted = quote.profile?.lockup_address;
   if (derivedAddress !== quoted) throw new AddressMismatch(derivedAddress, quoted);
@@ -1557,14 +1579,20 @@ var assertFundable = (input) => {
     }
   }
 };
-var expectQuote = (payload, rfqId) => {
+var expectQuote = (payload, rfqId, requestedPair) => {
   const p = payload;
   if (p?.type === "rfq_refusal") throw new SwapRefusal(p.reason ?? "unknown", p.rfq_id ?? rfqId);
   if (p?.type !== "rfq_quote" || p.rfq_id !== rfqId) {
     throw new Error(`unexpected reply: ${p?.type ?? "no payload"}`);
   }
+  if (requestedPair !== void 0 && p.pair !== requestedPair) {
+    throw new Error(
+      `solver quoted ${JSON.stringify(p.pair)}, not the requested ${requestedPair}`
+    );
+  }
   return payload;
 };
+var pairOf = (payload) => typeof payload.pair === "string" ? payload.pair : void 0;
 var httpTransport = (baseUrl, options = {}) => {
   const fetchImpl = options.fetchImpl ?? fetch;
   const readJson = async (response, what) => {
@@ -1584,7 +1612,11 @@ var httpTransport = (baseUrl, options = {}) => {
         headers: { "content-type": "application/json" },
         body: JSON.stringify(payload)
       });
-      return expectQuote(await readJson(response, "quote request"), String(payload.rfq_id));
+      return expectQuote(
+        await readJson(response, "quote request"),
+        String(payload.rfq_id),
+        pairOf(payload)
+      );
     },
     async status(rfqId) {
       const response = await fetchImpl(`${baseUrl}/v1/rfq/${rfqId}`, { method: "GET" });
@@ -1661,7 +1693,8 @@ var relayTransport = (relayUrl, options) => {
     async requestQuote(payload) {
       return expectQuote(
         await roundTrip(payload, String(payload.rfq_id)),
-        String(payload.rfq_id)
+        String(payload.rfq_id),
+        pairOf(payload)
       );
     },
     async status(rfqId) {
@@ -3376,6 +3409,60 @@ var outcomeOf = (swap) => {
 };
 var errorMessage = (error) => error instanceof Error ? error.message : String(error);
 var outpointKey = (vtxo) => `${vtxo.txid}:${vtxo.vout}`;
+
+// src/activity.ts
+var LABELS = {
+  lightning_send: "Lightning send",
+  lightning_receive: "Lightning receive",
+  onchain_send: "Onchain send"
+};
+var OUTCOME = {
+  pending: "pending",
+  // `claimable` and `claimed` are both in-progress states with no
+  // user-visible phase distinct from "pending". `needs_counterparty` is
+  // different in kind — the swap is BLOCKED, not merely in flight, since no
+  // unilateral trader move exists (see `RfqSwapState`). Collapsing it into
+  // `pending` here is a deliberate choice the opaque-token design permits —
+  // apps map tokens themselves — but a future reader weighing a `"blocked"`
+  // or `"stuck"` token should know this was already considered.
+  claimable: "pending",
+  claimed: "pending",
+  needs_counterparty: "pending",
+  settled: "settled",
+  refunded: "refunded",
+  failed: "failed"
+};
+function swapActivityResolver(deps) {
+  let byTxid = /* @__PURE__ */ new Map();
+  return {
+    id: "arkade:swap",
+    async prepare() {
+      const swaps = await deps.listSwaps();
+      const index = /* @__PURE__ */ new Map();
+      for (const swap of swaps) {
+        for (const txid of swap.txids) {
+          if (txid) index.set(txid, swap);
+        }
+      }
+      byTxid = index;
+    },
+    resolve(tx) {
+      const key = tx.key.arkTxid || tx.key.commitmentTxid || tx.key.boardingTxid;
+      const swap = key ? byTxid.get(key) : void 0;
+      if (!swap) return void 0;
+      const lostReceive = swap.kind === "lightning_receive" && swap.state === "refunded";
+      return [
+        {
+          groupId: `swap:${swap.rfqId}`,
+          label: LABELS[swap.kind],
+          kind: "swap",
+          outcome: lostReceive ? "lost" : OUTCOME[swap.state],
+          metadata: { rfqId: swap.rfqId, swapKind: swap.kind }
+        }
+      ];
+    }
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ARKADE_ASSET,
@@ -3415,6 +3502,7 @@ var outpointKey = (vtxo) => `${vtxo.txid}:${vtxo.vout}`;
   SWAP_LOCKUP_CONTRACT_TYPE,
   SwapRefusal,
   addAssetSwap,
+  arkadeAssetLeg,
   arkadeSwapRequest,
   assertFundable,
   assertReceivable,
@@ -3476,6 +3564,7 @@ var outpointKey = (vtxo) => `${vtxo.txid}:${vtxo.vout}`;
   senderIdentityForSwapRecord,
   spendTxidsOf,
   spendUpdate,
+  swapActivityResolver,
   swapPrograms,
   swapSecretsToRecord,
   unilateralClaimDelay,