@ninsei-labs/sdk 0.58.0 → 0.59.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,7 +3,7 @@
3
3
  // Everything below this header is identical to the source.
4
4
 
5
5
  // VM-neutral deployment pins generated from deployments/<vm>/<network>.json. No address table is copied below.
6
- import { DEPLOYMENTS, DEPLOYMENT_CHAINS, DEPLOYMENT_VMS, deploymentFor } from "./deployments.generated.js";
6
+ import { DEPLOYMENTS, DEPLOYMENT_CHAINS, DEPLOYMENT_VMS, FACTORY_HISTORY, deploymentFor } from "./deployments.generated.js";
7
7
 
8
8
  // Demo configuration. Every number a user sees lives here. Values come from the litepaper and are marked as demo data in the UI.
9
9
  //
@@ -790,7 +790,7 @@ export const KNOWN_FACTORY_CODES = Object.freeze(Object.fromEntries(
790
790
  .map((deployment) => [deployment.network, [...deployment.knownFactoryCodes]]),
791
791
  ));
792
792
 
793
- export { DEPLOYMENTS, DEPLOYMENT_CHAINS, DEPLOYMENT_VMS, deploymentFor };
793
+ export { DEPLOYMENTS, DEPLOYMENT_CHAINS, DEPLOYMENT_VMS, FACTORY_HISTORY, deploymentFor };
794
794
 
