@ninsei-labs/sdk 0.44.3 → 0.46.0

package/CHANGELOG.md

@@ -1,3 +1,28 @@
+## 0.46.0 — 2026-10-21
+
+THE QUOTE CARRIES THE CLAIM TIP, AND THE CLAIM PAYS IT.
+
+- `claimTip` is the last field of the signed order quote and of `FactoryQuote`, and it is encoded into
+  `createOrderAndFund`. The escrow pays it to whoever sends `claim` when that sender is not the claimer, out of the
+  payout and in the same transaction (`router-escrow-evm` #19). Zero means no tip.
+- `ORDER_QUOTE_VERSION` is 9. The field set changed, so every quote signed by this package is a version 9 quote and
+  verifies only against an escrow that knows the field.
+- A quote object without `claimTip` is refused by `quoteMissingFields` like any other absent condition: a missing tip
+  is not read as zero.
+
+## 0.45.0 — 2026-10-20
+
+THE RECOVERY PATH WORKS WITHOUT THE APP, AND A PASSPHRASE IS A CHOICE.
+
+- `sweep.plan` reads the counterparty's revealed half from the escrow with the `evmCall` the caller already
+  passes (`revealedHalf()`, selector `0x3f267bb6`). A recovery page served from a static host has no
+  `/escrow/revealed-half` route, so asking the app was the only path and the page could never withdraw there.
+  The app route remains as the fallback for a caller with no chain read that configured an API base.
+- An empty passphrase writes the recovery file without encryption. The envelope is version 3 with
+  `alg: "NONE"` and carries the payload; `decryptFile` returns it without deriving a key, and `isEncrypted`
+  tells a page whether to ask for a passphrase. A non-empty passphrase keeps the twelve character floor.
+- `swaps.start`, `sweep.plan`, `sweep.destination` and `recovery.restoreHeight` accept an empty passphrase.
+
 ## 0.44.3 — 2026-10-20
 
 A RESCAN THAT THE LIBRARY REFUSES DOES NOT STOP THE RESTORE.

package/engine/evm/factory.js

@@ -32,6 +32,7 @@ export const ORDER_CREATED_TOPIC =
 export const QUOTE_FIELDS = [
   "provider", "quoteKey", "registry", "cashier", "locker", "claimer", "amount", "readyBy", "t1", "salt",
   "commitHalfClaimer", "edPointClaimer", "chainId", "feeBps", "fee", "feeRecipient", "validUntil", "nonce", "xmrAmount",
+  "claimTip",
 ];
 // The depositor fields are NOT in the quote: they go as separate arguments (into the escrow init code).
 const LOCKER_HALF_FIELDS = ["commitHalfLocker", "edPointLocker", "edViewPointLocker"];
@@ -89,6 +90,7 @@ function quoteWords(quote) {
     chainId: word(quote.chainId, 32), feeBps: word(quote.feeBps, 32), fee: word(quote.fee, 32),
     feeRecipient: word(quote.feeRecipient, 32), validUntil: word(quote.validUntil, 32), nonce: word(quote.nonce, 32),
     xmrAmount: word(quote.xmrAmount, 32),
+    claimTip: word(quote.claimTip, 32),
   };
   return QUOTE_FIELDS.map((n) => map[n]).join("");
 }

package/engine/recovery/recoveryFile.js

@@ -78,7 +78,12 @@ export const FILE_MAGIC = "NINSEI-SWAP-RECOVERY";
 // BOTH must be readable: people hold version-1 files and they must not be lost. The version is raised when the
 // ENVELOPE itself changes, not the payload inside.
 export const ENVELOPE_VERSION = 2;
-const READABLE_ENVELOPE_VERSIONS = [1, 2];
+// v3 - NO ENCRYPTION. An empty passphrase writes the payload in the clear and the envelope says so. It is a
+// deliberate choice by the owner: a forgotten passphrase locks a person out of their own money, and the file is
+// still the only way to the XMR. Readers of every version must keep working.
+export const UNENCRYPTED_ENVELOPE_VERSION = 3;
+export const ALG_NONE = "NONE";
+const READABLE_ENVELOPE_VERSIONS = [1, 2, 3];
 export const PAYLOAD_VERSION = 3;
 // v1 - the very first files (seedHex and both keys as separate fields), v2 - the mnemonic as the single source,
 // v3 - HALVES. All three must be readable: people hold files of every version, and a recovery file is the only way
