@ninsei-labs/sdk 0.39.0

package/src/sweep.mjs

@@ -0,0 +1,222 @@
+// XMR WITHDRAWAL: PARSING THE FILE AND PREPARING. The withdrawal itself requires a Monero wallet - it arrives as
+// an adapter.
+//
+// Here is exactly what the sweep page does before syncing: decrypt the recovery file, validate it, take the shared
+// address, ask the app for the restore height (on the page it is taken by address) and say aloud what is missing
+// so the withdrawal can go. Funds do not move at this step.
+import { SdkError } from "./errors.mjs";
+import { primitives } from "./primitives.mjs";
+import * as engine from "./engine.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"];
+
+const contentsOf = (file) => (typeof file === "string" ? file : file && typeof file.contents === "string" ? file.contents : 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
+  // unnamed, and the withdrawal failed with "api is not defined": not a refusal, but a breakdown. `node --check`
+  // misses this, there are no conflict markers in the file - only a run shows it.
+  // AN OPEN SIGN SESSION: a token -> { wallet, plan, signed }. It lives until `relay`; it keeps no keys - they are
+  // owned by the library's wallet.
+  const sessions = new Map();
+  let sessionSeq = 0;
+
+  const api = {
+    async plan(request) {
+      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) {
+        throw new SdkError("bad-input", { field: "passphrase", min: MIN_PASSPHRASE });
+      }
+
+      let envelope = null;
+      try { envelope = JSON.parse(contents); } catch { throw new SdkError("recovery-failed", { step: "parse" }); }
+      let payload = null;
+      try { payload = await engine.recoveryFile.decryptFile(envelope, request.passphrase); } catch { throw new SdkError("recovery-failed", { step: "decrypt" }); }
+      // We check the composition BEFORE the work: a file that does not pass its own check is not good for withdrawal.
+      try { engine.recoveryFile.validatePayload(payload); } catch { throw new SdkError("recovery-failed", { step: "validate" }); }
+
+      const wallet = payload.moneroWallet || {};
+      const address = wallet.address || null;
+      if (!address) throw new SdkError("recovery-failed", { step: "address" });
+
+      const missing = [];
+      // WHAT WE CAN DISPOSE OF: our own half of the spend key. Without it the withdrawal is impossible under any
+      // circumstances, and that must be said before syncing, not after.
+      const spendable = !!wallet.spendHalf;
+      if (!spendable) missing.push("spendable");
+
+      // THE RESTORE HEIGHT: first from the file, then from the app BY ADDRESS - exactly as the sweep page does it.
+      // An unavailable app is a lack of data, not a refusal: the plan is returned anyway, and `missing` shows what
+      // is lacking.
+      let restoreHeight = Number(wallet.restoreHeight) || 0;
+      let row = null;
+      try {
+        // THE PATH BY NAME, not by a string: the override comes through the `routes` option.
+        const answer = await http.json(config.route("swaps"));
+        const rows = Array.isArray(answer) ? answer : ((answer && answer.swaps) || []);
+        row = rows.find((x) => String((x && x.address) || "") === String(address)) || null;
+      } catch { row = null; }
+      const fromApp = Number(row && row.restoreHeight) || 0;
+      if (fromApp > 0) restoreHeight = fromApp;
+      if (!(restoreHeight > 0)) missing.push("restore-height");
+
+      // THE COUNTERPARTY'S REVEALED HALF - FROM THE CHAIN, VIA THE APP. Exactly as the sweep page does it: POST to
+      // 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`.
+      let revealed = false;
+      let revealedValue = null;
+      const escrowAddress = wallet.escrowAddress || (payload.escrow && payload.escrow.address) || null;
+      if (escrowAddress) {
+        try {
+          const half = await http.json(config.route("revealedHalf"), {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ network: payload.network, address: escrowAddress }),
+          });
+          revealed = !!(half && half.ok && half.revealed && half.half);
+          if (revealed) revealedValue = String(half.half);
+        } catch { revealed = false; }
+      }
+      if (!revealed) missing.push("revealed-half");
+
+      return {
+        swapId: payload.swapId || null,
+        address,
+        spendable,
+        restoreHeight,
+        steps: STEPS,
+        // Whether the counterparty's half is revealed: this is a separate flag, not "absent from the missing list".
+        revealedHalf: revealed,
+        half: revealedValue,
+        missing,
+      };
+    },
+
+    // THE WITHDRAWAL KEYS. They are computed here and checked here too - for the reason that the contract cannot do
+    // it: it will check the hash of the revealed half, but not the link "half and the point in the address" - there
+    // is no ed25519 in EVM. So before syncing we must make sure that (s_a + s_b)*G matched the order's spend key. It
+    // did not match - we must not send: the XMR would go nowhere, while it would look like success.
+    async keys(request) {
+      const plan = await api.plan(request);
+      if (!plan.half) throw new SdkError("bad-input", { field: "revealedHalf", why: "not-revealed" });
+      const contents = contentsOf(request.file);
+      let payload = null;
+      try { payload = await engine.recoveryFile.decryptFile(JSON.parse(contents), request.passphrase); }
+      catch { throw new SdkError("recovery-failed", { step: "decrypt" }); }
+      const wallet = payload.moneroWallet || {};
+      const need = ["spendHalf", "viewHalf", "otherSpendPoint", "otherViewHalf"];
+      const missingFields = need.filter((k) => wallet[k] === undefined || wallet[k] === null || wallet[k] === "");
+      if (missingFields.length) throw new SdkError("bad-input", { field: "payload", missing: missingFields });
+      try {
+        const halves = engine.halves.createHalves(primitives);
+        const keys = engine.halvesSweep.spendKeysFromRevealedHalf({
+          halves,
+          ownSpendHalf: wallet.spendHalf, ownViewHalf: wallet.viewHalf,
+          otherSpendPoint: wallet.otherSpendPoint, otherViewHalf: wallet.otherViewHalf,
+          revealedHalf: plan.half,
+        });
+        return { privateSpendKey: keys.privateSpendKey, privateViewKey: keys.privateViewKey, address: plan.address };
+      } catch {
+        // THE CHECK DID NOT PASS: the half is from another order or was substituted. This is a refusal with a code,
+        // not an engine exception with text inside.
+        throw new SdkError("bad-input", { field: "revealedHalf", step: "verify" });
+      }
+    },
+
+    // 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.
+    //
+    // SIGNING AND SENDING ARE DELIBERATELY SPLIT: between them the interface has time to show the person what will
+    // leave, rather than telling them about it after sending. An empty remainder stops the withdrawal BEFORE
+    // signing - otherwise the wallet would sign a transaction for zero and the refusal would look like success.
+    // TELLING THE SERVICE ABOUT THE WITHDRAWAL - SEPARATELY AND REPEATABLY. The mark does not affect the transfer
+    // (it is already on the network), so it can be repeated: the interface calls this even after `relay` if the
+    // report did not go through then.
+    async report(request) {
+      if (!request || typeof request.swapId !== "string" || !request.swapId) throw new SdkError("bad-input", { field: "swapId" });
+      if (typeof request.txid !== "string" || !request.txid) throw new SdkError("bad-input", { field: "txid" });
+      try {
+        const answer = await http.json(config.route("swept", { id: request.swapId }), {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ txid: request.txid }),
+        });
+        return { reported: !(answer && answer.ok === false) };
+      } catch {
+        // The service is unavailable - that is `reported: false`, not a withdrawal refusal: the money has already left.
+        return { reported: false };
+      }
+    },
+
+    // SIGNING WITHOUT SENDING - AS A SEPARATE STEP. The core HOLDS the signed transaction until the person's
+    // decision: otherwise the interface could not show what exactly will leave, and would tell about it only after
+    // sending. Here is the whole order UP TO AND INCLUDING SIGNING: plan -> wallet -> open -> sync -> free remainder
+    // (an empty one STOPS the withdrawal with a code) -> sign (relay: false). The wallet stays open until `relay`,
+    // and the session token is the only handle to it.
+    async sign(request) {
+      const plan = await api.plan(request);
+      if (!request || typeof request.to !== "string" || !request.to) throw new SdkError("bad-input", { field: "to" });
+      if (typeof request.connectWallet !== "function") throw new SdkError("bad-input", { field: "connectWallet" });
+      const wallet = await request.connectWallet(plan);
+      const role = ["open", "sync", "unlockedBalance", "sweepUnlocked", "relay", "close"];
+      const missing = role.filter((name) => !wallet || typeof wallet[name] !== "function");
+      if (missing.length) throw new SdkError("bad-input", { field: "wallet", missing });
+
+      await wallet.open(plan);
+      try {
+        await wallet.sync();
+        const unlocked = BigInt(await wallet.unlockedBalance());
+        // AN EMPTY REMAINDER STOPS THE WITHDRAWAL BEFORE SIGNING: otherwise the wallet would sign a transaction for
+        // zero, and the refusal would look like success.
+        if (unlocked <= 0n) throw new SdkError("insufficient-funds", { unlocked: unlocked.toString() });
+        const signed = await wallet.sweepUnlocked({ address: request.to, relay: false });
+        const token = "sweep-" + (++sessionSeq);
+        sessions.set(token, { wallet, plan, signed });
+        return { token, amount: unlocked.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 */ }
+        throw error;
+      }
+    },
+
+    // SENDING THE SIGNED AND MARKING THE WITHDRAWAL. Sending is split from signing by the same seam as the session:
+    // the person has time to see the transfer before it leaves.
+    async relay(request) {
+      if (!request || typeof request.token !== "string" || !request.token) throw new SdkError("bad-input", { field: "token" });
+      const session = sessions.get(request.token);
+      if (!session) throw new SdkError("bad-input", { field: "token", why: "no-open-session" });
+      sessions.delete(request.token);
+      const { wallet, plan, signed } = session;
+      try {
+        const txids = await wallet.relay(signed);
+        const list = Array.isArray(txids) ? txids : [];
+        // MARKING THE WITHDRAWAL - AFTER SENDING AND NOT AFFECTING IT. The transfer is already on the network; the
+        // report merely tells the service that the XMR left. So a failed report does NOT make the withdrawal
+        // unsuccessful: it gives `reported: false`, so the interface offers to report again - by the same path as
+        // here (`report`).
+        const reported = plan.swapId && list.length
+          ? (await api.report({ swapId: plan.swapId, txid: list[0] })).reported
+          : false;
+        return { txids: list, swept: plan.address, reported };
+      } finally {
+        await wallet.close();
+      }
+    },
+
+    // THE WITHDRAWAL AS A WHOLE - THE SAME ORDER, ONE CALL. This is a WRAPPER over sign and relay, NOT a second
+    // step order: otherwise an edit in one place would diverge from the other.
+    async run(request) {
+      const opened = await api.sign(request);
+      return await api.relay({ token: opened.token });
+    },
+  };
+  return api;
+}

