@ninsei-labs/sdk 0.58.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.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,19 @@
1
+ ## 0.60.0 — 2026-11-13
2
+
3
+ - `swaps.watch` keeps the joint Monero address apart from the EVM escrow: the result carries the address the client checked, and the automatic ready mark always signs against the escrow. A typed watch no longer returns the escrow as its `address`; the legacy untyped `request.address` is not read. `verify` remains mandatory, so a watch without the client's own check is refused by name instead of falling back to a retired service answer.
4
+ - The claim window is read from the escrow before a sender is tried: a funded escrow that is already refunded reports `state: "claim-window"` with `reason: "escrow-refunded"`, not `claim-yourself`.
5
+ - `claimViaRelay` writes each sender to the record before its POST. A reload skips a refused or unconfirmed sender, while a `sending` or `unknown` attempt stops with `claim-unknown` and `why: "previous-sender-unknown"` so the half is not sent twice. `timeoutMs` is capped at 120 s, `slotMs` is clamped to 15-30 s, and `pollMs` is at least 250 ms and no longer than the slot.
6
+ - `startSell` stores the client's ordered `claimSenders` once, including the relay-published `claimSender` when present; a later `claimViaRelay({ id })` uses the stored list without repeating it.
7
+ - `sweep.restore` inherits the instance `fetch` transport, and a per-call `fetchImpl` still wins. A retry whose factory prediction cannot be read is `quote-factory-unchecked` with `why: "predict-failed"`, not a missing escrow.
8
+ - The recovery salt is canonicalised before the pending lookup, the arrival shadow raises its target to a witness tip served during the walk, and a failed witness walk is `witness:not-completed` rather than agreement.
9
+ - The supported version line is `0.60.x`; the package version and the baked-in `SDK_VERSION` move together.
10
+
11
+ ## 0.59.0 — 2026-11-11
12
+
13
+ - `FACTORY_HISTORY` is generated from the reviewed deployment manifests and `deployments/history/<vm>/<network>.json`. It lists the current factory as `live` and older factories as `retired`, each with its deployment block and release tag, so a recovery page can find old orders without a second hand-written address table.
14
+ - The deployment pin check is part of the full `pnpm run check` battery; it verifies the generated pins, the current `CHAINS`/`KNOWN_FACTORY_CODES` values, and the order and uniqueness of the factory history.
15
+ - The EVM deployment history for `arbitrum-sepolia` carries the two factories before `contracts-testnet-2026.11.04`; the current factory comes from the reviewed manifest.
16
+
1
17
  ## 0.58.0 — 2026-11-10
2
18
 
3
19
  - `swaps.verifyArrivalShadow` runs the exact arrival walk and the fixed-slice witness-v1 walk side by side. The witness request carries only `{version, network, grid, slice}` (20 blocks aligned to multiples of 20), never the start height, payout block, txid or order id; a node without `protocol: "witness-v1"` is refused rather than guessed. The exact verdict still decides, so this is the staging path before an independent operator serves the protocol.
package/README.md CHANGED
@@ -22,7 +22,7 @@ Report suspected vulnerabilities through GitHub's private **Report a vulnerabili
22
22
  The supported versions, scope, response targets, safe-harbor rules and disclosure process are in
23
23
  [`SECURITY.md`](SECURITY.md).
24
24
 
25
- ## State (0.58.0)
25
+ ## State (0.60.0)
26
26
 
27
27
  | Surface | State |
28
28
  |---|---|
@@ -34,9 +34,9 @@ The supported versions, scope, response targets, safe-harbor rules and disclosur
34
34
  | `quotes.firmRelay` | works: a firm quote through a relay, built from one recovery key; the node half is DLEQ-checked |
35
35
  | `swaps.list` / `swaps.get` | read state from storage (and after a page reload) |
36
36
  | `swaps.start` | holds the order: guards → recovery file and the person's confirmation → order → locking funds → **watching the Monero address**; no backend is required; returns the named state `step: "xmr-incoming"` |