795
795
  export function knownFactoryCodesFor(chainOrId) {
796
796
  const id = typeof chainOrId === "string" ? chainOrId : chainOrId && chainOrId.id;
@@ -1,5 +1,6 @@
1
1
  // GENERATED FILE - do not edit. Run: node tools/gen-deployment-pins.mjs --write
2
2
  // Source: deployments/<vm>/<network>.json, copied from the reviewed contract release manifest.
3
+ // Factory history: deployments/history/<vm>/<network>.json, reviewed old factories for recovery.
3
4
  const freeze = (value) => {
4
5
  if (value && typeof value === "object") {
5
6
  Object.freeze(value);
@@ -84,10 +85,42 @@ const DATA = {
84
85
  ]
85
86
  }
86
87
  };
88
+ const HISTORY_DATA = {
89
+ "arbitrum-sepolia": [
90
+ {
91
+ "address": "0x3ee25f12758ec28e5b3045d16132d89cd0bf341f",
92
+ "deploymentBlock": 318911595,
93
+ "release": {
94
+ "tag": "contracts-testnet-2026.10.21"
95
+ },
96
+ "status": "retired"
97
+ },
98
+ {
99
+ "address": "0x69b5a6878b542960af4d239ecc60ad1c9e3e6932",
100
+ "deploymentBlock": 323014007,
101
+ "release": {
102
+ "tag": "contracts-testnet-2026.10.26"
103
+ },
104
+ "status": "retired"
105
+ },
106
+ {
107
+ "address": "0x245d3a4ac4b98d713f6c5130b56cd5d550f8cefe",
108
+ "deploymentBlock": 326005419,
109
+ "release": {
110
+ "tag": "contracts-testnet-2026.11.04",
111
+ "commit": "930366a387c0c696bda6f5c038f23617447ebb78",
112
+ "toolchain": "0.8.38",
113
+ "deployedAt": "2026-11-04T15:00:55.822Z"
114
+ },
115
+ "status": "live"
116
+ }
117
+ ]
118
+ };
87
119
 
88
120
  export const DEPLOYMENTS = freeze(DATA);
89
121
  export const DEPLOYMENT_CHAINS = freeze(Object.keys(DATA).sort());
90
122
  export const DEPLOYMENT_VMS = freeze([...new Set(Object.values(DATA).map((d) => d.vm))].sort());
123
+ export const FACTORY_HISTORY = freeze(HISTORY_DATA);
91
124
 
92
125
  // Accept a network id, a CAIP-2, or an EVM chain id. No fallback to another network: an unknown deployment is null.
93
126
  export function deploymentFor(chainOrId) {
@@ -1,7 +1,7 @@
1
- // GENERATED FILE - a byte-for-byte copy of the engine module www/js/monero/scan.js for the SDK package.
2
- // Edit the source under www/js and regenerate the mirror; a drift guard reddens on any difference.
3
- // Everything below this header is identical to the source.
4
-
1
+ // THE MONERO INDEXER FOR THE SDK. The browser bundle carries a generated copy; this module is the source the package
2
+ // checks and tests use. Edit it here and regenerate the browser copy with `pnpm run build:sdk:docker` when a bundle
3
+ // change is needed.
4
+ //
5
5
  // MONERO INDEXER: we find arrivals at the swap address ourselves by parsing blocks.
6
6
  // WHY. Before, arrivals were learned from monero-wallet-rpc through a watch-only wallet, a path that hit a defect
7
7
  // (the wallet+keys pair is created and never reopens) and where one instance held one wallet, so scanning 25
@@ -25,6 +25,7 @@
25
25
  import { ed25519 } from "@noble/curves/ed25519.js";
26
26
  import { keccak_256 } from "@noble/hashes/sha3.js";
27
27
  import { UNLOCK_TIME_BLOCK_MAX, unlockStateOf, laterBoundary } from "./unlock.js";
28
+ import { decodeAddressKeys } from "./arrivalRead.js";
28
29
  export { UNLOCK_TIME_BLOCK_MAX, unlockStateOf, laterBoundary };
29
30
 
30
31
  export function keccak(bytes) { return keccak_256(bytes); }
@@ -125,6 +126,31 @@ export function viewKeyFormForAddress(viewSecret, expectedViewPubHex) {
125
126
  return false;
126
127
  }
127
128
 
129
+ // THE KEY MATERIAL MUST BELONG TO THE ADDRESS IT IS SCANNED FOR. A public `scanRange` used to try both byte-order
130
+ // readings of the view key and could count a payment to another address as ours. This is the ONE binding rule: the
131
+ // scanner and both facade paths call it, so a host cannot get a different answer by choosing another entry point.
132
+ // A subaddress or integrated address is refused here; the joint address this SDK builds is primary.
133
+ export function watchedAddressVerdict({ address, viewSecret, spendPub } = {}) {
134
+ let keys;
135
+ try {
136
+ keys = decodeAddressKeys(address);
137
+ } catch {
138
+ return { ok: false, code: "bad-input", why: "not-a-monero-address", field: "address" };
139
+ }
140
+ if (!keys.network) return { ok: false, code: "bad-input", why: "not-a-primary-address", field: "address" };
141
+ const wantedSpend = String(spendPub === undefined || spendPub === null ? "" : spendPub).replace(/^0x/, "").toLowerCase();
142
+ if (!wantedSpend || wantedSpend !== keys.spendPub.toLowerCase()) {
143
+ return { ok: false, code: "xmr-address-mismatch", field: "spendPub" };
144
+ }
145
+ const form = viewKeyFormForAddress(viewSecret, keys.viewPub);
146
+ if (!form) return { ok: false, code: "xmr-address-mismatch", field: "viewSecret" };
147
+ const secret = viewSecretCandidates(viewSecret).find(([name]) => name === form)?.[1];
148
+ if (secret === undefined || secret === null) {
149
+ return { ok: false, code: "xmr-address-mismatch", field: "viewSecret" };
150
+ }
151
+ return { ok: true, address, keys, form, viewSecret: secret, spendPub: keys.spendPub };
152
+ }
153
+
128
154
  export function keyDerivation(txPublicKeyHex, viewSecretHex) {
129
155
  const txPub = pointFromHex(txPublicKeyHex);
130
156
  // The view key is accepted both as LE bytes from monero-rpc and as a number if already parsed.
@@ -415,7 +441,11 @@ export async function fetchTransactions(daemonUrl, hashes, fetchImpl = globalThi
415
441
 
416
442
  // Parsing one transaction against the watched addresses. watched: [{ address, viewSecret, spendPub }] - viewSecret
417
443
  // is taken as a number, LE-hex or BE-hex. The result carries viewKeyForm: the form name that matched.
418
- export function matchTransaction(tx, watched, { height = null, tipHeight = null, nowSec = null } = {}) {
444
+ //
445
+ // THE KEY BINDING IS A PROPERTY OF THE WATCHED ENTRY, NOT OF THE TRANSACTION. `scanRange` binds every entry once
446
+ // before its block loop and passes the result here; the public `matchTransaction` binds the entries it is given.
447
+ // Re-binding inside the loop made every transaction repeat base58 decoding, keccak and an ed25519 multiplication.
448
+ function matchBoundTransaction(tx, boundWatched, { height = null, tipHeight = null, nowSec = null } = {}) {
419
449
  const out = [];
420
450
  // BOTH KEY LISTS ARE PART OF THE TRANSACTION. A subaddress output carries its own key under tag 0x04; using only
421
451
  // `txPublicKeyFromExtra` drops exactly those outputs.
@@ -436,10 +466,10 @@ export function matchTransaction(tx, watched, { height = null, tipHeight = null,
436
466
  const ecdhMasks = ecdh.map((e) => e.mask);
437
467
  const outPk = ((tx.rct_signatures || {}).outPk || []);
438
468
  const rctVersion = (tx.rct_signatures || {}).type || 2;
439
- for (const w of watched) {
469
+ for (const { entry: w, bound } of boundWatched) {
440
470
  const r = findOurOutputs({
441
471
  txPublicKeys: keys.txPublicKeys, additionalPublicKeys: keys.additionalPublicKeys,
442
- viewSecretHex: w.viewSecret, spendPubHex: w.spendPub,
472
+ viewSecretHex: bound.viewSecret, spendPubHex: bound.spendPub,
443
473
  outputs, ecdhAmounts, ecdhMasks, outPk, rctVersion: Number(rctVersion) || 1,
444
474
  });
445
475
  if (r.outputs.length) out.push({ address: w.address, index: w.index ?? null, outputs: r.outputs, derivation: r.derivation, viewKeyForm: r.viewKeyForm, unlockTime: Number(tx.unlock_time) || 0, unlock });
@@ -447,6 +477,21 @@ export function matchTransaction(tx, watched, { height = null, tipHeight = null,
447
477
  return out;
448
478
  }
449
479
 
480
+ // THE PUBLIC FORM BINDS EACH WATCHED ENTRY BEFORE IT LOOKS AT THE TRANSACTION. An entry that is not a primary
481
+ // address with this spend key is skipped; the binding cannot be supplied by the caller.
482
+ function bindWatched(watched) {
483
+ const bound = [];
484
+ for (const entry of watched) {
485
+ const verdict = watchedAddressVerdict(entry);
486
+ if (verdict.ok) bound.push({ entry, bound: verdict });
487
+ }
488
+ return bound;
489
+ }
490
+
491
+ export function matchTransaction(tx, watched, options = {}) {
492
+ return matchBoundTransaction(tx, bindWatched(watched), options);
493
+ }
494
+
450
495
  // Range scan. Returns per address the sum (receivedAtomic - only the UNLOCKED), hashes, the locked sum
451
496
  // (lockedAtomic) with its boundary (lockedUntil) and the best (highest) height of a found output.
452
497
  export async function scanRange({ daemonUrl, fromHeight, toHeight, watched, log = () => {}, concurrency = 4, nowSec = null, tipHeight = null, fetchImpl = globalThis.fetch }) {
@@ -454,6 +499,9 @@ export async function scanRange({ daemonUrl, fromHeight, toHeight, watched, log
454
499
  if (!(from >= 0) || !(to >= from)) throw new Error("bad height range: " + fromHeight + ".." + toHeight);
455
500
  const acc = new Map();
456
501
  for (const w of watched) acc.set(w.address, { address: w.address, receivedAtomic: 0n, lockedAtomic: 0n, lockedUntil: null, lockedTxids: [], txids: [], bestHeight: null, outputs: 0, viewKeyForm: null });
502
+ // BIND ONCE PER WATCHED ADDRESS. The binding does not depend on the transaction, and an invalid entry is skipped
503
+ // here exactly as the public matcher skips it.
504
+ const boundWatched = bindWatched(watched);
457
505
  const heights = [];
458
506
  for (let h = from; h <= to; h++) heights.push(h);
459
507
  const missingHeights = [];
@@ -469,7 +517,7 @@ export async function scanRange({ daemonUrl, fromHeight, toHeight, watched, log
469
517
  if (!hashes.length) continue;
470
518
  const txs = await fetchTransactions(daemonUrl, hashes, fetchImpl);
471
519
  for (const tx of txs) {
472
- for (const hit of matchTransaction(tx, watched, { height: h, tipHeight: tipHeight === null || tipHeight === undefined ? to : tipHeight, nowSec })) {
520
+ for (const hit of matchBoundTransaction(tx, boundWatched, { height: h, tipHeight: tipHeight === null || tipHeight === undefined ? to : tipHeight, nowSec })) {
473
521
  const a = acc.get(hit.address);
474
522
  if (!a) continue;
475
523
  if (hit.viewKeyForm) a.viewKeyForm = hit.viewKeyForm; // what matched - this goes to the log
package/index.d.ts CHANGED
@@ -53,7 +53,8 @@ export interface NinseiOptions {
53
53
  storage?: StorageAdapter;
54
54
  /** "live" - real nodes and chain; "sim" - a sandbox (mocks, accelerated time, failure scenarios). */
55
55
  mode?: "live" | "sim";
56
- /** An injected fetch function (SSR, tests, your own transport). */
56
+ /** An injected fetch function (SSR, tests, your own transport). It is the client default for relay quotes/claims,
57
+ * Monero height probes and witness checks; a per-call `fetchImpl` still wins. */
57
58
  fetch?: FetchLike;
58
59
  /** The clock. In "sim" the SDK uses it to accelerate time. */
59
60
  now?: () => number;
@@ -540,6 +541,10 @@ export interface FirmRelayAnswer {
540
541
  readonly jointAddress: string;
541
542
  /** The escrow address predicted from the signed quote and the depositor's half. */
542
543
  readonly escrow: string;
544
+ /** Seconds left when the answer was verified; the host may show this next to the confirm button. */
545
+ readonly remainingSec: number;
546
+ /** The last Unix second at which `swaps.start` can still begin this quote. */
547
+ readonly confirmBySec: number;
543
548
  readonly recovery: { readonly kind: "salt-v2"; readonly salt: string };
544
549
  /** Everything `swaps.start` can take from the relay; the caller adds its wallet, `receiveTo` and height. */
545
550
  readonly startRequest: Readonly<{
@@ -549,6 +554,7 @@ export interface FirmRelayAnswer {
549
554
  counterparty: Readonly<Record<string, unknown>>;
550
555
  recoveryKey: unknown;
551
556
  recoverySalt: string;
557
+ escrow: string;
552
558
  }>;
553
559
  /** The relay origin that answered. `startSell` stores it for the later no-wallet claim. */
554
560
  readonly relayUrl: string;
@@ -657,14 +663,13 @@ export interface SwapsApi {
657
663
  sellClaim(request: SellClaimRequest, wallet: WalletAdapter): Promise<unknown>;
658
664
  /**
659
665
  * CLAIM THE ETH ON A SELL WITHOUT A WALLET. The seller holds XMR and no ETH, so the signed `claimTip` pays the
660
- * sender. The half goes to the sender the client chose - a listed maker OTHER than the deal's maker - through
661
- * the relay that answered the quote (`POST /v1/claims/{sender}/{escrow}`). No wallet is created or used and no
662
- * chain transaction is signed.
666
+ * sender. `claimSenders` is the client's ordered list - the relay's own sender first, then the listed makers -
667
+ * sent one at a time through the relay (`POST /v1/claims/{sender}/{escrow}`). Each sender gets a 15-30 s slot; a
668
+ * refusal moves on, a txid or unknown answer is followed by reading the escrow, and only `claimed` on chain is
669
+ * success. When the list is exhausted the result is `claim-yourself` with the time left before `t1`.
663
670
  *
664
- * The sender is stored by `startSell`; a request may supply `claimSender` only when the record has none, and
665
- * may never name the deal's maker. `relayUrl` may restate the stored origin; a different origin is refused. A
666
- * node refusal is `quote-refused` with its own code in `params.code`; a lost answer is `claim-unknown` (the
667
- * claim may have been sent), never success.
671
+ * The deal's maker and its quote-key owner are refused before the half leaves the client. No wallet is created or
672
+ * used and no chain transaction is signed. `relayUrl` may restate the stored origin; a different origin is refused.
668
673
  */
669
674
  claimViaRelay(request: RelayClaimRequest): Promise<RelayClaimResult>;
670
675
  /**
@@ -834,6 +839,14 @@ export interface XmrWitnessShadowReading {
834
839
  readonly operator?: string;
835
840
  readonly url?: string;
836
841
  readonly completed: boolean;
842
+ /** Distinct operators whose walk covered the target; two instances of one operator count once. */
843
+ readonly quorum: {
844
+ readonly required: number;
845
+ readonly completed: readonly string[];
846
+ /** On mainnet the Ninsei walker is not one of the two votes; this list excludes it. */
847
+ readonly independent: readonly string[];
848
+ readonly ok: boolean;
849
+ };
837
850
  readonly checked: readonly Record<string, unknown>[];
838
851
  readonly failed: readonly Record<string, unknown>[];
839
852
  }
@@ -955,9 +968,9 @@ export interface SellStartRequest {
955
968
  /** The verified `quotes.firmRelay` answer for the bid side. */
956
969
  readonly offer: FirmRelayAnswer;
957
970
  /**
958
- * The sender the client chose for a later no-ETH claim: a listed maker other than the deal's maker. It is
959
- * stored with the record so a reload claims through the same node; the relay route names it as `provider`.
960
- * Omitted for a record that will only use the own-wallet path.
971
+ * Optional legacy single sender stored for a no-ETH claim. The ordered list passed to `claimViaRelay` is the
972
+ * authority; this scalar is only a one-element fallback for callers written before the list existed. A sender
973
+ * naming the deal's maker or its quote-key owner is refused.
961
974
  */
962
975
  readonly claimSender?: string;
963
976
  /** The twelve-word key; required only when no key is stored yet. */
@@ -982,7 +995,7 @@ export interface SellStart {
982
995
  readonly xmrAmount: string;
983
996
  readonly claimTip: string | null;
984
997
  readonly orderQuote: Readonly<Record<string, unknown>> | null;
985
- /** The no-wallet claim sender stored by `startSell`, or null when only the own-wallet path is available. */
998
+ /** The legacy single sender stored by `startSell`, or null when the client supplies the list at claim time. */
986
999
  readonly claimSender: string | null;
987
1000
  readonly readyWindow: ReadyWindow | null;
988
1001
  readonly resumed: boolean;
@@ -999,34 +1012,70 @@ export interface SellClaimRequest {
999
1012
 
1000
1013
  /**
1001
1014
  * THE NO-WALLET CLAIM'S INPUTS. `id` names the sell record made by `startSell`; the escrow, half and signed tip
1002
- * come from it. `claimSender` is the list-member node that will send the claim: it must be a listed maker other than
1003
- * the deal's maker, and is normally stored by `startSell`. `relayUrl` is optional and may only repeat the origin
1015
+ * come from it. `claimSenders` is the client's ordered list: the relay's own sender first, then the listed makers.
1016
+ * Each entry is checked for the deal's maker and its quote-key owner. The old scalar `claimSender` is accepted as a
1017
+ * one-element fallback for callers written before the list. `relayUrl` is optional and may only repeat the origin
1004
1018
  * stored with the record - a foreign origin is refused.
1005
1019
  */
1006
1020
  export interface RelayClaimRequest {
1007
1021
  readonly id: string;
1008
- /** Only for a record made before the sender was stored; it may never name the deal's maker. */
1022
+ /** Ordered senders. Tried one at a time; the first that lands a claim on chain wins. */
1023
+ readonly claimSenders?: readonly string[];
1024
+ /** One-element fallback for a caller written before `claimSenders`; may never name the deal's maker. */
1009
1025
  readonly claimSender?: string;
1010
1026
  readonly relayUrl?: string;
1027
+ /** One sender's slot; clamped to 15-30 s. Default 20 s. */
1028
+ readonly slotMs?: number;
1029
+ /** How often the escrow is read during a slot. Default 2 s. */
1030
+ readonly pollMs?: number;
1011
1031
  readonly fetchImpl?: typeof fetch;
1012
1032
  readonly timeoutMs?: number;
1013
1033
  }
1014
1034
 
1015
- /** The claim the relay sent for the record. Only a validated on-chain transaction hash is returned here. */
1016
- export interface RelayClaimResult {
1035
+ /** One sender's outcome in a list claim. */
1036
+ export interface RelayClaimAttempt {
1037
+ readonly sender: string;
1038
+ readonly outcome: "refused" | "unknown" | "unconfirmed";
1039
+ readonly code?: string | null;
1040
+ readonly params?: Readonly<Record<string, unknown>> | null;
1041
+ readonly txid?: string | null;
1042
+ }
1043
+
1044
+ /** The claim has landed: the escrow itself reads `claimed`, not merely a txid answer. */
1045
+ export interface RelayClaimed {
1046
+ readonly state: "claimed";
1017
1047
  readonly id: string;
1018
- /** The sender the client chose; `claimSender` repeats it for callers that think in that name. */
1019
- readonly provider: string;
1020
- readonly claimSender: string;
1048
+ /** The sender whose slot found the claim; null when the escrow already read claimed before the first POST. */
1049
+ readonly provider: string | null;
1050
+ readonly claimSender: string | null;
1021
1051
  readonly escrow: string;
1022
1052
  readonly relayUrl: string;
1023
- readonly txid: string;
1024
- /** The address that sent the claim transaction (the sender node's sender, not the seller). */
1025
- readonly from: string;
1026
- /** The signed tip, in wei, paid out of the claim. */
1053
+ /** The txid when an answer carried one; `null` when the claim was found on chain without it. */
1054
+ readonly txid: string | null;
1055
+ readonly from: string | null;
1027
1056
  readonly tipWei: string;
1057
+ readonly tried: readonly RelayClaimAttempt[];
1028
1058
  }
1029
1059
 
1060
+ /** No sender landed the claim. The seller must send `sellClaim` before `t1`. */
1061
+ export interface RelayClaimYourself {
1062
+ readonly state: "claim-yourself";
1063
+ readonly reason: "senders-exhausted" | "escrow-refunded";
1064
+ readonly id: string;
1065
+ readonly provider: null;
1066
+ readonly claimSender: null;
1067
+ readonly escrow: string;
1068
+ readonly relayUrl: string;
1069
+ readonly txid: null;
1070
+ readonly from: null;
1071
+ readonly tipWei: string;
1072
+ readonly t1: number | null;
1073
+ readonly secondsLeft: number | null;
1074
+ readonly tried: readonly RelayClaimAttempt[];
1075
+ }
1076
+
1077
+ export type RelayClaimResult = RelayClaimed | RelayClaimYourself;
1078
+
1030
1079
  export interface SellWatchRequest {
1031
1080
  /** The escrow predicted by the relay adapter. */
1032
1081
  readonly escrow: string;
@@ -1151,6 +1200,14 @@ export interface StartRequest {
1151
1200
  * without it (`bad-input { step: "fund-order" }`): the factory takes a signed quote, not bare order terms.
1152
1201
  */
1153
1202
  readonly orderQuote?: QuoteLike;
1203
+ /**
1204
+ * OPTIONAL CROSS-CHECK, NOT A REQUIREMENT. A reloaded retry derives this address from the signed quote; when the
1205
+ * caller already has it, the value is compared with that prediction and a different value is refused. A request
1206
+ * without it resumes the same pending record from the quote alone.
1207
+ */
1208
+ readonly escrow?: string;
1209
+ /** Alias for `escrow` accepted by the same cross-check. */
1210
+ readonly predictedEscrow?: string;
1154
1211
  /** The swap direction for the record. Default - `buy`. */
1155
1212
  readonly side?: "buy" | "sell";
1156
1213
  /** Where to receive: for a purchase - the Monero address, for a sale - the EVM address. */
@@ -1176,7 +1233,7 @@ export interface StartRequest {
1176
1233
  restoreHeight?: number;
1177
1234
  /** Monero nodes for that one measurement; absent - the configured nodes for the swap's network. */
1178
1235
  xmrNodes?: readonly (string | { readonly url: string })[];
1179
- /** The fetch used for the height measurement (tests); absent - the global fetch. */
1236
+ /** The fetch used for the height measurement (tests); absent - the client's `fetch`, otherwise the global fetch. */
1180
1237
  fetchImpl?: typeof fetch;
1181
1238
  /**
1182
1239
  * Hand the key backup to the interface, ONCE, when this call created the key. `true` - the person saved it;
@@ -1904,6 +1961,8 @@ export declare class SdkError extends Error {
1904
1961
  export declare const SDK_VERSION: string;
1905
1962
  /** The minimum remaining lifetime of a quote when a swap starts, in seconds. */
1906
1963
  export declare const LOCK_START_MARGIN_SEC: number;
1964
+ /** The SDK's own preparation allowance for a buy quote, in addition to the start margin. */
1965
+ export declare const START_PREP_SEC: number;
1907
1966
  /** The default firm quote lifetime, in seconds. A node may override it; the SDK default stays authoritative. */
1908
1967
  export declare const DEFAULT_ORDER_QUOTE_TTL_SEC: number;
1909
1968
  export declare const STEP_CODES: readonly StepCode[];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ninsei-labs/sdk",
3
- "version": "0.58.0",
3
+ "version": "0.59.0",
4
4
  "publishConfig": {
5
5
  "access": "public",
6
6
  "registry": "https://registry.npmjs.org/"
@@ -169,9 +169,9 @@
169
169
  "url": "https://github.com/Ninsei-Labs/sdk/issues"
170
170
  },
171
171
  "dependencies": {
172
- "@hpke/chacha20poly1305": "1.8.0",
173
- "@hpke/core": "1.10.0",
174
- "@hpke/dhkem-x25519": "1.8.0",
172
+ "@hpke/chacha20poly1305": "1.8.1",
173
+ "@hpke/core": "1.10.1",
174
+ "@hpke/dhkem-x25519": "1.8.1",
175
175
  "@noble/curves": "^2.4.0",
176
176
  "@noble/hashes": "^2.4.0",
177
177
  "@scure/bip39": "2.4.0",
package/src/index.mjs CHANGED
@@ -214,7 +214,7 @@ export function createNinsei(options) {
214
214
  const quotes = createQuotes({ config, now: o.now || (() => Date.now()), evmCall: o.evmCall || null,
215
215
  evmCode: o.evmCode || null, evmBlock: o.evmBlock || null,
216
216
  providerAllowed, knownFactoryCodes, knownImplementationCodes,
217
- denylist });
217
+ denylist, fetchImpl: o.fetch || null });
218
218
  // THE SAME CHAIN-READ SEAM AS THE LOCK AND THE CORE: checking the slots and signing must go one way, otherwise
219
219
  // part of the check goes past the wallet and part does not.
220
220
  const actions = createActions({ call: o.evmCall });
@@ -271,7 +271,7 @@ export function createNinsei(options) {
271
271
  // before signing.
272
272
  // THE CHAIN READER GOES INTO THE SWAP START: it will check the escrow address, the order state and the fee
273
273
  // before signing. The Monero watch reads the chain through the same seam; there is no backend watcher.
274
- swaps: createSwaps({ preflight, mode: o.mode, xmrNetwork: o.xmrNetwork, call: o.evmCall, now: o.now || null, evmBlock: o.evmBlock || null, store,
274
+ swaps: createSwaps({ preflight, mode: o.mode, xmrNetwork: o.xmrNetwork, call: o.evmCall, fetchImpl: o.fetch || null, now: o.now || null, evmBlock: o.evmBlock || null, store,
275
275
  // THE LOG SEAM FOR THE DECLINE CHECK: the watch asks the escrow for its `Declined` event on every tick, so
276
276
  // a declined order stops the wait at once instead of running to `xmr-timeout`.
277
277
  logs: o.evmLogs || null,
@@ -288,7 +288,7 @@ export { SdkError, ERROR_CODES, ERROR_META, ERROR_SIDES, STEP_CODES, CHECK_CODES
288
288
  export { SDK_VERSION } from "./version.mjs";
289
289
  // THE QUOTE LIFETIME AND THE START MARGIN ARE ONE PUBLIC DEFAULT. A node imports the lifetime, so its signed quote
290
290
  // cannot be shorter than the margin the SDK enforces before it opens the wallet.
291
- export { LOCK_START_MARGIN_SEC, DEFAULT_ORDER_QUOTE_TTL_SEC } from "./quotePolicy.mjs";
291
+ export { LOCK_START_MARGIN_SEC, START_PREP_SEC, DEFAULT_ORDER_QUOTE_TTL_SEC } from "./quotePolicy.mjs";
292
292
 
293
293
  // THE LEVEL WALK IS ON THE PACKAGE SURFACE. A maker publishes a level set (chunks of volume with their own prices)
294
294
  // and both the node and the client compute a firm price by WALKING it - the client must reach the SAME price before
@@ -102,7 +102,16 @@ export interface DeploymentPin {
102
102
  readonly knownFactoryCodes: readonly string[];
103
103
  }
104
104
 
105
+ /** One factory that served a network, including the current one. */
106
+ export interface FactoryHistoryEntry {
107
+ readonly address: string;
108
+ readonly deploymentBlock: number;
109
+ readonly release: { readonly tag: string | null; readonly commit?: string | null; readonly [field: string]: unknown };
110
+ readonly status: "live" | "retired";
111
+ }
112
+
105
113
  export declare const DEPLOYMENTS: Readonly<Record<string, DeploymentPin>>;
114
+ export declare const FACTORY_HISTORY: Readonly<Record<string, readonly FactoryHistoryEntry[]>>;
106
115
  export declare const DEPLOYMENT_CHAINS: readonly string[];
107
116
  export declare const DEPLOYMENT_VMS: readonly string[];
108
117
  export declare function deploymentFor(
@@ -14,5 +14,6 @@ export {
14
14
  DEPLOYMENTS,
15
15
  DEPLOYMENT_CHAINS,
16
16
  DEPLOYMENT_VMS,
17
+ FACTORY_HISTORY,
17
18
  deploymentFor,
18
19
  } from "../../engine/core/config.js";
@@ -487,6 +487,14 @@ export declare function probeMoneroNode(options: {
487
487
  /** The watch key form that matches the address's view public key, or null when none does. */
488
488
  export declare function viewKeyFormForAddress(viewSecret: string, expectedViewPubHex: string): string | null;
489
489
 
490
+ /** Whether the view and spend keys belong to the primary address they are scanned for, and the one scalar form to use. */
491
+ export declare function watchedAddressVerdict(watched: {
492
+ address: string;
493
+ viewSecret: string | bigint;
494
+ spendPub: string;
495
+ }): { readonly ok: true; readonly viewSecret: bigint; readonly spendPub: string; readonly form: string }
496
+ | { readonly ok: false; readonly code: string; readonly field?: string; readonly why?: string };
497
+
490
498
  /** A boundary height derived from a later unlock_time, or null when the time names no height. */
491
499
  export declare function laterBoundary(...args: unknown[]): unknown;
492
500
 
@@ -21,7 +21,7 @@ export {
21
21
  } from "../../engine/monero/address.js";
22
22
 
23
23
  // THE BLOCK WALK A WATCHER RUNS: the same scanner the page uses, without a wallet.
24
- export { laterBoundary, scanRange, viewKeyFormForAddress } from "../../engine/monero/scan.js";
24
+ export { laterBoundary, scanRange, viewKeyFormForAddress, watchedAddressVerdict } from "../../engine/monero/scan.js";
25
25
 
26
26
  export { createHalves } from "../../engine/atomic/halves.js";
27
27
  export { createDleq2 } from "../../engine/atomic/dleq2.js";
@@ -1,25 +1,58 @@
1
- // THE ONE PLACE THE QUOTE LIFETIME AND ITS START MARGIN ARE NAMED.
1
+ // THE ONE PLACE THE QUOTE LIFETIME, ITS START MARGIN AND THE CLIENT'S PREPARATION TIME ARE NAMED.
2
2
  //
3
- // A firm quote is signed with `validUntil`, and the SDK refuses to start a swap when less than the start margin is left.
4
- // A node that signs a shorter life than that margin is refusing its own quotes before the wallet is opened. The node
5
- // imports this default and may override it with its own setting; the SDK keeps the value here so the two cannot drift.
3
+ // A firm quote is signed with `validUntil`. On a buy (`ask`) the SDK refuses to show a quote unless enough life is
4
+ // left to finish the proof, the record and the lock; on a sell (`bid`) the node has already funded the escrow before
5
+ // it answers, so the client opens no wallet and the lock margin protects nothing there.
6
+ //
7
+ // A node that signs a shorter life than the start rule is refusing its own quotes before the wallet is opened. The
8
+ // node imports these values and may override the lifetime with its own setting; the SDK keeps the values here so the
9
+ // two cannot drift.
6
10
  export const LOCK_START_MARGIN_SEC = 30;
7
11
 
12
+ // THE TIME THE CLIENT NEEDS BEFORE THE LOCK. The proof, the record and the chain reads each cost seconds on a
13
+ // desktop and several times longer on a phone without a JIT. The start margin alone covers only the next block; this
14
+ // allowance covers the SDK's own preparation, so a quote shown to a person still has time to be clicked.
15
+ export const START_PREP_SEC = 15;
16
+
8
17
  /** The default firm quote lifetime, in seconds. A node may override it, but the default is this value. */
9
18
  export const DEFAULT_ORDER_QUOTE_TTL_SEC = 60;
10
19
 
11
20
  /**
12
- * THE QUOTE MUST STILL HAVE ITS START MARGIN WHEN IT ARRIVES. The lock check runs seconds later, after the proof and
13
- * the record work; a quote that is already at the margin is refused here, before the caller shows a confirmation.
14
- * Returns `ok:false` for an unreadable clock too: an unknown lifetime is not a reason to show a quote.
21
+ * THE QUOTE MUST HAVE ENOUGH LIFE LEFT WHEN IT ARRIVES.
22
+ *
23
+ * A buy is checked against the start margin plus the preparation allowance: the proof and the record work take
24
+ * seconds, and refusing at the lock would show the person a confirmation that was never going to reach the wallet.
25
+ * A sell is checked only against its own expiry: the node has already funded the escrow, so there is no local lock
26
+ * to prepare and a short remaining life must not abandon that escrow.
27
+ *
28
+ * Returns `ok:false` for an unreadable clock too: an unknown lifetime is not a reason to show a quote. `confirmBySec`
29
+ * is the last second at which a buy can still be started; the host may disable its button after it.
15
30
  */
16
- export function quoteLifeVerdict({ validUntil, nowSec, marginSec = LOCK_START_MARGIN_SEC } = {}) {
31
+ export function quoteLifeVerdict({ validUntil, nowSec, side = "ask", marginSec = LOCK_START_MARGIN_SEC, prepSec = START_PREP_SEC } = {}) {
17
32
  const until = Number(validUntil);
18
33
  const now = Number(nowSec);
19
34
  const margin = Number(marginSec);
20
- if (!Number.isSafeInteger(until) || !Number.isSafeInteger(now) || !Number.isSafeInteger(margin) || margin < 0) {
21
- return { ok: false, code: "quote-too-short", remainingSec: null, marginSec: Number.isSafeInteger(margin) ? margin : null };
35
+ const prepare = Number(prepSec);
36
+ if (!Number.isSafeInteger(until) || !Number.isSafeInteger(now)) {
37
+ return { ok: false, code: "quote-too-short", remainingSec: null, marginSec: null, prepSec: null, confirmBySec: null };
22
38
  }
23
39
  const remainingSec = until - now;
24
- return { ok: remainingSec > margin, code: remainingSec > margin ? null : "quote-too-short", remainingSec, marginSec: margin };
40
+ const bid = side === "bid";
41
+ if (bid) {
42
+ const ok = remainingSec > 0;
43
+ return { ok, code: ok ? null : "quote-too-short", remainingSec, marginSec: 0, prepSec: 0, confirmBySec: until };
44
+ }
45
+ if (!Number.isSafeInteger(margin) || !Number.isSafeInteger(prepare) || margin < 0 || prepare < 0) {
46
+ return { ok: false, code: "quote-too-short", remainingSec, marginSec: null, prepSec: null, confirmBySec: null };
47
+ }
48
+ const requiredSec = margin + prepare;
49
+ const ok = remainingSec > requiredSec;
50
+ return {
51
+ ok,
52
+ code: ok ? null : "quote-too-short",
53
+ remainingSec,
54
+ marginSec: margin,
55
+ prepSec: prepare,
56
+ confirmBySec: until - requiredSec,
57
+ };
25
58
  }
package/src/quotes.mjs CHANGED
@@ -108,7 +108,7 @@ export function claimTipVerdict({ claimTipWei = 0, baseFeeWei = null, priorityFe
108
108
  }
109
109
 
110
110
  export function createQuotes({ config, now = () => Date.now(), evmCall = null, evmCode = null, evmBlock = null,
111
- providerAllowed = null, knownFactoryCodes = null, knownImplementationCodes = null, denylist = null }) {
111
+ providerAllowed = null, knownFactoryCodes = null, knownImplementationCodes = null, denylist = null, fetchImpl = null }) {
112
112
  // THE INTERFACE'S FACTORY POLICY (#103): the code hashes of factories it is willing to trade through
113
113
  // (extcodehash semantics = keccak256 of the runtime code). An EMPTY list is "no policy" (like
114
114
  // allowedProviders); a NON-EMPTY one refuses any factory whose code is not on it. Lower-cased once.
@@ -225,7 +225,7 @@ export function createQuotes({ config, now = () => Date.now(), evmCall = null, e
225
225
  const result = await requestFirmQuote({
226
226
  relayUrl: request.relayUrl,
227
227
  partner: request.partner,
228
- fetchImpl: request.fetchImpl,
228
+ fetchImpl: request.fetchImpl || fetchImpl,
229
229
  timeoutMs: request.timeoutMs,
230
230
  features,
231
231
  terms: {
@@ -246,15 +246,6 @@ export function createQuotes({ config, now = () => Date.now(), evmCall = null, e
246
246
  side,
247
247
  });
248
248
  const quote = result.quote;
249
- // A QUOTE THAT IS ALREADY AT THE START MARGIN CANNOT BECOME A SWAP. The proof and the record work take
250
- // seconds; refusing at the lock would show the person a confirmation that was never going to reach the wallet.
251
- // The check is here, on arrival, with its own code so the caller asks again without showing confirm.
252
- const answerNowSec = Math.floor(Number(now()) / 1000);
253
- const life = quoteLifeVerdict({ validUntil: quote.validUntil, nowSec: answerNowSec });
254
- if (!life.ok) {
255
- fail("quote-too-short", { step: "answer", validUntil: Number.isFinite(Number(quote.validUntil)) ? Number(quote.validUntil) : null,
256
- now: answerNowSec, remainingSec: life.remainingSec, marginSec: life.marginSec });
257
- }
258
249
  requirePinnedCashier(quote, "relay", config);
259
250
  // THE NODE HALF IS NOT A DECORATION. The answer's proof must stand in THIS order's context and the proven
260
251
  // point must be the one the quote commits to. For ask that is the claimer's commitment; for bid the node
@@ -381,7 +372,20 @@ export function createQuotes({ config, now = () => Date.now(), evmCall = null, e
381
372
  const marketAsset = request.market && String(request.market).includes(":")
382
373
  ? String(request.market).split(":").slice(1).join(":") : null;
383
374
  const asset = String(order.asset || marketAsset || "").trim();
375
+ // THE LIFE CHECK RUNS AFTER ALL THE WORK THE ANSWER NEEDS. The proof, the predict and the registry reads
376
+ // happen first; a quote that had 31 s on arrival has less by now, and showing a confirmation would waste the
377
+ // person's time only to refuse at the lock. A sell (bid) is checked by its own expiry alone: its escrow is
378
+ // already funded, so there is no local lock to prepare and no margin to reserve.
379
+ const answerNowSec = Math.floor(Number(now()) / 1000);
380
+ const life = quoteLifeVerdict({ validUntil: quote.validUntil, nowSec: answerNowSec, side });
381
+ if (!life.ok) {
382
+ fail("quote-too-short", { step: "answer", side,
383
+ validUntil: Number.isFinite(Number(quote.validUntil)) ? Number(quote.validUntil) : null,
384
+ now: answerNowSec, remainingSec: life.remainingSec, marginSec: life.marginSec,
385
+ prepSec: life.prepSec, confirmBySec: life.confirmBySec });
386
+ }
384
387
  const startQuote = { ...quote, viewHalfClaimer: derived.makerViewHalf, xmrAmount: signedAtomic, readyWindow,
388
+ escrow, remainingSec: life.remainingSec, confirmBySec: life.confirmBySec,
385
389
  ...(asset ? { asset, token: asset.toLowerCase() } : {}),
386
390
  // A STABLE ID FOR THE PENDING-FUNDING RECORD. The signed nonce is the one value every relay answer carries.
387
391
  ...(quote.nonce !== undefined && quote.nonce !== null ? { id: String(quote.nonce) } : {}) };
@@ -408,7 +412,10 @@ export function createQuotes({ config, now = () => Date.now(), evmCall = null, e
408
412
  counterparty: startCounterparty,
409
413
  recoveryKey: request.recoveryKey,
410
414
  recoverySalt: order.salt,
415
+ escrow,
411
416
  },
417
+ remainingSec: life.remainingSec,
418
+ confirmBySec: life.confirmBySec,
412
419
  // THE SHAPE `swaps.start` TAKES: the proof and the claimer commitment travel with the view half, so a
413
420
  // caller can pass this object as `counterparty` without rebuilding the relay fields.
414
421
  counterparty: startCounterparty,