package/src/wallet.mjs

@@ -0,0 +1,164 @@
+// THE WALLET OUTSIDE AND WITHOUT KNOWLEDGE OF THE CHAIN (issue #32, requirement 4; extensibility for Tron and Solana).
+//
+// The SDK core knows neither EIP-1193, nor WalletConnect, nor the Solana wallet-standard. It knows the ADAPTER
+// INTERFACE: vm, connect, disconnect, address, chainId, subscribe, driver - and requires the adapter to be for
+// the SAME vm as the settlement network. The interface brings the wallet:
+// `import { evmWallet } from "@ninsei-labs/sdk/adapters"`.
+//
+// It opens no windows and does not reach into others' settings: for EVM the network is switched through the
+// provider, for other VMs it may not exist at all - then the honest answer is `not-implemented`, not a silent
+// "nothing happened".
+import { ERROR_CODES } from "./codes.mjs";
+import { SdkError, fail } from "./errors.mjs";
+
+const REQUIRED = ["connect", "disconnect", "address", "chainId", "subscribe", "driver"];
+
+/** The adapter's refusal code, if it is declared by the contract; otherwise `unknown` (the adapter's text does not go out). */
+const codeOf = (error) => (error && ERROR_CODES.includes(error.code) ? error.code : "unknown");
+
+// THE OTHER SIDE OF THE SWAP IS MONERO. It cannot be the settlement network: Monero has no leg contract, so its
+// wallet arrives as an adapter with this VM, and it reads the balance itself - there is no leg to delegate that to.
+const XMR_VM = "monero";
+// THE ATOMIC UNIT OF XMR: 1 XMR = 10^12 piconero (12 decimal places). monero-ts returns getUnlockedBalance in
+// these, and sweep takes the free remainder in them too; the core does NOT reconvert these units.
+const XMR_TOKEN = { token: "xmr", symbol: "XMR", decimals: 12 };
+// THE STAGE AT WHICH SWITCHING THE NETWORK OF OTHER VMs WILL ARRIVE: stage 2 (sdk/README.md, "Stages") - the demo
+// screens move onto the SDK. Until then the wallet switches the network itself, and that is NAMED by a code with
+// the stage number, not swallowed.
+const SWITCH_STAGE = 2;
+
+export function createWallet({ settlement, leg }) {
+  let adapter = null;
+  let cached = { connected: false, address: null, chainId: null, chainMatches: false };
+  const listeners = new Set();
+  let detach = null;
+
+  const settle = async (notify = true) => {
+    if (!adapter) return cached;
+    const [address, chainId] = await Promise.all([
+      Promise.resolve(adapter.address()).catch(() => null),
+      Promise.resolve(adapter.chainId()).catch(() => null),
+    ]);
+    const connected = typeof address === "string" && address.length > 0;
+    cached = {
+      connected,
+      address: connected ? address : null,
+      chainId: chainId === undefined ? null : chainId,
+      chainMatches: connected && leg.sameChain(chainId, settlement),
+    };
+    if (notify) for (const handler of listeners) handler(cached);
+    return cached;
+  };
+
+  const close = () => {
+    if (typeof detach === "function") detach();
+    detach = null;
+  };
+
+  return {
+    use(next) {
+      if (!next || typeof next !== "object") fail("bad-input", { field: "adapter" });
+      const missing = REQUIRED.filter((name) => typeof next[name] !== "function");
+      if (missing.length) fail("bad-input", { field: "adapter", missing });
+      if (typeof next.vm !== "string" || !next.vm) fail("bad-input", { field: "adapter.vm" });
+      // ANOTHER VM IS NOT SUBSTITUTED: the wallet is good either for the settlement network or for Monero - the
+      // other side of the swap (which has neither a leg driver nor the settlement network's chainId). Anything
+      // else is a refusal naming the vm.
+      const acceptedVms = [settlement.vm, XMR_VM];
+      if (!acceptedVms.includes(next.vm)) fail("bad-input", { field: "adapter.vm", expected: settlement.vm, accepted: acceptedVms, got: next.vm });
+      close();
+      adapter = next;
+      detach = adapter.subscribe(() => { settle().catch(() => {}); });
+      cached = { connected: false, address: null, chainId: null, chainMatches: false };
+      settle().catch(() => {});
+      return undefined;
+    },
+    // THE STATE IS RETURNED FROM MEMORY: reading from the wallet is asynchronous, while the interface needs the
+    // answer in the same render tick. Fresh reads are done by connect(), switchChain() and wallet events - they
+    // update the memory.
+    status: () => cached,
+    async connect({ chainId = null } = {}) {
+      if (!adapter) fail("wallet-not-connected");
+      try {
+        // THE SETTLEMENT NETWORK IS NAMED ONLY TO ITS OWN WALLET: we do not tell the Monero wallet a foreign
+        // chainId - its network is set by the Monero network, and an EVM chainId means nothing to it.
+        const want = chainId === null && adapter.vm === settlement.vm ? leg.walletChainId(settlement) : chainId;
+        await adapter.connect(want === null ? {} : { chainId: want });
+      } catch (error) {
+        throw new SdkError(codeOf(error), { vm: adapter.vm });
+      }
+      return settle();
+    },
+    async disconnect() {
+      if (adapter) await Promise.resolve(adapter.disconnect()).catch(() => {});
+      close();
+      adapter = null;
+      return void (await settle());
+    },
+    address: () => cached.address,
+    async switchChain(chainId) {
+      if (!adapter) fail("wallet-not-connected");
+      if (!Number.isFinite(Number(chainId))) fail("bad-input", { field: "chainId" });
+      // THE SETTLEMENT NETWORK IS SWITCHED BY THE SETTLEMENT WALLET, and only if it can. For another VM switching
+      // the network lives only in the wallet itself - then a NAMED refusal with the stage number, not silence: the
+      // interface will show its own action instead of deciding everything has already switched.
+      if (adapter.vm !== settlement.vm || typeof adapter.switchChain !== "function") {
+        fail("not-implemented", { surface: "wallet.switchChain", vm: adapter.vm, stage: SWITCH_STAGE });
+      }
+      try {
+        await adapter.switchChain(Number(chainId));
+      } catch (error) {
+        throw new SdkError(codeOf(error), { vm: adapter.vm });
+      }
+      // DO NOT TAKE IT ON TRUST - CHECK IT: the wallet could "switch" and remain on the previous network. We
+      // re-read the wallet's network (settle) and refuse if it is not the right one: otherwise a foreign balance
+      // would look like your own, and the signature would go to the wrong chain.
+      const status = await settle();
+      if (!status.chainMatches) fail("wrong-chain", { got: status.chainId, want: leg.walletChainId(settlement) });
+      return status;
+    },
+    /**
+     * BALANCES in minimal units (string): the native coin and the settlement network's tokens.
+     * They are read by the leg driver; an unread balance comes as null, not zero.
+     */
+    async balances(tokens) {
+      if (!adapter) fail("wallet-not-connected");
+      const status = cached.connected ? cached : await settle(false);
+      if (!status.connected) fail("wallet-not-connected");
+      // THE MONERO BALANCE IS THE WALLET'S OWN BUSINESS. Neither the leg nor the network check apply here: Monero
+      // has no leg driver and no settlement-network chainId. The wallet returns the free remainder BY THE SAME
+      // method as the XMR withdrawal (unlockedBalance; in monero-ts that is getUnlockedBalance), and in the same
+      // atomic units.
+      // THE UNITS ARE NOT RECONVERTED: an atomic unit arrives (1 XMR = 10^12), and BigInt turns it into a string -
+      // exactly as in sweep.mjs. The core keeps no unit arithmetic of its own.
+      if (adapter.vm === XMR_VM) {
+        const wantedXmr = Array.isArray(tokens) && tokens.length ? tokens.map((t) => String(t).toLowerCase()) : [XMR_TOKEN.token];
+        const unknownXmr = wantedXmr.find((id) => id !== XMR_TOKEN.token);
+        if (unknownXmr !== undefined) fail("bad-input", { field: "tokens", unknown: unknownXmr });
+        if (typeof adapter.unlockedBalance !== "function") fail("not-implemented", { surface: "wallet.balances", vm: XMR_VM });
+        const amount = BigInt(await adapter.unlockedBalance()).toString();
+        return [{ token: XMR_TOKEN.token, symbol: XMR_TOKEN.symbol, decimals: XMR_TOKEN.decimals, amount }];
+      }
+      // ON A FOREIGN NETWORK THE BALANCE IS NOT READ: it is a number from a different network, and it would look like an empty wallet.
+      if (!status.chainMatches) fail("wrong-chain", { got: status.chainId, want: leg.walletChainId(settlement) });
+      if (typeof leg.balances !== "function") fail("not-implemented", { surface: "wallet.balances", vm: settlement.vm });
+      const all = settlement.tokens || [];
+      const wanted = Array.isArray(tokens) && tokens.length ? tokens.map((t) => String(t).toLowerCase()) : all.map((t) => t.id);
+      const picked = [];
+      for (const id of wanted) {
+        const token = all.find((t) => t.id === id);
+        if (!token) fail("bad-input", { field: "tokens", unknown: id });
+        picked.push(token);
+      }
+      return leg.balances({ driver: adapter.driver(), address: status.address, tokens: picked });
+    },
+    subscribe(handler) {
+      if (typeof handler !== "function") fail("bad-input", { field: "handler" });
+      listeners.add(handler);
+      return () => listeners.delete(handler);
+    },
+    // INTERNAL, FOR THE LEG DRIVER: the provider/wallet client itself. It is not in the contract: the interface
+    // does not need it, and the leg takes it from the SDK in one place.
+    driver: () => (adapter ? adapter.driver() : null),
+  };
+}