@ninsei-labs/sdk 0.59.0 → 0.60.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.
@@ -1,6 +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
+ // Factory history: deployments/history/<vm>/<network>.json, mainnet-only retired factories for recovery.
4
4
  const freeze = (value) => {
5
5
  if (value && typeof value === "object") {
6
6
  Object.freeze(value);
@@ -87,22 +87,6 @@ const DATA = {
87
87
  };
88
88
  const HISTORY_DATA = {
89
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
90
  {
107
91
  "address": "0x245d3a4ac4b98d713f6c5130b56cd5d550f8cefe",
108
92
  "deploymentBlock": 326005419,
package/index.d.ts CHANGED
@@ -54,7 +54,8 @@ export interface NinseiOptions {
54
54
  /** "live" - real nodes and chain; "sim" - a sandbox (mocks, accelerated time, failure scenarios). */
55
55
  mode?: "live" | "sim";
56
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
+ * Monero height probes and witness checks; per-call `fetchImpl` wins for relay quote/claim and `fetch` wins for
58
+ * arrival/witness checks. An arrival request may override it with its own `fetch`. */
58
59
  fetch?: FetchLike;
59
60
  /** The clock. In "sim" the SDK uses it to accelerate time. */
60
61
  now?: () => number;
@@ -168,9 +169,22 @@ export interface NinseiOptions {
168
169
  createRecord?: (request: StartRequest) => Promise<SwapRecord> | SwapRecord;
169
170
  }
170
171
 
172
+ /** One durable sender attempt on a sell record, written before the relay POST. */
173
+ export interface StoredClaimAttempt {
174
+ readonly sender: string;
175
+ readonly at?: number;
176
+ readonly outcome: "sending" | "refused" | "unknown" | "unconfirmed" | "claimed";
177
+ readonly code?: string | null;
178
+ readonly params?: Readonly<Record<string, unknown>> | null;
179
+ readonly txid?: string | null;
180
+ }
181
+
171
182
  /** The result of assembling the swap record: the record itself, your own side and what is missing. */
172
183
  export interface SwapRecord {
173
- readonly swap: Readonly<Record<string, unknown>>;
184
+ readonly swap: Readonly<Record<string, unknown>> & {
185
+ /** The ordered claim attempts; absent on records written before the journal existed. */
186
+ readonly claimAttempts?: readonly StoredClaimAttempt[];
187
+ };
174
188
  /** Our side of the order: halves, points, the proof and the encryption key. The shape is set by the builder. */
175
189
  readonly side: unknown;
176
190
  /** What the record is missing: for a start that is the counterparty's half (`counterparty-half`). */
@@ -558,6 +572,8 @@ export interface FirmRelayAnswer {
558
572
  }>;
559
573
  /** The relay origin that answered. `startSell` stores it for the later no-wallet claim. */
560
574
  readonly relayUrl: string;
575
+ /** The sender `GET /v1/relay` publishes for claims; null when the relay did not name one. */
576
+ readonly claimSender: string | null;
561
577
  readonly relay: string | null;
562
578
  readonly offered: number | null;
563
579
  readonly forwarded: Readonly<Record<string, unknown>> | null;
@@ -673,17 +689,17 @@ export interface SwapsApi {
673
689
  */
674
690
  claimViaRelay(request: RelayClaimRequest): Promise<RelayClaimResult>;
675
691
  /**
676
- * WAIT FOR THE XMR TO ARRIVE at the order's joint address. The polling uses the same request as the page's
677
- * (GET /swaps/{id}), the rate and the timeout - from `config.limits` and overridable here.
678
- * It arrived - the FACT is returned (the amount, the confirmations, the txid); we did not wait - a refusal with
679
- * the CODE `xmr-timeout`, separate from the others: "the wait expired" is a state of the money, not a breakdown.
692
+ * WAIT FOR THE XMR TO ARRIVE at the order's joint address. The polling is the client's own `verify` walk; there
693
+ * is no backend status call. The rate and the timeout come from `config.limits` and are overridable here.
694
+ * It arrived - the FACT is returned (the amount, the confirmations, the txid, and the joint Monero address); we did
695
+ * not wait - a refusal with the CODE `xmr-timeout`, separate from the others: "the wait expired" is a state of the
696
+ * money, not a breakdown.
680
697
  * XMR ON THE ADDRESS BUT LOCKED BY `unlock_time` is a THIRD answer with its own code `xmr-locked` (the boundary,
681
698
  * a height or a date, is in `params.until`): locked funds are NOT an arrival, and nothing is signed under them.
682
699
  * IF `expect` AND `wallet` ARE PASSED, then after the arrival the ready mark (actions.markReady) is called with
683
- * THESE expectations: the slot check against the chain stands in it before the signature. Without them the step
684
- * names the next one (`next: "mark-ready"`) and signs nothing.
685
- * THE MAKER DECLINED - THE WAIT STOPS AT ONCE (issue #40): the escrow's `Declined` event and the service's
686
- * `declined` + `compliance` status are BOTH asked on every tick, and either one ends the wait with
700
+ * THESE expectations and the EVM escrow: the slot check against the chain stands in it before the signature.
701
+ * Without them the step names the next one (`next: "mark-ready"`) and signs nothing.
702
+ * THE MAKER DECLINED - THE WAIT STOPS AT ONCE (issue #40): the escrow's `Declined` event ends the wait with
687
703
  * `SwapDeclinedWatch` instead of running to `xmr-timeout` about an order whose ETH is already back. Nothing is
688
704
  * signed, and the decline is written into the record, so every later read of the swap reports the same state.
689
705
  */
@@ -820,6 +836,8 @@ export interface XmrArrivalRequest {
820
836
  readonly fromHeight?: number | null;
821
837
  readonly nowSec?: number;
822
838
  readonly timeoutMs?: number;
839
+ /** The transport for node and witness reads; absent - the client's `fetch`, otherwise the global fetch. */
840
+ readonly fetch?: FetchLike;
823
841
  }
824
842
 
825
843
  /** The slice check's extra input: independent witnesses that serve witness-v1. */
@@ -849,6 +867,10 @@ export interface XmrWitnessShadowReading {
849
867
  };
850
868
  readonly checked: readonly Record<string, unknown>[];
851
869
  readonly failed: readonly Record<string, unknown>[];
870
+ /** One opinion per operator: seen/txid/height/blockHash/amount/locked. */
871
+ readonly observations: readonly Record<string, unknown>[];
872
+ /** Same-operator and cross-operator contradictions, plus contradictions against the exact reading. */
873
+ readonly disagreements: readonly Record<string, unknown>[];
852
874
  }
853
875
 
854
876
  /** The exact verdict and the slice reading, side by side. This is not a swap decision. */
@@ -973,6 +995,8 @@ export interface SellStartRequest {
973
995
  * naming the deal's maker or its quote-key owner is refused.
974
996
  */
975
997
  readonly claimSender?: string;
998
+ /** The ordered senders stored for a later `claimViaRelay`; the relay's published sender is prepended. */
999
+ readonly claimSenders?: readonly string[];
976
1000
  /** The twelve-word key; required only when no key is stored yet. */
977
1001
  readonly recoveryKey?: string | { readonly mnemonic: string };
978
1002
  /** The recovery file's passphrase. In memory; the interface puts it on disk if it deems fit. */
@@ -997,6 +1021,8 @@ export interface SellStart {
997
1021
  readonly orderQuote: Readonly<Record<string, unknown>> | null;
998
1022
  /** The legacy single sender stored by `startSell`, or null when the client supplies the list at claim time. */
999
1023
  readonly claimSender: string | null;
1024
+ /** The ordered senders stored by `startSell`; empty when the client supplies the list at claim time. */
1025
+ readonly claimSenders: readonly string[];
1000
1026
  readonly readyWindow: ReadyWindow | null;
1001
1027
  readonly resumed: boolean;
1002
1028
  readonly next: "send-xmr";
@@ -1026,10 +1052,11 @@ export interface RelayClaimRequest {
1026
1052
  readonly relayUrl?: string;
1027
1053
  /** One sender's slot; clamped to 15-30 s. Default 20 s. */
1028
1054
  readonly slotMs?: number;
1029
- /** How often the escrow is read during a slot. Default 2 s. */
1055
+ /** How often the escrow is read during a slot; clamped to at least 250 ms. Default 2 s. */
1030
1056
  readonly pollMs?: number;
1031
- readonly fetchImpl?: typeof fetch;
1057
+ /** HTTP timeout per sender; capped at 120 s. Default 20 s. */
1032
1058
  readonly timeoutMs?: number;
1059
+ readonly fetchImpl?: typeof fetch;
1033
1060
  }
1034
1061
 
1035
1062
  /** One sender's outcome in a list claim. */
@@ -1060,7 +1087,27 @@ export interface RelayClaimed {
1060
1087
  /** No sender landed the claim. The seller must send `sellClaim` before `t1`. */
1061
1088
  export interface RelayClaimYourself {
1062
1089
  readonly state: "claim-yourself";
1063
- readonly reason: "senders-exhausted" | "escrow-refunded";
1090
+ readonly reason: "senders-exhausted";
1091
+ readonly id: string;
1092
+ readonly provider: null;
1093
+ readonly claimSender: null;
1094
+ readonly escrow: string;
1095
+ readonly relayUrl: string;
1096
+ readonly txid: null;
1097
+ readonly from: null;
1098
+ readonly tipWei: string;
1099
+ readonly t1: number | null;
1100
+ readonly secondsLeft: number | null;
1101
+ readonly tried: readonly RelayClaimAttempt[];
1102
+ }
1103
+
1104
+ /**
1105
+ * The half was not handed to any sender because the escrow's own claim window is not open. The caller must not
1106
+ * retry the relay list: the state, not the sender, is the answer.
1107
+ */
1108
+ export interface RelayClaimWindow {
1109
+ readonly state: "claim-window";
1110
+ readonly reason: "not-ready" | "window-closed" | "settlement-margin" | "unreadable" | "not-funded" | "escrow-refused" | "escrow-refunded";
1064
1111
  readonly id: string;
1065
1112
  readonly provider: null;
1066
1113
  readonly claimSender: null;
@@ -1074,7 +1121,7 @@ export interface RelayClaimYourself {
1074
1121
  readonly tried: readonly RelayClaimAttempt[];
1075
1122
  }
1076
1123
 
1077
- export type RelayClaimResult = RelayClaimed | RelayClaimYourself;
1124
+ export type RelayClaimResult = RelayClaimed | RelayClaimYourself | RelayClaimWindow;
1078
1125
 
1079
1126
  export interface SellWatchRequest {
1080
1127
  /** The escrow predicted by the relay adapter. */
@@ -1087,14 +1134,18 @@ export interface SellWatchRequest {
1087
1134
 
1088
1135
  export interface SellWatchResult {
1089
1136
  readonly escrow: string;
1090
- readonly state: "ready" | "claim-open" | "claimed" | "refunded";
1137
+ readonly state: "ready" | "claim-open" | "claim-window-closed" | "claimed" | "refunded";
1091
1138
  readonly funded: boolean;
1092
1139
  readonly claimed: boolean;
1093
1140
  readonly refunded: boolean;
1094
1141
  /** `null` for a terminal claim/refund: the ready mark is not part of that answer. */
1095
1142
  readonly ready: boolean | null;
1096
- /** True when the escrow's readyBy has passed and no ready mark or terminal action was seen. */
1143
+ /** True when the escrow's readyBy has passed, t1 has not, and no ready mark or terminal action was seen. */
1097
1144
  readonly claimOpen: boolean;
1145
+ /** The order's deadline when the answer is about the claim window. */
1146
+ readonly t1?: number | null;
1147
+ /** Seconds from the observed clock to t1, when the answer is about the claim window. */
1148
+ readonly secondsLeft?: number | null;
1098
1149
  readonly balanceWei: string;
1099
1150
  readonly waitedMs: number;
1100
1151
  }
@@ -1102,7 +1153,7 @@ export interface SellWatchResult {
1102
1153
  export interface SwapWatchRequest {
1103
1154
  /** The local swap record identifier. */
1104
1155
  readonly id: string;
1105
- /** The escrow address for the ready mark (mandatory when `expect` and `wallet` are passed). */
1156
+ /** The escrow address for the ready mark (mandatory when `expect` and `wallet` are passed and the record has none). */
1106
1157
  readonly escrow?: string;
1107
1158
  /** How often to ask the state. Default - `config.limits.watchPollMs`. */
1108
1159
  readonly pollMs?: number;
@@ -1117,7 +1168,7 @@ export interface SwapWatchRequest {
1117
1168
  /**
1118
1169
  * CLIENT-SIDE ARRIVAL CHECK (issue #85). With this the CLIENT decides: it reads the chain itself and `ready`
1119
1170
  * opens only when two operators agree. The backend's `seen` is then only a notification and does not open the
1120
- * button. Without it the watch keeps the service's answer.
1171
+ * button. `verify` is mandatory: without it the watch refuses with `bad-input`.
1121
1172
  */
1122
1173
  readonly verify?: Omit<XmrArrivalRequest, "minConfirmations">;
1123
1174
  /** The confirmation target before `ready`. Default - `config.limits.xmrConfirmations` (10). */
@@ -1159,8 +1210,9 @@ export interface SwapDeclinedWatch {
1159
1210
  export interface SwapWatch {
1160
1211
  readonly seen: true;
1161
1212
  readonly id: string;
1213
+ /** The joint Monero address the client checked - never the EVM escrow. */
1162
1214
  readonly address: string | null;
1163
- /** The watch state at the service (awaiting_funding | funded | ready | ...). */
1215
+ /** The legacy service status; null because the watch no longer asks a service. */
1164
1216
  readonly status: string | null;
1165
1217
  readonly expectedXmr: number | null;
1166
1218
  readonly receivedXmr: number;
@@ -1427,7 +1479,7 @@ export interface SweepRestoreRequest {
1427
1479
  */
1428
1480
  readonly trustedNode?: boolean;
1429
1481
  };
1430
- /** The fetch used for `get_block`; absent - the global fetch. */
1482
+ /** The fetch used for `get_block`; absent - the instance `fetch` from `createNinsei`, then the global fetch. */
1431
1483
  readonly fetchImpl?: typeof fetch;
1432
1484
  }
1433
1485
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ninsei-labs/sdk",
3
- "version": "0.59.0",
3
+ "version": "0.60.0",
4
4
  "publishConfig": {
5
5
  "access": "public",
6
6
  "registry": "https://registry.npmjs.org/"
package/src/index.mjs CHANGED
@@ -280,7 +280,7 @@ export function createNinsei(options) {
280
280
  createRecord: o.createRecord }),
281
281
  // XMR WITHDRAWAL: parsing the file and requesting data work; the withdrawal itself is named (the Monero
282
282
  // wallet as an adapter).
283
- sweep: createSweep({ call: o.evmCall }),
283
+ sweep: createSweep({ call: o.evmCall, fetchImpl: o.fetch || null }),
284
284
  });
285
285
  }
286
286
 
@@ -0,0 +1,25 @@
1
+ // ONE PREDICTION FOR THE THREE SDK PATHS. The escrow address is a factory read of the signed quote plus the
2
+ // depositor's half; the quote check, the swap start and the pending retry all need exactly the same calldata.
3
+ // Keeping the assembly here leaves one place to change when the signed term set grows.
4
+ import * as engine from "./engine.mjs";
5
+
6
+ /** The quote the factory receives: signed terms plus the depositor's own half and the resolved factory. */
7
+ export function predictTerms({ quote, order = null, lockerHalf = null, factory = null } = {}) {
8
+ if (!quote || typeof quote !== "object") throw new Error("a signed quote is required for predict()");
9
+ const resolvedFactory = factory || (order && order.factory) || quote.factory;
10
+ if (!resolvedFactory) throw new Error("the quote names no factory");
11
+ const half = lockerHalf || {
12
+ commitHalfLocker: (order && order.commitHalfLocker) ?? quote.commitHalfLocker,
13
+ edPointLocker: (order && order.edPointLocker) ?? quote.edPointLocker,
14
+ edViewPointLocker: (order && order.edViewPointLocker) ?? quote.edViewPointLocker,
15
+ };
16
+ return { ...quote, ...half, factory: resolvedFactory };
17
+ }
18
+
19
+ /** Read the factory's predicted escrow. The caller maps a failed read; no address is guessed here. */
20
+ export async function predictEscrow({ quote, order = null, lockerHalf = null, factory = null, call } = {}) {
21
+ if (typeof call !== "function") throw new Error("a chain read is required for predict()");
22
+ const terms = predictTerms({ quote, order, lockerHalf, factory });
23
+ const raw = await call({ to: terms.factory, data: engine.evm.encodePredict(terms) });
24
+ return engine.evm.decodeAddress(raw);
25
+ }
package/src/quotes.mjs CHANGED
@@ -10,6 +10,7 @@ import { claimGasGiftWei } from "../engine/evm/claimGas.js";
10
10
  import { takerHalvesV2, recoverySaltOf } from "./recovery-key.mjs";
11
11
  import { acceptCounterpartyChunked, buildOwnSideFromHalvesChunked, jointAddress } from "./order.mjs";
12
12
  import { requestFirmQuote } from "./relayFirmClient.mjs";
13
+ import { predictEscrow } from "./predictEscrow.mjs";
13
14
  import { readReadyWindow } from "./readyWindow.mjs";
14
15
  import { quoteLifeVerdict } from "./quotePolicy.mjs";
15
16
  // THE CHAIN READ NEEDED TO ASK THE REGISTRY WHO OWNS THE KEY. The selector is COMPUTED from the signature, not
@@ -290,11 +291,7 @@ export function createQuotes({ config, now = () => Date.now(), evmCall = null, e
290
291
  : { commitHalfLocker: nodeHalf.commitHalf, edPointLocker: nodeHalf.edPoint, edViewPointLocker: result.edViewPointLocker };
291
292
  let escrow = null;
292
293
  try {
293
- const predicted = await evmCall({
294
- to: quote.factory,
295
- data: engine.evm.encodePredict({ ...result.orderQuote, ...lockerHalf, signature: result.orderQuote.signature }),
296
- });
297
- escrow = engine.evm.decodeAddress(predicted);
294
+ escrow = await predictEscrow({ quote: result.orderQuote, lockerHalf, call: evmCall });
298
295
  } catch {
299
296
  fail("quote-escrow-unchecked", { step: "factory", why: "predict-failed", factory: quote.factory });
300
297
  }
@@ -139,12 +139,30 @@ export async function requestFirmQuote({
139
139
  || wireText(published.relayId, "relay.relayId") !== wireText(response.body.relay, "relay")) {
140
140
  throw new SdkError("quote-refused", { step: "relay-info", why: "relay" });
141
141
  }
142
+ // THE OPERATOR'S OWN CLAIM SENDER. `GET /v1/relay` publishes the address the relay submits claims from; it is the
143
+ // first entry in the seller's ordered list. A malformed value is refused here rather than handed to a claim path.
144
+ let claimSender = null;
145
+ const publishedSender = published.claimSender;
146
+ if (publishedSender !== undefined && publishedSender !== null) {
147
+ // A NON-STRING IS NOT AN ADDRESS. Check the type before any coercion: `String({toString: null})` throws before
148
+ // the refusal can be named, and the caller would see a raw TypeError instead of quote-refused/claim-sender.
149
+ if (typeof publishedSender !== "string") {
150
+ throw new SdkError("quote-refused", { step: "relay-info", why: "claim-sender" });
151
+ }
152
+ if (publishedSender.trim() !== "") {
153
+ claimSender = publishedSender.trim().toLowerCase();
154
+ if (!/^0x[0-9a-f]{40}$/.test(claimSender)) {
155
+ throw new SdkError("quote-refused", { step: "relay-info", why: "claim-sender" });
156
+ }
157
+ }
158
+ }
142
159
  return {
143
160
  ...verified,
144
161
  // THE ORIGIN THAT ANSWERED, KEPT FOR THE LATER CLAIM. The seller has no wallet, so the claim goes back to the
145
162
  // same relay through `swaps.claimViaRelay`; the record stores this value and a different origin is refused.
146
163
  relayUrl: base,
147
164
  relay: response.body.relay ?? null,
165
+ claimSender,
148
166
  offered: response.body.offered ?? null,
149
167
  forwarded: response.body.forwarded ?? null,
150
168
  answer,