@arkade-os/swap 0.0.9 → 0.0.11

package/dist/{rfq-hbzhTWHT.d.cts → rfq-DkckzRKK.d.ts}

@@ -255,11 +255,15 @@ declare class SwapRefusal extends Error {
     readonly rfqId: string | undefined;
     constructor(reason: string, rfqId?: string);
 }
-/** The solver's address does not match the local derivation. NEVER fund past this. */
+/**
+ * The solver's address does not match the local derivation. NEVER fund past
+ * this. `derived` is every candidate address tried — more than one when the
+ * derivation itself is ambiguous, see {@link verifyLockupAddress}.
+ */
 declare class AddressMismatch extends Error {
-    readonly derived: string;
+    readonly derived: string | string[];
     readonly quoted: string | undefined;
-    constructor(derived: string, quoted?: string);
+    constructor(derived: string | string[], quoted?: string);
 }
 /** A fresh client-chosen negotiation id: 32 random bytes, lowercase hex. */
 declare const newRfqId: () => string;
@@ -323,9 +327,24 @@ declare const arkadeSwapRequest: (input: {
  * 90 because the refund CLTV matures against median-time-past (BIP-113),
  * which lags wall clock by ~1h — a smaller wall-clock margin is no margin. */
 declare const MIN_HEADROOM_SECONDS: number;
-/** Compare-only check of the solver's address against YOUR derivation.
- * Throws {@link AddressMismatch}; returns the address so calls chain. */
-declare const verifyLockupAddress: (quote: RfqQuote, derivedAddress: string) => string;
+/**
+ * Compare-only check of the solver's address against YOUR OWN derivation(s)
+ * — never extends trust, only narrows it.
+ *
+ * `derivedAddress` may be a single address or an array of candidates. Pass an
+ * array when your own derivation is ambiguous — as it is for the covenant
+ * lockups while solvers roll out the timelocked non-interactive refund leaf:
+ * nothing on the wire says whether a given quote's covenant carries it (the
+ * shape is fixed by the solver's own build, not negotiated per quote), so the
+ * only safe move is to derive BOTH shapes and accept whichever one the quote's
+ * own `lockup_address` matches. This loses no security: every candidate shape
+ * pins the refund to the trader's own refund destination, so a solver gains
+ * nothing by choosing which one to quote.
+ *
+ * Throws {@link AddressMismatch} only when NONE of the candidates match.
+ * Returns the address that matched, so calls chain exactly as before.
+ */
+declare const verifyLockupAddress: (quote: RfqQuote, derivedAddress: string | string[]) => string;
 /** The user's gates, checked immediately before funding — never at quote
  * time. Throws with a stable `reason` property. `invoiceExpiresAt` applies to
  * BOLT11 profiles only; `onchain` adds the L1-HTLC gates (§ guardrails of the
@@ -413,15 +432,17 @@ declare const unilateralRefundWithoutReceiverDelay: (claimDelay: number) => numb
  * hex); the script's HASH160 commitment is derived from it here, which is why
  * the trader never needs to see `P`.
  *
- * Every quote gets the full eight-leaf contract: VHTLC's own six
+ * Every quote gets the full emulator-covenant suite on top of VHTLC's own six
  * (`claim`/`refund`/`refundWithoutReceiver`/`unilateralClaim`/
- * `unilateralRefund`/`unilateralRefundWithoutReceiver`), plus two more the
- * emulator co-signs under a covenant pinning the payout to a pre-committed
- * destination — `nonInteractiveClaim` (server + emulator, pays the solver's
- * own `receiverPkScript`, no solver signature needed) and
- * `nonInteractiveRefund` (server + solver + emulator, pays the trader's own
- * `refundPkScript`, no timelock and no trader signature needed — see {@link
- * VHTLC.Options.nonInteractiveRefund}'s doc comment for why that matters).
+ * `unilateralRefund`/`unilateralRefundWithoutReceiver`): `nonInteractiveClaim`
+ * (server + emulator, pays the solver's own `receiverPkScript`, no solver
+ * signature needed), `nonInteractiveRefund` (server + solver + emulator, pays
+ * the trader's own `refundPkScript`, no timelock and no trader signature
+ * needed — see {@link VHTLC.Options.nonInteractiveParameters}'s doc comment for why
+ * that matters), and its timelocked twin `nonInteractiveRefundWithoutReceiver`
+ * (server + emulator alone, after `refundLocktime` — the only refund tier
+ * needing no participant at all). Nine leaves in all, unless `legacy` says
+ * otherwise.
  */
 declare function lightningSendVtxoScript(params: {
     /** Binding field #1: the solver's x-only key, from the quote. */
@@ -439,7 +460,7 @@ declare function lightningSendVtxoScript(params: {
     /** Emulator x-only key (32 bytes). */
     emulatorPubkey: Uint8Array;
     /** Where a refund must pay: the trader's P2TR pkScript (34 bytes). Also
-     * `nonInteractiveRefund`'s covenant destination. */
+     * the refund covenants' destination. */
     refundPkScript: Uint8Array;
     /** The trader's own key — VHTLC's `sender` role. Required on every
      * interactive refund-side leaf; the trader generates and persists it
@@ -450,6 +471,11 @@ declare function lightningSendVtxoScript(params: {
      * covenant key can be derived; the trader does not otherwise use or trust
      * this value. P2TR pkScript, 34 bytes. */
     receiverPkScript: Uint8Array;
+    /** LEGACY REBUILD ONLY — see {@link VHTLC.Options.nonInteractiveParameters}'s
+     * `legacy` field. Set only to re-derive a lockup funded before the
+     * timelocked refund leaf shipped; {@link matchQuotedLockup} passes it when
+     * the quote's own address says the solver quoted that shape. */
+    legacy?: "preTimelockedRefund";
 }): InstanceType<typeof VHTLC.ScriptV2>;
 /** Every input {@link lightningSendVtxoScript} builds from. Derived from the
  * builder rather than restated, so the two cannot drift. */
@@ -487,12 +513,11 @@ interface InvoiceFacts {
  * throws while nothing is funded. `RfqSwapManager` re-registers as a backstop
  * for older records; a repeat write is a no-op.
  *
- * The `sender` key comes from the wallet — a fresh HD descriptor per call, or
- * the wallet's static key — and is returned as `senderPubkey` plus `secrets`.
- * `secrets` holds only a public descriptor; the signer re-derives from the
- * wallet, so nothing secret is at rest. Persist `secrets` with the record
- * anyway: it is how the refund signer is found again. `nonInteractiveRefund`
- * recovers the funds even without it — but it needs the SOLVER's active
+ * The `sender` key is the wallet's identity key, reused by {@link
+ * provisionRefundKey} — returned as `senderPubkey` plus `secrets`. `secrets`
+ * holds only a public descriptor; the signer re-derives from the wallet, so
+ * nothing secret is at rest. Persist `secrets` with the record anyway: it is
+ * how the refund signer is found again. `nonInteractiveRefund` recovers the funds even without it — but it needs the SOLVER's active
  * cooperation, not just infrastructure uptime.
  */
 declare function requestLightningSend(wallet: IWallet, arkServerUrl: string, transport: RfqTransport, params: {
@@ -515,7 +540,8 @@ declare function requestLightningSend(wallet: IWallet, arkServerUrl: string, tra
      * `lockup` (with `address`): without it the manager can only poll, and
      * cannot retire the row this call just wrote. */
     script: InstanceType<typeof VHTLC.ScriptV2>;
-    /** Where a failed swap refunds. */
+    /** Where a failed swap refunds — the same address `secrets.pkScript` was
+     * decoded from, so the quote and the covenant always name one script. */
     refundAddress: string;
     /** The VHTLC `sender` x-only key, bound into the covenant. Public. */
     senderPubkey: Uint8Array;
@@ -528,7 +554,9 @@ declare function requestLightningSend(wallet: IWallet, arkServerUrl: string, tra
      * Returned so a consumer can persist the swap without re-deriving any of
      * it. Half of these are not on the quote: `serverPubkey` and `claimDelay`
      * come from this wallet's own `getInfo()`, `emulatorPubkey` from a
-     * per-network pin, `refundPkScript` from decoding an address.
+     * per-network pin, `refundPkScript` from `secrets` — decoded from the
+     * refund address at provisioning time, the same address this call returns
+     * as `refundAddress`.
      *
      * All public. Persisting them is optional: this call also registers the
      * lockup as a contract, and that row is where `rebuildRfqSwap` takes its
@@ -784,7 +812,7 @@ declare const assertReceivable: (input: {
     /** Absolute sats ceiling on `from_amount`. */
     maxPayAmount?: number;
 }) => void;
-/** Compile the RECEIVE-direction VHTLC: the same eight-leaf tree as {@link
+/** Compile the RECEIVE-direction VHTLC: the same suite-carrying tree as {@link
  * lightningSendVtxoScript} with the roles inverted — the trader is the
  * `receiver` (it generated `P` and claims the lockup with it), the solver is
  * the `sender` (it funds the lockup and holds the refund recourse). One
@@ -815,6 +843,8 @@ declare function receiveVtxoScript(params: {
     /** The trader's own Arkade payout pkScript (decoded from its payout
      * address) — `nonInteractiveClaim`'s pinned destination. */
     payoutPkScript: Uint8Array;
+    /** LEGACY REBUILD ONLY — see {@link lightningSendVtxoScript}'s `legacy`. */
+    legacy?: "preTimelockedRefund";
 }): InstanceType<typeof VHTLC.ScriptV2>;
 /** Every input {@link receiveVtxoScript} builds from; see
  * {@link LightningSendTreeParams}. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/swap",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "type": "module",
   "description": "Client-side Arkade Intents asset swaps: discover markets, quote, create/track/cancel offers, restore from chain.",
   "repository": {
@@ -70,7 +70,7 @@
     "@noble/hashes": "2.0.1",
     "@scure/base": "2.0.0",
     "@scure/btc-signer": "2.0.1",
-    "@arkade-os/sdk": "0.4.66"
+    "@arkade-os/sdk": "0.4.68"
   },
   "peerDependencies": {
     "nostr-tools": "^2.12.0"
@@ -91,8 +91,8 @@
   "scripts": {
     "build": "tsup src/index.ts src/nostr.ts src/repositories/sqlite/index.ts src/repositories/realm/index.ts --format esm,cjs --dts --clean",
     "typecheck": "tsc --noEmit",
-    "format": "prettier --write src test",
-    "lint": "prettier --check src test",
+    "format": "biome format --write src test",
+    "lint": "biome format src test",
     "test": "vitest run --exclude test/e2e",
     "test:unit": "vitest run --exclude test/e2e",
     "test:integration": "vitest run test/e2e/** --exclude test/e2e/rfq*.test.ts",