37
- | `swaps.watch` | waits for XMR at the joint address with the CLIENT's own check: `verify` carries the joint address, view secret, spend public key and witness nodes. Arrived — returns the fact (amount, confirmations, txid); did not wait — a refusal with `xmr-timeout`; funds barred by `unlock_time` — `xmr-locked`; the maker DECLINED — `SwapDeclinedWatch` (`declined: true`, `terminal: "declined"`), every action off; with expectations and a wallet, places the ready mark after the arrival |
37
+ | `swaps.watch` | waits for XMR at the joint address with the CLIENT's own check: `verify` carries the joint address, view secret, spend public key and witness nodes, and is mandatory — without it the watch refuses with `bad-input`. Arrived — returns the fact (amount, confirmations, txid) and the joint address; did not wait — a refusal with `xmr-timeout`; funds barred by `unlock_time` — `xmr-locked`; the maker DECLINED — `SwapDeclinedWatch` (`declined: true`, `terminal: "declined"`), every action off; with expectations and a wallet, places the ready mark after the arrival against the escrow, never against the Monero address |
38
38
  | `swaps.verifyArrivalShadow` | the staging path for witness-v1: runs the exact walk and the fixed-slice walk side by side, without changing ready or refund. The slice request carries only the grid and slice; a node must name `protocol: "witness-v1"` |
39
- | `swaps.startSell` / `swaps.sellClaim` / `swaps.claimViaRelay` | a sell is recorded from the verified relay offer; `sellClaim` claims from the claimer's own wallet, `claimViaRelay` claims with no wallet through the sender the client chose, paid by the signed `claimTip` |
39
+ | `swaps.startSell` / `swaps.sellClaim` / `swaps.claimViaRelay` | a sell is recorded from the verified relay offer; `sellClaim` claims from the claimer's own wallet, `claimViaRelay` claims with no wallet through the client's ordered sender list, paid by the signed `claimTip` |
40
40
  | `wallet.balances` | works: the native coin and tokens, in minimal units |
41
41
 
42
42
  What is not ready names itself with the code `not-implemented` with the fields `surface` and `stage`: an empty
@@ -155,9 +155,9 @@ interface's: this package holds no user-facing string.
155
155
  ### Errors (`error.code`, `SdkError.code`)
156
156
 
157
157
  `not-implemented`, `bad-input`, `wallet-not-connected`, `wallet-rejected`, `wrong-chain`, `quote-unavailable`,
158
- `quote-refused`, `address-denied`, `quote-stale`, `recovery-declined`, `recovery-failed`, `storage-unavailable`,
159
- `server-unavailable`, `server-refused`, `claim-unknown`, `xmr-timeout`, `xmr-locked`, `contract-reverted`,
160
- `insufficient-funds`, `unknown`.
158
+ `quote-refused`, `quote-too-short`, `quote-expired`, `address-denied`, `quote-stale`, `recovery-declined`,
159
+ `recovery-failed`, `storage-unavailable`, `xmr-address-mismatch`, `server-unavailable`, `server-refused`,
160
+ `claim-unknown`, `xmr-timeout`, `xmr-locked`, `contract-reverted`, `insufficient-funds`, `unknown`.
161
161
 
162
162
  Three refusals that are easy to merge into one are named DIFFERENTLY, because the advice differs:
163
163
  `server-unavailable` — the service did not answer (retry); `server-refused` — it answered and did not accept (its
@@ -179,9 +179,15 @@ in the package; a host that needs an indicative book keeps it in the host.
179
179
  ```js
180
180
  const offer = await sdk.quotes.firmRelay({ relayUrl, features, order, side: "ask", recoveryKey, xmrAmount });
181
181
  offer.orderQuote; // the signed quote the factory takes
182
- offer.startRequest; // quote, order, orderQuote, counterparty and recovery salt for swaps.start
182
+ offer.startRequest; // quote, order, orderQuote, counterparty, recovery salt and predicted escrow for swaps.start
183
183
  ```
184
184
 
185
+ A buy quote must keep `LOCK_START_MARGIN_SEC` (30 s) plus `START_PREP_SEC` (15 s) after the relay answer has been
186
+ verified. `quotes.firmRelay` refuses a shorter one with `quote-too-short` before a confirmation is shown, and returns
187
+ `remainingSec` / `confirmBySec` so the host can show the time left and disable its button. A bid quote is checked only
188
+ for its own expiry: the node has already funded the escrow and the client opens no wallet. The lock step then checks only
189
+ the 30 s margin: the preparation was already spent between the answer and the send.
190
+
185
191
  ## Selling and claiming
186
192
 
187
193
  A bid is a sale of XMR. `quotes.firmRelay({ side: "bid", claimTip, ... })` returns the signed quote, the escrow,
@@ -203,23 +209,49 @@ relay submits the half and is paid from the claim itself. No wallet is created o
203
209
  signed by the client:
204
210
 
205
211
  ```js
206
- const sell = await sdk.swaps.startSell({ offer, claimSender }); // another listed maker
207
- const claimed = await sdk.swaps.claimViaRelay({ id: sell.id });
208
- claimed.txid; // the claim transaction
209
- claimed.from; // the sender node's claim sender
210
- claimed.tipWei; // the signed tip paid out of the claim
212
+ const sell = await sdk.swaps.startSell({ offer });
213
+ const relaySender = offer.claimSender; // GET /v1/relay; the relay origin that answered
214
+ const claimed = await sdk.swaps.claimViaRelay({ id: sell.id,
215
+ claimSenders: [...(relaySender ? [relaySender] : []), ...otherListedMakers] });
216
+ if (claimed.state === "claimed") {
217
+ claimed.txid; // the claim transaction, or null when the escrow itself showed claimed
218
+ claimed.from; // the sender node's claim sender
219
+ claimed.tipWei; // the signed tip paid out of the claim
220
+ } else if (claimed.state === "claim-window") {
221
+ claimed.reason; // not-ready | window-closed | settlement-margin | not-funded | unreadable | escrow-refused | escrow-refunded
222
+ } else {
223
+ claimed.secondsLeft; // no sender landed it: claim yourself before t1
224
+ }
211
225
  ```
212
226
 
213
- `claimSender` is chosen by the client from the relay's price answer: a listed maker OTHER than the deal's maker and
214
- other than its quote key owner. `startSell` stores it with the record, so a reload claims through the same node; a
215
- record made before the sender was stored may pass `claimSender` to `claimViaRelay` once; it is stored on the record
216
- then. A sender naming the deal's maker or its quote key is refused before the half leaves the client.
217
-
218
- `claimViaRelay` reads the sell record made by `startSell` and requires a positive `claimTip`, the sender, the
219
- escrow and the half. It posts to the relay origin stored with the record; an optional `relayUrl` may repeat that
220
- origin but a different one is refused. A node refusal is `quote-refused` with the sender's own code in
221
- `params.code`. A timeout or a body without a real transaction hash is `claim-unknown`: the claim may have been
222
- sent, so read the escrow before trying anything else. Only a validated txid is returned as a claim.
227
+ `claimSenders` is the client's ordered list: the relay's own sender first, then other listed makers. `startSell`
228
+ accepts the same list (or the relay answer's published `claimSender`) and stores it, so a later
229
+ `claimViaRelay({ id })` can use the record without repeating the list. The SDK tries
230
+ one sender at a time for a 15-30 s slot. A refusal moves on at once; a txid is not success - the SDK reads the
231
+ escrow until it says `claimed` or the slot ends. The deal's maker and its quote-key owner are refused before the
232
+ half leaves the client. When the list is exhausted the result is `state: "claim-yourself"` with `t1` and
233
+ `secondsLeft`. The old scalar `claimSender` remains a one-element fallback for callers written before the list.
234
+
235
+ The claim window is the escrow's, not the relay's. Before every sender the SDK reads `ready`, `readyBy` and `t1`
236
+ from the chain. Without the ready mark before `readyBy`, at or after `t1`, or inside the 120 s settlement margin
237
+ (plus the sender's slot and time for the seller's own claim), it returns `state: "claim-window"` with a named
238
+ `reason` and posts nothing. An unread escrow is `claim-unknown` with `why: "escrow-unread"`; it is never reported as
239
+ `claim-yourself`. A relay answer such as `claim-not-ready` or `claim-window-closed` stops the list instead of
240
+ passing the half to the next sender.
241
+
242
+ `claimViaRelay` reads the sell record made by `startSell` and requires a positive `claimTip`, the escrow and the
243
+ half. It posts to the relay origin stored with the record; an optional `relayUrl` may repeat that origin but a
244
+ different one is refused. A node refusal keeps its code under `quote-refused.params.code`. A timeout or a body
245
+ without a real transaction hash is `claim-unknown`: the claim may have been sent, so the SDK reads the escrow and
246
+ moves on only after the slot. Only an escrow that reads `claimed` is success.
247
+
248
+ Each sender is written to the record before its POST. A reload skips senders that were already tried; a refused
249
+ sender allows the next, while an attempt left `sending` or `unknown` stops with `claim-unknown` and
250
+ `why: "previous-sender-unknown"` instead of resending the half. An `unconfirmed` sender is skipped as well. A
251
+ sender's slot starts when it is entered, not when its POST returns; `pollMs` has a 250 ms floor and `timeoutMs` a
252
+ 120 s ceiling. The relay gate also reserves the settlement margin, so `sellWatch` can still report its own-wallet
253
+ `claim-open` while `claimViaRelay` has already stopped. A refunded escrow is `claim-window` with
254
+ `reason: "escrow-refunded"`, not a request to claim; recovery is the next step.
223
255
 
224
256
  `actions.claim` is unchanged: it still sends only from the claimer's own wallet, because the half is revealed by
225
257
  whoever sends the claim.
@@ -301,10 +333,11 @@ receipt, a receipt without `OrderCreated`, or an event from another factory is `
301
333
  hash, and `swaps.start` does not save an escrow or retire a recovery number in that state.
302
334
 
303
335
  The predicted escrow and its salt are written to the pending record before the funding transaction is sent. A retry
304
- after a late receipt or a process restart finds that record by quote id or salt and reads the same transaction; it
305
- does not build a second side or send a second deposit. An explicit wallet rejection clears the pending mark so the
306
- person can sign again. A transaction that was already mined is stopped by the escrow state guard; one still in the
307
- mempool can make the resend revert and cost gas, but cannot create a second deposit.
336
+ after a late receipt or a process restart finds that record by the salt, the chain, the factory and the predicted
337
+ escrow, and reads the same transaction; it does not build a second side or send a second deposit. An explicit wallet
338
+ rejection clears the pending mark so the person can sign again. A transaction that was already mined is stopped by
339
+ the escrow state guard; one still in the mempool can make the resend revert and cost gas, but cannot create a second
340
+ deposit.
308
341
 
309
342
  The wallet adapter accepts the standard Monero network names (`mainnet`, `stagenet`, `testnet`, `fakechain`) and
310
343
  still checks the address shape, so a mainnet withdrawal is not refused because the demo registry lists only
@@ -6,7 +6,7 @@ It is generated from the installed production tree; do not edit it by hand.
6
6
  Generated by `tools/third-party-notices.mjs`. Licences accepted by the project are listed in
7
7
  [LICENSE-POLICY.md](LICENSE-POLICY.md).
8
8
 
9
- ## @hpke/chacha20poly1305 1.8.0
9
+ ## @hpke/chacha20poly1305 1.8.1
10
10
 
11
11
  License: MIT
12
12
  Source: git+https://github.com/dajiaji/hpke-js.git
@@ -17,6 +17,8 @@ Source: git+https://github.com/dajiaji/hpke-js.git
17
17
  MIT License
18
18
 
19
19
  Copyright (c) 2023 Ajitomi Daisuke
20
+ Copyright (c) 2022 Paul Miller (https://paulmillr.com)
21
+ Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
20
22
 
21
23
  Permission is hereby granted, free of charge, to any person obtaining a copy
22
24
  of this software and associated documentation files (the "Software"), to deal
@@ -37,7 +39,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
37
39
  SOFTWARE.
38
40
  ```
39
41
 
40
- ## @hpke/common 1.10.1, 1.11.0
42
+ ## @hpke/common 1.13.0
41
43
 
42
44
  License: MIT
43
45
  Source: git+https://github.com/dajiaji/hpke-js.git
@@ -68,7 +70,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
68
70
  SOFTWARE.
69
71
  ```
70
72
 
71
- ## @hpke/core 1.10.0
73
+ ## @hpke/core 1.10.1
72
74
 
73
75
  License: MIT
74
76
  Source: git+https://github.com/dajiaji/hpke-js.git
@@ -99,7 +101,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
99
101
  SOFTWARE.
100
102
  ```
101
103
 
102
- ## @hpke/dhkem-x25519 1.8.0
104
+ ## @hpke/dhkem-x25519 1.8.1
103
105
 
104
106
  License: MIT
105
107
  Source: git+https://github.com/dajiaji/hpke-js.git
@@ -110,6 +112,7 @@ Source: git+https://github.com/dajiaji/hpke-js.git
110
112
  MIT License
111
113
 
112
114
  Copyright (c) 2023 Ajitomi Daisuke
115
+ Copyright (c) 2022 Paul Miller (https://paulmillr.com)
113
116
 
114
117
  Permission is hereby granted, free of charge, to any person obtaining a copy
115
118
  of this software and associated documentation files (the "Software"), to deal
@@ -3,7 +3,7 @@
3
3
  "note": "Pinned browser bundles. A change to one of these files must be accompanied by a matching SHA-256 here and a rebuild of the page's asset registry.",
4
4
  "bundles": {
5
5
  "sdk/sdk-browser.js": {
6
- "sha256": "61b3a75c36457b4485144be3c328c00938d1c164b9f2bd3a1c28207d9af7d681",
6
+ "sha256": "e9c934b0d5e6a164ea959e780e447485361913f91e7e5bcb475147b6cc657d8f",
7
7
  "source": "sdk/src (facade, adapters, recovery)"
8
8
  }
9
9
  }