@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.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,13 @@
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
+
1
11
  ## 0.59.0 — 2026-11-11
2
12
 
3
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.
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.59.0)
25
+ ## State (0.60.0)
26
26
 
27
27
  | Surface | State |
28
28
  |---|---|
@@ -34,7 +34,7 @@ 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
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 |
@@ -210,29 +210,49 @@ signed by the client:
210
210
 
211
211
  ```js
212
212
  const sell = await sdk.swaps.startSell({ offer });
213
+ const relaySender = offer.claimSender; // GET /v1/relay; the relay origin that answered
213
214
  const claimed = await sdk.swaps.claimViaRelay({ id: sell.id,
214
- claimSenders: [relaySender, ...otherListedMakers] });
215
+ claimSenders: [...(relaySender ? [relaySender] : []), ...otherListedMakers] });
215
216
  if (claimed.state === "claimed") {
216
217
  claimed.txid; // the claim transaction, or null when the escrow itself showed claimed
217
218
  claimed.from; // the sender node's claim sender
218
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
219
222
  } else {
220
223
  claimed.secondsLeft; // no sender landed it: claim yourself before t1
221
224
  }
222
225
  ```
223
226
 
224
- `claimSenders` is the client's ordered list: the relay's own sender first, then other listed makers. The SDK tries
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
225
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
226
231
  escrow until it says `claimed` or the slot ends. The deal's maker and its quote-key owner are refused before the
227
232
  half leaves the client. When the list is exhausted the result is `state: "claim-yourself"` with `t1` and
228
233
  `secondsLeft`. The old scalar `claimSender` remains a one-element fallback for callers written before the list.
229
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
+
230
242
  `claimViaRelay` reads the sell record made by `startSell` and requires a positive `claimTip`, the escrow and the
231
243
  half. It posts to the relay origin stored with the record; an optional `relayUrl` may repeat that origin but a
232
244
  different one is refused. A node refusal keeps its code under `quote-refused.params.code`. A timeout or a body
233
245
  without a real transaction hash is `claim-unknown`: the claim may have been sent, so the SDK reads the escrow and
234
246
  moves on only after the slot. Only an escrow that reads `claimed` is success.
235
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.
255
+
236
256
  `actions.claim` is unchanged: it still sends only from the claimer's own wallet, because the half is revealed by
237
257
  whoever sends the claim.
238
258
 
@@ -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": "563587be187b41651725d0192234b0341ad6d183f23c7e3aac92487360f44a6e",
6
+ "sha256": "e9c934b0d5e6a164ea959e780e447485361913f91e7e5bcb475147b6cc657d8f",
7
7
  "source": "sdk/src (facade, adapters, recovery)"
8
8
  }
9
9
  }