@ninsei-labs/sdk 0.43.3 → 0.44.1

package/src/recovery.mjs

@@ -3,6 +3,12 @@
 //
 // The file arrives from the interface as a string or as `{ contents }`: the SDK knows neither about
 // <input type=file> nor about buffers - that is the interface's business.
+//
+// THE RESTORE HEIGHT IS A RULE, NOT A LOOKUP THE PAGE PERFORMS. Two sources exist: the height written into the
+// file when it was issued, and the height the service learned when it registered the wallet (it watches the
+// address, so its row is often more precise). The order between them is the package's: the service's height wins
+// when it is known, the file's is the fallback, and NO height is a named state - not a refusal, because the
+// person can still type one.
 import * as engine from "./engine.mjs";
 import { SdkError } from "./errors.mjs";
 
@@ -12,7 +18,7 @@ const contentsOf = (file) => {
   return null;
 };
 
-export function createRecovery() {
+export function createRecovery({ http = null, config = null } = {}) {
   return {
     async open(file, passphrase) {
       const contents = contentsOf(file);
@@ -36,5 +42,70 @@ export function createRecovery() {
         swapId: typeof payload.swapId === "string" ? payload.swapId : null,
       };
     },
+
+    // WHICH HEIGHT TO SCAN FROM, AND WHERE IT CAME FROM. The page used to run this lookup itself: it read the
+    // file, then asked the service by address. Two readers of one rule is how a page and a package drift, so the
+    // lookup lives here and the answer names its source.
+    //
+    // A SERVICE THAT DOES NOT ANSWER IS NOT A REFUSAL. The file's height is still a height; with neither, the
+    // answer is `source: "none"` and the interface asks the person. The problem is a token, never a message.
+    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) {
+        throw new SdkError("bad-input", { field: "passphrase" });
+      }
+      // THE ENVELOPE IS PARSED HERE: `restoreFromFile` takes the OBJECT, while the file arrives as text. Doing it
+      // in one place keeps "not JSON" a named stage instead of a library message.
+      let envelope;
+      try {
+        envelope = JSON.parse(contents);
+      } catch {
+        throw new SdkError("recovery-failed", { stage: "parse" });
+      }
+      // ONLY THE PAYLOAD IS NEEDED, NOT A RESTORED WALLET: the height and the address live in the decrypted
+      // payload, while restoring a wallet would rebuild keys from the halves - work this answer does not use, and
+      // work that needs the browser's crypto vendor.
+      let payload;
+      try {
+        payload = await engine.recoveryFile.decryptFile(envelope, request.passphrase);
+        engine.recoveryFile.validatePayload(payload);
+      } catch {
+        throw new SdkError("recovery-failed", { stage: "restore" });
+      }
+      const wallet = payload.moneroWallet || {};
+      const address = typeof wallet.address === "string" && wallet.address ? wallet.address : null;
+      const fileHeight = Number(wallet.restoreHeight) || 0;
+
+      let appHeight = 0;
+      let appAsked = false;
+      let appProblem = null;
+      if (http && config && address) {
+        appAsked = true;
+        try {
+          const answer = await http.json(config.route("swaps"));
+          const rows = Array.isArray(answer) ? answer : ((answer && answer.swaps) || []);
+          const row = rows.find((x) => String((x && x.address) || "") === String(address)) || null;
+          appHeight = Number(row && row.restoreHeight) || 0;
+          if (!row) appProblem = "no-row";
+        } catch {
+          appProblem = "unreachable";
+        }
+      }
+
+      const height = appHeight > 0 ? appHeight : fileHeight;
+      const source = appHeight > 0 ? "app" : (fileHeight > 0 ? "file" : "none");
+      return {
+        address,
+        height,
+        source,
+        fileHeight,
+        appHeight,
+        appAsked,
+        // Why there is no height, when there is none: a token the interface turns into words. Null when a height
+        // was found, so a reader cannot mistake "found" for "asked and failed".
+        appProblem: source === "none" ? (appProblem || "no-height") : null,
+      };
+    },
   };
 }

package/src/sweep-restore.mjs

