@ninsei-labs/sdk 0.49.0 → 0.50.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 0.50.0 — 2026-10-21
+
+A CLAIM IS SENT BY ITS CLAIMER, AND A SALE IS RANKED AFTER THE TIP.
+
+- `actions.claim` compares the wallet's address with `request.claimer` or `expect.claimer` before it signs. A
+  third-party wallet, a missing claimer or a wallet without an address is a named `bad-input`; `claimSenderVerdict`
+  exposes the same rule. This is a deliberate tightening: a claim reveals the half to its sender.
+- `readQuote` keeps the signed `claimTip`, and `rankOffers` selects a sale by `amount × rate − claimTip`, not by
+  the headline rate. A buy, or a request without an amount, still ranks by rate.
+- `quotes.watch` uses that ranking for the chosen offer, so moving margin from the price into the tip no longer
+  wins a sale.
+
 ## 0.49.0 — 2026-10-21
 
 A ONE-KEY RECOVERY CAN WITHDRAW WITHOUT A FULL SCAN, AND A CLAIM TIP IS CHECKED.

package/index.d.ts

@@ -507,6 +507,8 @@ export interface QuoteOffer {
   readonly currency: string | null;
   readonly rate: number;
   readonly rateQuote: number;
+  /** The claim tip in native-token wei; a sale is ranked by the payout AFTER it. */
+  readonly claimTip: string;
   readonly min: number | null;
   readonly max: number | null;
   readonly step: number | null;
@@ -1597,6 +1599,9 @@ export interface ActionsApi {
 export interface ActionsRequest {
   readonly escrow: string;
   readonly expect: Readonly<Record<string, unknown>>;
+  /** The claimer whose half is revealed by `claim`; absent - `expect.claimer` is used. A claim without one is
+   * refused: the package sends it only from the claimer's own wallet, never from a third-party sender. */
+  readonly claimer?: string;
   readonly onStep?: (stage: string, detail?: string) => void;
 }
 

package/package.json

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

package/src/actions.mjs

@@ -25,6 +25,18 @@ const walletOrFail = (wallet) => {
   return wallet;
 };
 
+// THE CLAIM'S HALF IS REVEALED BY WHOEVER SENDS IT. The package sends a claim only from the claimer's own wallet:
+// a third-party sender would see the half before the claim is mined, and the only reason to use one is the tip -
+// not a reason to hand the half to another party. A caller with no claimer is refused, not sent blind.
+export function claimSenderVerdict({ sender = null, claimer = null } = {}) {
+  const from = typeof sender === "string" ? sender.trim().toLowerCase() : "";
+  const to = typeof claimer === "string" ? claimer.trim().toLowerCase() : "";
+  if (!to) return { ok: false, code: "bad-input", field: "claimer" };
+  if (!from) return { ok: false, code: "bad-input", field: "wallet.address" };
+  if (from !== to) return { ok: false, code: "bad-input", field: "wallet", why: "not-the-claimer" };
+  return { ok: true };
+}
+
 const requestOrFail = (request, extra) => {
   if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
   const missing = missingFields(request, ["escrow", "expect", ...extra]);
@@ -59,6 +71,9 @@ export function createActions({ call = null } = {}) {
       requestOrFail(request, ["halfClaimer"]);
       walletOrFail(wallet);
       const { escrow, halfClaimer, expect, onStep } = request;
+      const sender = typeof wallet.address === "function" ? await wallet.address() : null;
+      const verdict = claimSenderVerdict({ sender, claimer: request.claimer || (expect && expect.claimer) });
+      if (!verdict.ok) throw new SdkError(verdict.code, { field: verdict.field, why: verdict.why, surface: "actions.claim" });
       return await withCodes("claim", () => flow.claimOrder({ escrow, halfClaimer, expect, onStep, deps: deps(wallet) }));
     },
     /** Refunding: it also reveals a half. The core passes the expectations ALWAYS, though the engine does not require them. */

package/src/quotes.mjs

@@ -83,6 +83,13 @@ export function readQuote(pair, raw, owner = {}, data = {}) {
     currencyNetwork: q.currencyNetwork ? String(q.currencyNetwork) : null,
     rateQuote,
     rate,
+    // THE CLAIM TIP IS IN THE MAKER'S NATIVE TOKEN (wei). A sale is ranked by what the seller receives AFTER it;
+    // the value is kept as a string, because a wei amount does not fit a float reliably.
+    claimTip: (() => {
+      if (q.claimTip === undefined || q.claimTip === null || q.claimTip === "") return "0";
+      try { const n = BigInt(q.claimTip); return n < 0n ? "0" : n.toString(); }
+      catch { return "0"; }
+    })(),
     min: num(q.min),
     max: num(q.max),
     step: num(q.step),
@@ -104,6 +111,27 @@ export function readQuote(pair, raw, owner = {}, data = {}) {
   };
 }
 
+/**
+ * THE BEST OFFER IS THE ONE THAT PAYS THE MOST, NOT THE ONE WITH THE HIGHEST RATE. On a sale the maker may move
+ * its margin into `claimTip`: the escrow pays that tip out of the seller's payout, so a higher rate with a larger
+ * tip can leave the seller with less. With no amount there is nothing to compare beyond the rate, and a buy has
+ * no tip. Native-token wei are converted at 18 decimals: a sale settles in the chain's native coin.
+ */
+export function rankOffers(offers = [], { direction = "buy", amount = null } = {}) {
+  const list = Array.isArray(offers) ? offers.filter((offer) => offer && Number(offer.rate) > 0) : [];
+  const amountXmr = Number(amount);
+  const score = (offer) => {
+    const rate = Number(offer.rate);
+    if (direction !== "sell" || !(amountXmr > 0)) return rate;
+    let tip = 0;
+    try { tip = Number(BigInt(offer.claimTip || "0")) / 1e18; } catch { tip = 0; }
+    return amountXmr * rate - tip;
+  };
+  const ranked = list.map((offer) => ({ offer, net: score(offer) }))
+    .sort((a, b) => (b.net - a.net) || (Number(b.offer.rate) - Number(a.offer.rate)));
+  return { best: ranked.length ? ranked[0].offer : null, net: ranked.length ? ranked[0].net : null, ranked };
+}
+
 /**
  * Parsing the book in one place. The envelope is accepted in three forms (a map by pairs, a list of rows, a list
  * of providers) and is brought to a single list: the screen must not know which form the answer came in.
@@ -201,7 +229,7 @@ const compactOffer = (o) => ({
   assetNetwork: o.assetNetwork, currencyNetwork: o.currencyNetwork, networkStated: o.networkStated,
   networksDerived: o.networksDerived === true, networksUnnamed: o.networksUnnamed === true,
   // THE REASON (in the provider's words), THE PACKAGE'S SIGNATURE AND KEY, THE AGE BY ITS OWN MARK.
-  why: o.why, signature: o.signature, keyId: o.keyId, ageMs: o.ageMs,
+  claimTip: o.claimTip, why: o.why, signature: o.signature, keyId: o.keyId, ageMs: o.ageMs,
   networks: { asset: o.assetNetwork, currency: o.currencyNetwork, stated: o.networkStated },
 });
 
@@ -267,8 +295,11 @@ export function createQuotes({ config, http, now = () => Date.now(), evmCall = n
       const asked = explicit ? Number(request.size) : size;
       const data = await http.json("/rate?amount=" + encodeURIComponent(asked) + "&side=" + encodeURIComponent(request.direction));
       const book = readBook(data, now());
-      const offer = book.best;
       const amount = Number.isFinite(Number(request.amount)) ? Number(request.amount) : null;
+      // A SALE IS RANKED BY THE PAYOUT AFTER THE TIP; a buy has no tip. Without an amount the rate is the only
+      // comparable number, and the service's own best remains the fallback.
+      const ranked = rankOffers(book.offers, { direction: request.direction, amount });
+      const offer = ranked.best || book.best;
       // The size derived from the person's amount becomes the size of the NEXT request: the price does not depend
       // on volume, and the volume is needed by the provider to say whether it takes such a size. With a named size
       // there is nothing to derive - it stays what it was asked as.

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