@@ -264,7 +269,13 @@ export function validatePayload(payload) {
 }
 
 export async function encryptPayload(payload, passphrase) {
-  if (!passphrase || passphrase.length < 12) throw new Error("Passphrase must be at least 12 characters");
+  const metaOf = () => ({ id: payload.swapId, side: payload.side, createdAt: payload.createdAt, termsHash: payload.termsHash || null });
+  // AN EMPTY PASSPHRASE MEANS NO ENCRYPTION, AND THE ENVELOPE SAYS SO. A provided one keeps the twelve character
+  // floor: a short password is worse than none because it looks like protection.
+  if (passphrase === "") {
+    return { v: UNENCRYPTED_ENVELOPE_VERSION, alg: ALG_NONE, meta: metaOf(), payload };
+  }
+  if (typeof passphrase !== "string" || passphrase.length < 12) throw new Error("Passphrase must be at least 12 characters");
   const salt = crypto.getRandomValues(new Uint8Array(16));
   const iv = crypto.getRandomValues(new Uint8Array(12));
   const key = await deriveKey(passphrase, salt, ITER);
@@ -282,9 +293,19 @@ export async function encryptPayload(payload, passphrase) {
 // Decryption. AES-GCM errors (wrong password, altered ciphertext) arrive as OperationError with no detail - we
 // turn them into a human message, else the user sees "operation failed" and cannot tell a wrong password from a
 // corrupt file.
+// WHETHER A FILE ASKS FOR A PASSPHRASE. A page reads this before showing the field: an unencrypted file has none.
+export function isEncrypted(fileObject) {
+  return !!(fileObject && typeof fileObject === "object" && fileObject.alg !== ALG_NONE);
+}
+
 export async function decryptFile(fileObject, passphrase) {
   if (!fileObject || typeof fileObject !== "object") throw new Error("Not a recovery file (expecting JSON)");
   if (!READABLE_ENVELOPE_VERSIONS.includes(fileObject.v)) throw new Error(`Unsupported recovery file version: ${fileObject.v}`);
+  if (fileObject.v === UNENCRYPTED_ENVELOPE_VERSION) {
+    if (fileObject.alg !== ALG_NONE) throw new Error(`Unknown algorithm: ${fileObject.alg}`);
+    if (!fileObject.payload || typeof fileObject.payload !== "object") throw new Error('Recovery file is missing "payload"');
+    return fileObject.payload;
+  }
   if (fileObject.alg !== ALG_ID) throw new Error(`Unknown algorithm: ${fileObject.alg}`);
   for (const field of ["salt", "iv", "ciphertext"]) {
     if (typeof fileObject[field] !== "string" || !fileObject[field]) throw new Error(`Recovery file is missing "${field}"`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninsei-labs/sdk",
-  "version": "0.44.3",
+  "version": "0.46.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/src/index.mjs

@@ -284,7 +284,7 @@ export function createNinsei(options) {
       createRecord: o.createRecord }),
     // XMR WITHDRAWAL: parsing the file and requesting data work; the withdrawal itself is named (the Monero
     // wallet as an adapter).
-    sweep: createSweep({ http, config }),
+    sweep: createSweep({ http, config, call: o.evmCall }),
   });
 }
 

package/src/public/evm.d.ts

@@ -47,6 +47,8 @@ export interface FactoryQuote {
   readonly validUntil: string | number | bigint;
   readonly nonce: string | number | bigint;
   readonly xmrAmount: string | number | bigint;
+  /** The tip `claim` pays to a third-party sender out of the payout; zero means none. */
+  readonly claimTip: string | number | bigint;
   /** r || s || v over the quote digest, 65 bytes, with or without the `0x` prefix. */
   readonly signature: string;
   readonly commitHalfLocker: string;

package/src/public/order.d.ts

@@ -110,6 +110,8 @@ export interface OrderQuote {
   readonly validUntil: string | number | bigint;
   readonly nonce: string | number | bigint;
   readonly xmrAmount: string | number | bigint;
+  /** The tip `claim` pays to a third-party sender out of the payout; zero means none. */
+  readonly claimTip: string | number | bigint;
   /** The escrow factory the domain names as `verifyingContract`. */
   readonly factory: string;
   /** r || s || v over the digest, 65 bytes, with or without the `0x` prefix; v is normalised to 27/28. */

package/src/public/recovery.d.ts

@@ -19,6 +19,12 @@ export declare const ENVELOPE_VERSION: number;
 /** The payload version (deal content), raised independently of the envelope: 1 keys as fields, 2 the mnemonic, 3 halves. */
 export declare const PAYLOAD_VERSION: number;
 
+/** The envelope version of a file written WITHOUT a passphrase: the payload travels in the clear and the header says so. */
+export declare const UNENCRYPTED_ENVELOPE_VERSION: number;
+
+/** The algorithm identifier of an unencrypted envelope. */
+export declare const ALG_NONE: string;
+
 /** The mark every Ninsei recovery file carries in its payload, so a foreign file is refused by name. */
 export declare const FILE_MAGIC: string;
 
@@ -47,7 +53,7 @@ export interface RecoveryEnvelopeHeader {
   readonly iv: string;
 }
 
-/** The recovery file object as it is written (`ninsei-<id>.json.enc`) and read back. */
+/** An encrypted recovery file object as it is written (`ninsei-<id>.json.enc`) and read back. */
 export interface RecoveryEnvelope extends RecoveryEnvelopeHeader {
   /** The AES-GCM ciphertext of the payload, base64. */
   readonly ciphertext: string;
@@ -55,6 +61,14 @@ export interface RecoveryEnvelope extends RecoveryEnvelopeHeader {
   readonly meta?: RecoveryEnvelopeMeta | null;
 }
 
+/** A recovery file written WITHOUT a passphrase: the payload is readable, the envelope says so, and no key is derived. */
+export interface RecoveryPlainEnvelope {
+  readonly v: number;
+  readonly alg: string;
+  readonly meta?: RecoveryEnvelopeMeta | null;
+  readonly payload: RecoveryPayload;
+}
+
 /**
  * The AAD string: the header fields, in one FIXED order, that AES-GCM authenticates beside the ciphertext.
  *
@@ -221,10 +235,14 @@ export interface RecoveryValidation {
 export declare function validatePayload(payload: RecoveryPayload): RecoveryValidation;
 
 /**
- * Encrypts one payload into a recovery file envelope: a fresh salt and IV, the key derived from the passphrase, and
- * the header authenticated as AAD. A passphrase shorter than 12 characters is refused.
+ * Writes one payload into a recovery file envelope. A non-empty passphrase derives a key from a fresh salt and IV
+ * and authenticates the header as AAD; a passphrase shorter than 12 characters is refused. An EMPTY passphrase
+ * writes the payload in the clear, with the envelope naming that fact.
  */
-export declare function encryptPayload(payload: RecoveryPayload, passphrase: string): Promise<RecoveryEnvelope>;
+export declare function encryptPayload(payload: RecoveryPayload, passphrase: string): Promise<RecoveryEnvelope | RecoveryPlainEnvelope>;
+
+/** Whether the file asks for a passphrase. False for an unencrypted envelope. */
+export declare function isEncrypted(fileObject: unknown): boolean;
 
 /**
  * Decrypts a recovery file: the envelope version, the algorithm, the required fields and the iteration count are

package/src/public/recovery.mjs

@@ -13,6 +13,9 @@ export {
   decryptFile,
   encryptPayload,
   envelopeAad,
+  isEncrypted,
+  ALG_NONE,
+  UNENCRYPTED_ENVELOPE_VERSION,
   recoveryFileName,
   scanStartHeight,
   validatePayload,

package/src/quoteEip712Spec.mjs

@@ -32,18 +32,22 @@
 //   validUntil           - the quote's own expiry, IN SECONDS (the order's readyBy/t1 and block.timestamp
 //                          scale): a quote past it is refused regardless of the price.
 //   nonce                - replay protection: the very same signed quote cannot be presented twice.
+//   claimTip             - the tip the escrow pays to whoever sends `claim`, out of the payout, in the same
+//                          transaction (#18). It is inside the signed set so a provider cannot raise it after the
+//                          taker has seen the quote. Zero means no tip and is the only value a buy uses.
 //
 // The domain's verifyingContract is the escrow FACTORY taken from the order: the contract that will verify the
 // quote in EVM (stage 2). The type order, the domain name and the version are part of the protocol - they may
 // change only together with the quote version.
 export const ORDER_QUOTE_DOMAIN_NAME = "NinseiEscrowFactory";
 export const ORDER_QUOTE_DOMAIN_VERSION = "1";
-// 8: the signed EIP-712 field set grew `xmrAmount` (#110 step 3) - the XMR the level walk gives is now covered by
-// the provider's signature and verified ON CHAIN. This is the request-shape generation label, and it moves WITH the
+// 9: the signed EIP-712 field set grew `claimTip` (#18) - the tip a third-party sender of `claim` takes from the
+// payout, covered by the provider's signature like every other condition.
+// 8: the field set grew `xmrAmount` (#110 step 3). This is the request-shape generation label, and it moves WITH the
 // field set (see the note above). The DOMAIN name and the domain version string are UNCHANGED by it: they name the
 // domain (the factory address and the chain), which did not change. So here the label and the domain version string
 // move apart, and that is deliberate - the label tracks the message shape, not the domain identity.
-export const ORDER_QUOTE_VERSION = 8;
+export const ORDER_QUOTE_VERSION = 9;
 
 // The domain type string is assembled from parts ON PURPOSE. A single literal of it is a phrase of several
 // space-separated words, and the SDK check reads such literals as user-facing text. Do not "simplify" it.
@@ -72,6 +76,7 @@ export const ORDER_QUOTE_FIELDS = [
   ["validUntil", "uint64"],
   ["nonce", "uint256"],
   ["xmrAmount", "uint256"],
+  ["claimTip", "uint256"],
 ];
 export const ORDER_QUOTE_TYPE = "OrderQuote(" + ORDER_QUOTE_FIELDS.map((f) => f[1] + " " + f[0]).join(",") + ")";
 

package/src/recovery.mjs

@@ -52,7 +52,8 @@ export function createRecovery({ http = null, config = null } = {}) {
     async restoreHeight(request = {}) {
       const contents = contentsOf(request.file);
       if (contents === null) throw new SdkError("bad-input", { field: "file" });
-      if (typeof request.passphrase !== "string" || !request.passphrase) {
+      // AN EMPTY PASSPHRASE IS A VALID ONE: the file may be unencrypted on purpose.
+      if (typeof request.passphrase !== "string") {
         throw new SdkError("bad-input", { field: "passphrase" });
       }
       // THE ENVELOPE IS PARSED HERE: `restoreFromFile` takes the OBJECT, while the file arrives as text. Doing it

package/src/swaps.mjs

@@ -737,7 +737,8 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
       const makeRecord = typeof createRecord === "function" ? createRecord
         : async (req) => recordModule.createRecord(recordInputOf(req), { order: req.order });
       const passphrase = typeof request.passphrase === "string" ? request.passphrase : "";
-      if (passphrase.length < MIN_PASSPHRASE) throw new SdkError("bad-input", { field: "passphrase", min: MIN_PASSPHRASE });
+      if (typeof passphrase !== "string") throw new SdkError("bad-input", { field: "passphrase" });
+      if (passphrase.length > 0 && passphrase.length < MIN_PASSPHRASE) throw new SdkError("bad-input", { field: "passphrase", min: MIN_PASSPHRASE });
       // THE ORDER TERMS ARE CHECKED BEFORE THE RECORD. The context is assembled by the engine from the very fields the
       // firm quote's signature is bound to; incomplete terms - a refusal with a named field, not a substitution of empty
       // values: the DLEQ proof would then be bound to nothing.

package/src/sweep.mjs

@@ -14,6 +14,8 @@ import { checkDestination } from "./destination.mjs";
 // The same boundary as when the file was issued: a passphrase shorter than twelve characters will not open the file.
 const MIN_PASSPHRASE = 12;
 const STEPS = ["unlock", "sync", "sweep", "relay"];
+// `revealedHalf()` on the escrow. Public data: the function returns the half the settlement published.
+const REVEALED_HALF_SELECTOR = "0x3f267bb6";
 
 const contentsOf = (file) => (typeof file === "string" ? file : file && typeof file.contents === "string" ? file.contents : null);
 
@@ -50,7 +52,7 @@ const feeOf = async (wallet, signed) => {
   return /^\d+$/.test(text) ? text : null;
 };
 
-export function createSweep({ http, config }) {
+export function createSweep({ http, config, call = null }) {
   // THE NAME IS NEEDED BY THE OBJECT ITSELF: `run` calls `api.plan(...)` - the step order is held by the plan and
   // the withdrawal living in one object, not in two copies. During a manual merge of branches the object was left
   // unnamed, and the withdrawal failed with "api is not defined": not a refusal, but a breakdown. `node --check`
@@ -96,7 +98,7 @@ export function createSweep({ http, config }) {
     async destination(request = {}) {
       const contents = contentsOf(request.file);
       if (!contents) throw new SdkError("bad-input", { field: "file" });
-      if (!request.passphrase) throw new SdkError("bad-input", { field: "passphrase" });
+      if (typeof request.passphrase !== "string") throw new SdkError("bad-input", { field: "passphrase" });
       if (typeof request.dest !== "string" || !request.dest.trim()) throw new SdkError("bad-input", { field: "dest" });
       let payload = null;
       try { payload = await engine.recoveryFile.decryptFile(JSON.parse(contents), request.passphrase); }
@@ -110,7 +112,8 @@ export function createSweep({ http, config }) {
       if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
       const contents = contentsOf(request.file);
       if (!contents) throw new SdkError("bad-input", { field: "file" });
-      if (typeof request.passphrase !== "string" || request.passphrase.length < MIN_PASSPHRASE) {
+      // EMPTY IS ALLOWED: it opens an unencrypted file. A non-empty one keeps the floor.
+      if (typeof request.passphrase !== "string" || (request.passphrase.length > 0 && request.passphrase.length < MIN_PASSPHRASE)) {
         throw new SdkError("bad-input", { field: "passphrase", min: MIN_PASSPHRASE });
       }
 
@@ -150,10 +153,25 @@ export function createSweep({ http, config }) {
       // the named path, body { network, address }, where address is the ESCROW ADDRESS (not the Monero address).
       // The half is published by the settlement that moves the ETH: a claim or a refund. Before that no one has the
       // spend key, so "not revealed yet" is not an error but a state, and that is exactly where it lands in `missing`.
+      // THE COUNTERPARTY'S REVEALED HALF - FROM THE CHAIN WHEN THE CALLER HAS A CHAIN READ. The half is public:
+      // `claim` and `refund` store it in `revealedHalf()` and emit `HalfRevealed`. A recovery page served from a
+      // static host has no `/escrow/revealed-half` route, so asking the app was the only path and a static page
+      // could never withdraw. The app route stays as the fallback for a caller that has no chain read and did
+      // configure an API base.
       let revealed = false;
       let revealedValue = null;
       const escrowAddress = wallet.escrowAddress || (payload.escrow && payload.escrow.address) || null;
-      if (escrowAddress) {
+      if (escrowAddress && typeof call === "function") {
+        try {
+          const word = String((await call({ to: escrowAddress, data: REVEALED_HALF_SELECTOR })) || "");
+          const hex = word.startsWith("0x") ? word.slice(2) : word;
+          if (/^[0-9a-fA-F]{64}$/.test(hex) && !/^0+$/.test(hex)) {
+            revealed = true;
+            revealedValue = "0x" + hex.slice(24);
+          }
+        } catch { revealed = false; }
+      }
+      if (!revealed && escrowAddress && config && config.apiBase) {
         try {
           const half = await http.json(config.route("revealedHalf"), {
             method: "POST",

package/src/version.mjs

@@ -6,4 +6,4 @@
 // tools/sync-version.mjs. Do not edit it by hand - set the version in package.json and run `npm run sync:version`.
 // The `version` check in tools/check.mjs refuses a mismatch, and refuses a runtime read of package.json here.
 
-export const SDK_VERSION = "0.44.3";
+export const SDK_VERSION = "0.46.0";