@@ -0,0 +1,130 @@
+// RESTORING THE WITHDRAWAL WALLET: THE PASS BEFORE ANYTHING IS SIGNED.
+//
+// WHY THIS IS IN THE PACKAGE. The sweep page used to run this itself: set the restore height ten blocks below
+// the one the file names, rescan, sync, read the balance, and - if the balance was non-zero while nothing was
+// spendable - rescan the spent status and sync again. The second pass was not a guess: coins are locked for ten
+// blocks after they arrive, and the spent status of outputs restored from a key is not known until the wallet
+// asks the chain. Both are facts about wallet2, not about a page, and a node or a CLI needs the same pass.
+//
+// WHAT IS NOT HERE: creating the wallet, opening it and closing it. The wallet arrives as the same withdrawal
+// adapter the signing step takes (`sync`, `unlockedBalance`, `driver`); who built it and where the WASM and the
+// worker live is the caller's business.
+//
+// REFUSALS CARRY CODES. A missing method, a missing height and a library error all come out as `SdkError`; a
+// low-level exception never escapes with `code: null`, because the interface has no phrase for it and a check
+// cannot assert it.
+import { SdkError } from "./errors.mjs";
+
+// THE SECOND PASS IS BOUNDED: a wallet that reports a balance but no spendable coins twice is not helped by a
+// third pass, and repeating it would only make an empty answer slower to arrive.
+const PASSES = 2;
+// HOW FAR BELOW THE NAMED HEIGHT THE SCAN STARTS. A gap in an arrival block is worth more than the ten blocks it
+// costs: scanning from the exact height has already missed an arrival one block earlier.
+const SCAN_BACK = 10;
+
+const asAmount = (value, field) => {
+  try {
+    return BigInt(value);
+  } catch {
+    throw new SdkError("bad-input", { field });
+  }
+};
+
+const driverOf = (wallet) => {
+  if (!wallet || typeof wallet.driver !== "function") throw new SdkError("bad-input", { field: "wallet.driver" });
+  const driver = wallet.driver();
+  if (!driver || typeof driver !== "object") throw new SdkError("bad-input", { field: "wallet.driver" });
+  const missing = ["setRestoreHeight", "getBalance"].filter((name) => typeof driver[name] !== "function");
+  if (missing.length) throw new SdkError("bad-input", { field: "wallet.driver", missing });
+  return driver;
+};
+
+// A WALLET STEP THAT FAILS IS A REFUSAL WITH A CODE, never raw library text. The surface is named so a reader can
+// tell which call went wrong.
+const step = async (surface, fn) => {
+  try {
+    return await fn();
+  } catch (error) {
+    if (error instanceof SdkError) throw error;
+    throw new SdkError("wallet-rejected", { surface, why: String((error && error.message) || error) });
+  }
+};
+
+const heightOf = async (driver, name) => {
+  if (typeof driver[name] !== "function") return null;
+  try {
+    const value = await driver[name]();
+    const number = Number(value);
+    return Number.isFinite(number) ? number : null;
+  } catch {
+    // A missing height is not a refusal: the balance is the answer this pass exists for.
+    return null;
+  }
+};
+
+/**
+ * Restore the wallet from a height and report what it holds.
+ *
+ * @param {object} request
+ * @param {object} request.wallet   the withdrawal adapter: `sync`, `unlockedBalance`, `driver`
+ * @param {number} request.fromHeight the height the file names; the scan starts a little below it
+ * @param {number} [request.scanBack] how far below, default 10
+ * @param {boolean} [request.rescanWhenLocked] run the second pass, default true
+ * @returns {Promise<{total: string, unlocked: string, scanHeight: number, walletHeight: number|null,
+ *   nodeHeight: number|null, passes: number, lockedPass: boolean}>}
+ */
+export async function restoreWallet(request = {}) {
+  const wallet = request.wallet;
+  if (!wallet || typeof wallet !== "object") throw new SdkError("bad-input", { field: "wallet" });
+  const missing = ["sync", "unlockedBalance"].filter((name) => typeof wallet[name] !== "function");
+  if (missing.length) throw new SdkError("bad-input", { field: "wallet", missing });
+
+  const fromHeight = Number(request.fromHeight);
+  if (!Number.isFinite(fromHeight) || fromHeight <= 0) throw new SdkError("bad-input", { field: "restoreHeight" });
+
+  const scanBack = Number.isFinite(Number(request.scanBack)) && Number(request.scanBack) >= 0
+    ? Math.floor(Number(request.scanBack))
+    : SCAN_BACK;
+  const scanHeight = Math.max(0, Math.floor(fromHeight) - scanBack);
+  const driver = driverOf(wallet);
+
+  await step("setRestoreHeight", () => driver.setRestoreHeight(scanHeight));
+  // A RESCAN IS REQUIRED, NOT OPTIONAL: without it the height only applies to a wallet that has not scanned yet,
+  // and a wallet restored from a key has. A driver that cannot rescan is the caller's mistake, named here.
+  if (typeof driver.rescanBlockchain !== "function") throw new SdkError("bad-input", { field: "wallet.driver.rescanBlockchain" });
+  await step("rescanBlockchain", () => driver.rescanBlockchain());
+
+  // A FAILED SYNC IS BEST-EFFORT, exactly as in the signing step: what blocks a withdrawal is the spendable
+  // remainder, and it is read below. The library throws low-level while scanning a chain it cannot read; that must
+  // not pre-empt the verdict.
+  try { await wallet.sync(); } catch { /* the remainder decides */ }
+
+  let total = asAmount(await step("getBalance", () => driver.getBalance()), "balance");
+  let unlocked = asAmount(await step("unlockedBalance", () => wallet.unlockedBalance()), "unlockedBalance");
+  let passes = 1;
+  let lockedPass = false;
+
+  // THE SECOND PASS: coins exist but none is spendable. The spent status is re-checked and the wallet is synced
+  // again; the arrival may have been locked by time rather than lost.
+  const rescanWhenLocked = request.rescanWhenLocked !== false;
+  if (rescanWhenLocked && total > 0n && unlocked === 0n && typeof driver.rescanSpent === "function" && passes < PASSES) {
+    lockedPass = true;
+    await step("rescanSpent", () => driver.rescanSpent());
+    try { await wallet.sync(); } catch { /* as above */ }
+    total = asAmount(await step("getBalance", () => driver.getBalance()), "balance");
+    unlocked = asAmount(await step("unlockedBalance", () => wallet.unlockedBalance()), "unlockedBalance");
+    passes += 1;
+  }
+
+  return {
+    total: total.toString(),
+    unlocked: unlocked.toString(),
+    scanHeight,
+    walletHeight: await heightOf(driver, "getHeight"),
+    nodeHeight: await heightOf(driver, "getDaemonHeight"),
+    passes,
+    // Whether the second pass RAN - not whether it helped. A reader must be able to tell "nothing was locked" from
+    // "it was locked and stayed locked".
+    lockedPass,
+  };
+}

