@ninsei-labs/sdk 0.53.0 → 0.55.0

package/src/relayView.mjs

@@ -0,0 +1,110 @@
+// THE VIEW MATERIAL A RELAY REQUEST CARRIES.
+//
+// The relay `firm/1` exchange does not send a Monero view scalar in clear text. The client chooses the view
+// halves, keeps them in its recovery material, and encrypts only the node's share to the X25519 key in the
+// signed public features. The profile is fixed by the relay wire spec: HPKE RFC 9180 base mode, DHKEM(X25519,
+// HKDF-SHA256), HKDF-SHA256 and ChaCha20-Poly1305.
+//
+// This module owns the profile, not the request shape. It names one encryption and one decryption, both taking
+// the application `info` as bytes, so the caller cannot accidentally use a different suite or a different
+// interpretation of the context. The relay client builds `info` with `relayViewInfo`.
+import { CipherSuite, DhkemX25519HkdfSha256, HkdfSha256 } from "@hpke/core";
+import { Chacha20Poly1305 } from "@hpke/chacha20poly1305";
+import { SdkError } from "./errors.mjs";
+
+const utf8 = (value) => new TextEncoder().encode(String(value));
+
+const bytesOf = (value) => {
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  throw new SdkError("bad-input", { field: "viewEnvelope" });
+};
+
+const bytesToHex = (bytes) => {
+  let out = "0x";
+  for (const byte of bytesOf(bytes)) out += byte.toString(16).padStart(2, "0");
+  return out;
+};
+
+const hexToBytes = (value, width, field) => {
+  const text = String(value === undefined || value === null ? "" : value).replace(/^0x/, "");
+  if (!new RegExp("^[0-9a-fA-F]{" + (width * 2) + "}$").test(text)) {
+    throw new SdkError("bad-input", { field });
+  }
+  const out = new Uint8Array(width);
+  for (let i = 0; i < width; i += 1) out[i] = parseInt(text.slice(i * 2, i * 2 + 2), 16);
+  return out;
+};
+
+const suite = () => new CipherSuite({
+  kem: new DhkemX25519HkdfSha256(),
+  kdf: new HkdfSha256(),
+  aead: new Chacha20Poly1305(),
+});
+
+// The relay binds encryption to the exact terms, the client half and both view points. The prefix and the
+// order of the five words are part of the wire format; a different order still decrypts, which is why it is
+// built here once instead of at each call site.
+export const RELAY_VIEW_INFO_PREFIX = "ninsei-relay-view-v1";
+
+export function relayViewInfo({ termsDigest, commitHalf, edPoint, edViewPointClient, edViewPointNode } = {}) {
+  const words = [
+    ["termsDigest", termsDigest],
+    ["commitHalf", commitHalf],
+    ["edPoint", edPoint],
+    ["edViewPointClient", edViewPointClient],
+    ["edViewPointNode", edViewPointNode],
+  ].map(([field, value]) => hexToBytes(value, 32, field));
+  const prefix = utf8(RELAY_VIEW_INFO_PREFIX);
+  const out = new Uint8Array(prefix.length + words.reduce((n, word) => n + word.length, 0));
+  out.set(prefix, 0);
+  let at = prefix.length;
+  for (const word of words) { out.set(word, at); at += word.length; }
+  return out;
+}
+
+// One sender context, one Seal. The relay spec forbids reusing an ephemeral key for another encryption, so
+// the context is created here and never exposed.
+export async function sealViewEnvelope({ hpkeKey, info, plaintext } = {}) {
+  // The two plaintext lengths are part of the wire contract: ask carries the node's view scalar, bid carries
+  // the node's scalar followed by the client's. A caller that passes another length is refused before any
+  // network or cryptographic work.
+  const publicKey = hexToBytes(hpkeKey, 32, "hpkeKey");
+  const body = bytesOf(plaintext);
+  if (body.length !== 32 && body.length !== 64) {
+    throw new SdkError("bad-input", { field: "plaintext" });
+  }
+  if (!(info instanceof Uint8Array)) throw new SdkError("bad-input", { field: "info" });
+  const ctx = suite();
+  let key = null;
+  try {
+    key = await ctx.kem.deserializePublicKey(publicKey);
+    const sender = await ctx.createSenderContext({ recipientPublicKey: key, info });
+    const ciphertext = bytesOf(await sender.seal(body));
+    return { enc: bytesToHex(sender.enc), ciphertext: bytesToHex(ciphertext) };
+  } catch (error) {
+    if (error instanceof SdkError) throw error;
+    throw new SdkError("bad-input", { field: "hpkeKey" });
+  }
+}
+
+// The recipient side exists for checks and for a node that embeds this package. It is not needed by a client
+// that only asks for a quote, but keeping both halves in one module makes a symmetric test possible.
+export async function openViewEnvelope({ privateKey, enc, ciphertext, info } = {}) {
+  const secret = hexToBytes(privateKey, 32, "privateKey");
+  const encapsulated = hexToBytes(enc, 32, "enc");
+  const text = String(ciphertext === undefined || ciphertext === null ? "" : ciphertext).replace(/^0x/, "");
+  const width = text.length / 2;
+  if (width !== 48 && width !== 80) throw new SdkError("bad-input", { field: "ciphertext" });
+  const body = hexToBytes(ciphertext, width, "ciphertext");
+  if (!(info instanceof Uint8Array)) throw new SdkError("bad-input", { field: "info" });
+  const ctx = suite();
+  try {
+    const key = await ctx.kem.deserializePrivateKey(secret, true);
+    const recipient = await ctx.createRecipientContext({ recipientKey: key, enc: encapsulated, info });
+    return bytesOf(await recipient.open(body));
+  } catch (error) {
+    if (error instanceof SdkError) throw error;
+    throw new SdkError("bad-input", { field: "ciphertext" });
+  }
+}

