@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.
- package/CHANGELOG.md +6 -0
- package/README.md +37 -24
- package/THIRD_PARTY_NOTICES.md +7 -4
- package/assets/vendors/MANIFEST.json +1 -1
- package/assets/vendors/sdk/sdk-browser.js +4 -6
- package/engine/core/config.js +2 -2
- package/engine/core/deployments.generated.js +33 -0
- package/engine/monero/scan.js +56 -8
- package/index.d.ts +84 -25
- package/package.json +4 -4
- package/src/index.mjs +3 -3
- package/src/public/networks.d.ts +9 -0
- package/src/public/networks.mjs +1 -0
- package/src/public/xmr.d.ts +8 -0
- package/src/public/xmr.mjs +1 -1
- package/src/quotePolicy.mjs +44 -11
- package/src/quotes.mjs +18 -11
- package/src/record.mjs +4 -0
- package/src/swaps.mjs +292 -73
- package/src/version.mjs +1 -1
- package/src/witness-slice.mjs +84 -0
- package/src/xmr-arrival.mjs +221 -120
package/engine/core/config.js
CHANGED
|
@@ -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) {
|
package/engine/monero/scan.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
//
|
|
2
|
-
//
|
|
3
|
-
//
|
|
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
|
-
|
|
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
|
|
469
|
+
for (const { entry: w, bound } of boundWatched) {
|
|
440
470
|
const r = findOurOutputs({
|
|
441
471
|
txPublicKeys: keys.txPublicKeys, additionalPublicKeys: keys.additionalPublicKeys,
|
|
442
|
-
viewSecretHex:
|
|
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
|
|
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.
|
|
661
|
-
*
|
|
662
|
-
*
|
|
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
|
|
665
|
-
*
|
|
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
|
-
*
|
|
959
|
-
*
|
|
960
|
-
*
|
|
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
|
|
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. `
|
|
1003
|
-
* the deal's maker
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
1016
|
-
export interface
|
|
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
|
|
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
|
-
|
|
1024
|
-
|
|
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.
|
|
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.
|
|
173
|
-
"@hpke/core": "1.10.
|
|
174
|
-
"@hpke/dhkem-x25519": "1.8.
|
|
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
|
package/src/public/networks.d.ts
CHANGED
|
@@ -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(
|
package/src/public/networks.mjs
CHANGED
package/src/public/xmr.d.ts
CHANGED
|
@@ -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
|
|
package/src/public/xmr.mjs
CHANGED
|
@@ -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";
|
package/src/quotePolicy.mjs
CHANGED
|
@@ -1,25 +1,58 @@
|
|
|
1
|
-
// THE ONE PLACE THE QUOTE LIFETIME
|
|
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
|
|
4
|
-
//
|
|
5
|
-
//
|
|
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
|
|
13
|
-
*
|
|
14
|
-
*
|
|
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
|
-
|
|
21
|
-
|
|
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
|
-
|
|
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,
|