package/src/sweep.mjs

@@ -7,6 +7,9 @@
 import { SdkError } from "./errors.mjs";
 import { primitives } from "./primitives.mjs";
 import * as engine from "./engine.mjs";
+import { restoreWallet } from "./sweep-restore.mjs";
+import { moneroWalletAdapter } from "./adapters/monero-wallet.mjs";
+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;
@@ -30,6 +33,23 @@ const walletStep = async (surface, step) => {
   }
 };
 
+// THE FEE A WALLET REPORTS FOR A SIGNED TRANSACTION. Optional on purpose: the adapter contract does not require
+// it, and an adapter without it is not broken - the answer is simply unknown. The library's own shape is tried
+// (`getFee()` on the transaction or on the signed wrapper), because that is what monero-ts returns; a value that is
+// not a non-negative integer string is refused as unknown rather than trusted.
+const feeOf = async (wallet, signed) => {
+  if (!wallet || typeof wallet.fee !== "function") return null;
+  let value;
+  try {
+    value = await wallet.fee(signed);
+  } catch {
+    return null;
+  }
+  if (value === null || value === undefined) return null;
+  const text = String(value);
+  return /^\d+$/.test(text) ? text : null;
+};
+
 export function createSweep({ http, config }) {
   // 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
@@ -40,7 +60,52 @@ export function createSweep({ http, config }) {
   const sessions = new Map();
   let sessionSeq = 0;
 
+  // THE NETWORK NAME MONERO-TS TAKES. The adapter speaks a string ("stagenet") because that is what a node says and
+  // what a human reads; the library wants its own enum. That translation used to be a callback on the sweep page -
+  // the last thing a caller had to know about the library to open a wallet.
+  const NETWORK_ENUM = { mainnet: "MAINNET", stagenet: "STAGENET", testnet: "TESTNET" };
+
   const api = {
+    // BUILD THE WITHDRAWAL WALLET from the library namespace the caller has. The page used to pass a `createWallet`
+    // callback that mapped the enum itself; that mapping is here now, so a caller passes `moneroTs` and the keys.
+    wallet(request = {}) {
+      const moneroTs = request.moneroTs;
+      if (!moneroTs || typeof moneroTs !== "object") throw new SdkError("bad-input", { field: "moneroTs" });
+      if (typeof moneroTs.createWalletFull !== "function") throw new SdkError("bad-input", { field: "moneroTs.createWalletFull" });
+      const network = String(request.network || "").trim().toLowerCase();
+      const enumName = NETWORK_ENUM[network] || null;
+      const enumValue = enumName && moneroTs.MoneroNetworkType ? moneroTs.MoneroNetworkType[enumName] : undefined;
+      if (enumValue === undefined || enumValue === null) {
+        throw new SdkError("bad-input", { field: "network", known: Object.keys(NETWORK_ENUM), got: request.network });
+      }
+      if (typeof request.serverUri !== "string" || !request.serverUri) throw new SdkError("bad-input", { field: "serverUri" });
+      return moneroWalletAdapter({
+        createWallet: (config) => moneroTs.createWalletFull({ ...config, networkType: enumValue }),
+        network,
+        serverUri: request.serverUri,
+        password: request.password,
+        keys: request.keys || {},
+        restoreHeight: request.restoreHeight,
+        expectedAddress: request.expectedAddress || null,
+      });
+    },
+
+    // WHERE THE WITHDRAWAL GOES. The file names the recipient the swap was made for; this compares the address the
+    // person typed with that promise and with the file's network. `matches` is null when the file named nobody -
+    // that is not a failure, it is an absence the caller can phrase.
+    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.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); }
+      catch { throw new SdkError("recovery-failed", { step: "decrypt" }); }
+      try { engine.recoveryFile.validatePayload(payload); }
+      catch { throw new SdkError("recovery-failed", { step: "validate" }); }
+      return checkDestination(payload, request.dest);
+    },
+
     async plan(request) {
       if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
       const contents = contentsOf(request.file);
@@ -145,6 +210,13 @@ export function createSweep({ http, config }) {
       }
     },
 