package/src/swaps.mjs

@@ -13,14 +13,15 @@ import * as engine from "./engine.mjs";
 import * as recordModule from "./record.mjs";
 // The order: our own side is built by the engine's builder, the counterparty's side is verified and accepted, and
 // the joint address is assembled from the halves. There are no formulas of our own in the core - see order.mjs.
-import { buildOwnSideFromHalves, contextOf, normalizeCounterpartyView, orderStep } from "./order.mjs";
+import { buildOwnSideFromHalves, contextOf, halfHex, norm, normalizeCounterpartyView, orderStep } from "./order.mjs";
 // Locking the funds: sending goes through the already-finished step (`lock.send`), the wallet is an adapter from outside.
 import * as lock from "./lock.mjs";
+import * as flow from "./swap-flow.mjs";
 import { fundingReceiptVerdict } from "../engine/evm/funding.js";
 import { vmOfChain, legFor } from "./legs/index.mjs";
 // THE VIEW HALVES - from the core's primitives: the sum of two halves is the key the wallet sees incoming payments
 // with. There is no arithmetic of the core's own here either (see order.mjs) - we use the same halves builder.
-import { primitives } from "./primitives.mjs";
+import { keccak256, primitives, secp256k1 } from "./primitives.mjs";
 import { probeMoneroNode } from "./probes.mjs";
 // MARKING READY - A FINISHED STEP, NOT A SECOND IMPLEMENTATION OF IT: it requires the order expectations and checks
 // the slots against the chain BEFORE signing (actions.markReady). The watch must call exactly it, otherwise "we saw