+    // THE PASS BEFORE SIGNING: set the height, rescan, sync, read the balance, and - when coins exist but none is
+    // spendable - re-check the spent status once. The wallet is the same withdrawal adapter `sign` takes; the page
+    // no longer decides when a second pass is needed.
+    async restore(request) {
+      return await restoreWallet(request || {});
+    },
+
     // THE WITHDRAWAL ITSELF. The wallet arrives as an adapter (the WASM and the worker live with whoever builds the
     // page), while the core holds the order: open -> sync -> look at the free remainder -> SIGN (relay: false) ->
     // send -> close.
@@ -202,9 +274,26 @@ export function createSweep({ http, config }) {
         // zero, and the refusal would look like success.
         if (unlocked <= 0n) throw new SdkError("insufficient-funds", { unlocked: unlocked.toString() });
         const signed = await walletStep("sweepUnlocked", () => wallet.sweepUnlocked({ address: request.to, relay: false }));
+        // WHAT THE TRANSFER COSTS, WHEN THE WALLET CAN SAY. A withdrawal moves the whole free remainder, so the fee
+        // is not extra money on top - it is taken out of it, and the recipient receives the remainder MINUS the fee.
+        // An adapter that cannot report a fee answers null; publishing 0 there would be a claim the package cannot
+        // support, and the interface would show a free transfer.
+        const fee = await feeOf(wallet, signed);
+        const feeValue = fee === null ? null : BigInt(fee);
         const token = "sweep-" + (++sessionSeq);
         sessions.set(token, { wallet, plan, signed });
-        return { token, amount: unlocked.toString(), to: request.to, swept: plan.address };
+        return {
+          token,
+          amount: unlocked.toString(),
+          // The fee in atomic units, or null when the wallet could not report it.
+          fee,
+          // What the recipient receives: the remainder minus the fee. Null whenever the fee is unknown, and null
+          // rather than a negative number when a fee claims more than the remainder (that is a broken report, not
+          // a transfer).
+          receive: feeValue === null || feeValue >= unlocked ? null : (unlocked - feeValue).toString(),
+          to: request.to,
+          swept: plan.address,
+        };
       } catch (error) {
         // There is no signature - we do not leave an open wallet. Closing must not hide the refusal's reason.
         try { await wallet.close(); } catch { /* the reason matters more than closing */ }

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.43.3";
+export const SDK_VERSION = "0.44.1";