@@ -294,6 +295,10 @@ const recordInputOf = (request) => {
     payToken: quote.asset ? String(quote.asset).toLowerCase() : undefined,
     payAmount: quote.amount !== undefined ? quote.amount : undefined,
     xmrAmount: quote.size !== undefined ? quote.size : undefined,
+    // THE SIGNED INTEGER, NOT THE DISPLAY NUMBER. `quote.size` is a rounded view of the XMR amount; the signed
+    // order's `xmrAmount` is the exact atomic value the maker will pay, and the arrival check compares that one.
+    expectedAtomic: request.order && request.order.xmrAmount !== undefined && request.order.xmrAmount !== null
+      ? request.order.xmrAmount : undefined,
     // THE ORDER-QUOTE ID IS PART OF THE RECORD, NOT A DETAIL OF THE SCREEN (a defect found): our service uses it to
     // tie the created escrow to the provider node's record, and without it the node cannot take the ETH
     // (sdk/src/swap-flow.mjs: quoteId: quote.id -> swap.orderQuoteId; markBodyOf reads exactly this field).
@@ -792,6 +797,13 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
 
     async start(request) {
       if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
+      // SELL IS NOT A BUY WITH ANOTHER LABEL. The lock step sends the settlement deposit from the caller; on a sell
+      // the caller is the claimer and the node is the locker, so this path would ask the wallet to sign the wrong
+      // transaction. Refuse before the recovery key, the wallet or any network read; the sell client has its own
+      // flow and must not be simulated by this one.
+      if (request.side === "sell") {
+        throw new SdkError("bad-input", { field: "side", why: "sell-not-supported", surface: "swaps.start" });
+      }
       if (!request.quote || typeof request.quote !== "object") throw new SdkError("bad-input", { field: "quote" });
       // THE PER-SWAP FILE PATH IS GONE. One key covers every swap, and a per-swap file issued before funding cannot
       // name the escrow (it does not exist yet), so `sweep.plan` could not read the revealed half from it.
@@ -1334,5 +1346,194 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
         await new Promise((resolve) => setTimeout(resolve, pollMs));
       }
     },
+
+    /**
+     * START A SELL FROM A VERIFIED RELAY OFFER. The offer is the result of `quotes.firmRelay` for the bid side;
+     * the record keeps the one-time address, the escrow, our half and the order expectations, so a reload can
+     * continue with `get` + `sellWatch` + `sellClaim`. This method sends nothing.
+     */
+    async startSell(request) {
+      if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
+      const offer = request.offer && typeof request.offer === "object" ? request.offer : null;
+      if (!offer) throw new SdkError("bad-input", { field: "offer" });
+      const order = offer.order && typeof offer.order === "object" ? offer.order : null;
+      const quote = offer.quote && typeof offer.quote === "object" ? offer.quote : null;
+      if (!order || !quote) throw new SdkError("bad-input", { field: "offer", missing: ["order", "quote"] });
+      if (typeof offer.jointAddress !== "string" || !offer.jointAddress) throw new SdkError("bad-input", { field: "offer.jointAddress" });
+      if (typeof offer.escrow !== "string" || !offer.escrow) throw new SdkError("bad-input", { field: "offer.escrow" });
+      // THE RECORD'S ROLE IS THE BID ROLE. The node is the locker and the person is the claimer; a quote whose
+      // addresses or factory disagree with the order is not the offer this record describes.
+      const sameValue = (a, b) => String(a || "").replace(/^0x/, "").toLowerCase() === String(b || "").replace(/^0x/, "").toLowerCase();
+      if (!sameValue(quote.locker, order.locker) || !sameValue(quote.claimer, order.claimer)
+        || !sameValue(quote.provider, order.locker)
+        || !sameValue(quote.factory, order.factory) || Number(quote.chainId) !== Number(order.chainId)) {
+        throw new SdkError("quote-refused", { step: "sell-record", why: "terms" });
+      }
+      // THE RECORD IS FOUND BEFORE A SECOND ONE IS MADE. The same offer retried after a reload yields the same
+      // one-time address and escrow; a second record would be a second promise about one deal.
+      const quoteId = quote.id || quote.nonce || null;
+      const existing = records().find((swap) => swap.side === "sell" &&
+        ((swap.escrow && String(swap.escrow.address || "").toLowerCase() === String(offer.escrow).toLowerCase()) ||
+          (quoteId !== null && String(swap.orderQuoteId || "") === String(quoteId))));
+      if (existing) {
+        // A RETRY IS THE SAME OFFER, NOT A NEW ONE THAT HAPPENS TO NAME THE SAME ESCROW. The stored fields are
+        // the commitment the first call verified; a changed point or commitment is refused before it is resumed.
+        const stored = existing.quote && typeof existing.quote === "object" ? existing.quote : {};
+        const same = (a, b) => String(a || "").replace(/^0x/, "").toLowerCase() === String(b || "").replace(/^0x/, "").toLowerCase();
+        if (!same(stored.commitHalfClaimer, quote.commitHalfClaimer)
+          || !same(stored.edPointClaimer, quote.edPointClaimer)
+          || !same(existing.escrow && existing.escrow.moneroAddress, offer.jointAddress)) {
+          throw new SdkError("quote-refused", { step: "sell-record", why: "offer-changed" });
+        }
+        return { id: existing.id, side: "sell", escrow: (existing.escrow && existing.escrow.address) || offer.escrow,
+          address: (existing.escrow && existing.escrow.moneroAddress) || offer.jointAddress,
+          xmrAmount: (existing.escrow && existing.escrow.xmrAmount) || quote.xmrAmount,
+          claimTip: existing.claimTip || quote.claimTip, orderQuote: existing.orderQuote || offer.orderQuote,
+          resumed: true, next: "send-xmr" };
+      }
+      const storage = engine.store.storage();
+      const supplied = typeof request.recoveryKey === "string"
+        ? request.recoveryKey
+        : request.recoveryKey && typeof request.recoveryKey.mnemonic === "string" ? request.recoveryKey.mnemonic : null;
+      const saved = loadRecoveryKey(storage);
+      if (saved && supplied && saved.mnemonic !== supplied) throw new SdkError("bad-input", { field: "recoveryKey", why: "different-key" });
+      if (!saved && !supplied) throw new SdkError("bad-input", { field: "recoveryKey" });
+      const key = saved || importRecoveryKey(supplied);
+      if (!saved) saveRecoveryKey(storage, { ...key, backupConfirmed: false });
+      const chainId = Number(order.chainId);
+      if (!Number.isSafeInteger(chainId) || chainId <= 0) throw new SdkError("bad-input", { field: "order.chainId" });
+      if (!order.factory || order.salt === undefined || order.salt === null) throw new SdkError("bad-input", { field: "order" });
+      let derived = null;
+      if (offer.recovery && offer.recovery.kind === "index-v1") {
+        const index = Number(offer.recovery.index);
+        if (!Number.isSafeInteger(index) || index < 0) throw new SdkError("bad-input", { field: "offer.recovery" });
+        derived = takerHalves({ mnemonic: key.mnemonic, chainId, index });
+      } else {
+        let salt = null;
+        try { salt = recoverySaltOf(offer.recovery && offer.recovery.salt ? offer.recovery.salt : order.salt); }
+        catch { throw new SdkError("bad-input", { field: "offer.recovery" }); }
+        derived = takerHalvesV2({ mnemonic: key.mnemonic, chainId, factory: order.factory, salt });
+      }
+      const own = buildOwnSideFromHalves(order, { spendHalf: derived.spendHalf, viewHalf: derived.viewHalf });
+      // THE OFFER MUST NAME THE HALF THIS KEY ACTUALLY PRODUCES. The relay already checked the proof; the record
+      // needs the same point and commitment, otherwise a later claim would reveal a half the escrow rejects.
+      const ownCommit = (() => {
+        try {
+          const point = secp256k1.Point.fromHex(own.side.proof.XA);
+          return "0x" + Array.from(keccak256(point.toBytes(false).slice(1)), (b) => b.toString(16).padStart(2, "0")).join("");
+        } catch { return null; }
+      })();
+      const low160 = (v) => String(v || "").replace(/^0x/, "").toLowerCase().slice(-40);
+      if (!ownCommit || low160(ownCommit) !== low160(quote.commitHalfClaimer)) {
+        throw new SdkError("quote-refused", { step: "sell-record", why: "commitment" });
+      }
+      if (String(own.spendPoint).toLowerCase() !== String(quote.edPointClaimer || "").toLowerCase()) {
+        throw new SdkError("quote-refused", { step: "sell-record", why: "spend-point" });
+      }
+      if (offer.edViewPointClaimer && String(own.viewPoint).toLowerCase() !== String(offer.edViewPointClaimer).toLowerCase()) {
+        throw new SdkError("quote-refused", { step: "sell-record", why: "view-point" });
+      }
+      const made = recordModule.createRecord({
+        side: "sell", network: String(order.chainId),
+        payToken: order.asset || quote.asset || undefined,
+        payAmount: quote.amount, xmrAmount: Number(quote.xmrAmount) / 1e12,
+        orderQuoteId: quoteId || undefined,
+        receiveAddress: order.claimer,
+        makerId: quote.provider || null,
+      }, { order, side: own.side });
+      const swap = made.swap;
+      swap.side = "sell";
+      swap.order = order;
+      swap.orderQuote = offer.orderQuote || null;
+      swap.quote = quote;
+      swap.claimTip = quote.claimTip || null;
+      swap.expect = {
+        chainId, factory: order.factory, locker: order.locker, claimer: order.claimer, amount: String(order.amount),
+        readyBy: order.readyBy, t1: order.t1, salt: order.salt,
+        commitHalfLocker: (offer.nodeHalf && offer.nodeHalf.commitHalf) || null,
+        edPointLocker: (offer.nodeHalf && offer.nodeHalf.edPoint) || null,
+        edViewPointLocker: offer.edViewPointLocker || null,
+        commitHalfClaimer: quote.commitHalfClaimer || null,
+        edPointClaimer: quote.edPointClaimer || null,
+      };
+      swap.escrow = { ...(swap.escrow || {}),
+        address: offer.escrow, moneroAddress: offer.jointAddress,
+        half: halfHex(own.side.half), viewHalf: halfHex(own.side.viewHalf),
+        edPointClaimer: own.spendPoint, edViewPointClaimer: norm(own.side.viewPub),
+        commitHalfClaimer: quote.commitHalfClaimer,
+        edPointLocker: (offer.nodeHalf && offer.nodeHalf.edPoint) || null,
+        edViewPointLocker: offer.edViewPointLocker || null,
+        commitHalfLocker: (offer.nodeHalf && offer.nodeHalf.commitHalf) || null,
+        orderContext: offer.context || null, xmrAmount: quote.xmrAmount || null,
+      };
+      try { engine.swap.saveSwap(swap); } catch { throw new SdkError("storage-unavailable", { step: "save-swap" }); }
+      return { id: swap.id, side: "sell", escrow: offer.escrow, address: offer.jointAddress,
+        xmrAmount: quote.xmrAmount, claimTip: quote.claimTip || null, orderQuote: offer.orderQuote || null,
+        resumed: false, next: "send-xmr" };
+    },
+
+    /**
+     * CLAIM THE ETH ON A SELL. The half and the expectations are in the record made by `startSell`; the sender
+     * must be the claimer's own wallet.
+     */
+    async sellClaim(request, wallet) {
+      if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
+      const id = String(request.id || "").trim();
+      if (!id) throw new SdkError("bad-input", { field: "id" });
+      let swap = null;
+      try { swap = engine.swap.getSwap(id); } catch { swap = null; }
+      if (!swap || swap.side !== "sell") throw new SdkError("bad-input", { field: "id", why: "sell-not-found" });
+      const escrow = request.escrow || (swap.escrow && swap.escrow.address) || null;
+      const halfClaimer = request.halfClaimer || (swap.escrow && swap.escrow.half) || null;
+      if (!escrow || !halfClaimer) throw new SdkError("bad-input", { field: "escrow", missing: ["escrow", "halfClaimer"] });
+      const expect = request.expect || swap.expect || null;
+      if (!expect) throw new SdkError("bad-input", { field: "expect", why: "not-in-record" });
+      return actions.claim({ escrow, halfClaimer, claimer: swap.order && swap.order.claimer,
+        expect, onStep: request.onStep }, wallet);
+    },
+
+    /**
+     * WAIT FOR THE NODE'S SIDE ON A SELL. The client sends XMR to the one-time joint address; the node (the
+     * locker) must mark the order ready before the claimer can take the ETH. This reads the escrow itself - no
+     * backend watcher - and returns as soon as the chain says ready, claimed or refunded.
+     */
+    async sellWatch(request) {
+      if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
+      const escrow = String(request.escrow || "").trim();
+      if (!escrow) throw new SdkError("bad-input", { field: "escrow" });
+      const timeoutMs = Number.isFinite(Number(request.timeoutMs)) && Number(request.timeoutMs) > 0
+        ? Number(request.timeoutMs) : limitOf("watchTimeoutMs", 1_200_000);
+      const pollMs = Number.isFinite(Number(request.pollMs)) && Number(request.pollMs) > 0
+        ? Number(request.pollMs) : limitOf("watchPollMs", 6_000);
+      const started = Date.now();
+      let lastStatus = null;
+      let lastError = null;
+      for (;;) {
+        try { lastStatus = await flow.orderStatus(escrow, { call: reader }); }
+        catch (error) { lastError = (error && error.code) || "status-unread"; lastStatus = null; }
+        if (lastStatus && (lastStatus.isClaimed || lastStatus.isRefunded)) {
+          return { escrow, state: lastStatus.isClaimed ? "claimed" : "refunded",
+            funded: lastStatus.isFunded, claimed: lastStatus.isClaimed, refunded: lastStatus.isRefunded,
+            ready: null, balanceWei: String(lastStatus.balance), waitedMs: Date.now() - started };
+        }
+        if (lastStatus && lastStatus.isFunded) {
+          let ready = null;
+          try {
+            const raw = await reader({ to: escrow, data: engine.evm.encodeRead("ready") });
+            const hex = String(raw || "").replace(/^0x/, "");
+            ready = hex.length > 0 && BigInt("0x" + hex) !== 0n;
+          } catch (error) { lastError = (error && error.code) || "ready-unread"; }
+          if (ready === true) {
+            return { escrow, state: "ready", funded: true, claimed: false, refunded: false,
+              ready: true, balanceWei: String(lastStatus.balance), waitedMs: Date.now() - started };
+          }
+        }
+        if (Date.now() - started >= timeoutMs) {
+          throw new SdkError("sell-timeout", { escrow, waitedMs: Date.now() - started, timeoutMs,
+            status: lastStatus, error: lastError });
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+      }
+    },
   };
 }

package/src/sweep.mjs

@@ -85,7 +85,16 @@ const payloadFromOrder = async (request) => {
     ownSpendHalf: halves.spendHalf, ownViewHalf: halves.viewHalf,
     otherSpendPoint, otherViewPoint, network: moneroNetwork,
   });
-  const escrow = { address: order.escrow, readyBy: order.readyBy, t1: order.t1 };
+  // THE SIGNED XMR AMOUNT TRAVELS WITH THE ESCROW. A recovery file rebuilt from the chain must compare the
+  // arrival against the exact integer the order carries, not against the rounded display number.
+  const signedAtomic = (() => {
+    try {
+      const atomic = BigInt(String(order.xmrAmount));
+      return atomic > 0n ? atomic.toString() : null;
+    } catch { return null; }
+  })();
+  const escrow = { address: order.escrow, readyBy: order.readyBy, t1: order.t1,
+    ...(signedAtomic ? { expectedAtomic: signedAtomic } : {}) };
   const payload = engine.recoveryFile.buildPayload({
     swap: {
       id: order.escrow, side, network, moneroNetwork,

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