@ninsei-labs/sdk 0.39.0 → 0.39.2

package/CHANGELOG.md

@@ -1,3 +1,118 @@
+## Unreleased — 2026-10-08
+
+EVERY ORDER'S ESCROW IS A CLONE, AND THE CLIENT NOW CHECKS THE IMPLEMENTATION IT WILL EXECUTE (issue #114).
+Since the contract change an order's escrow is an EIP-1167 minimal proxy of ONE shared implementation, and the
+factory carries the pair (`implementation()`, `implementationCodeHash()`). The factory checks that pair before every
+creation; the client now checks the SAME pair on chain, armed by the interface's own policy - `knownImplementationCodes`,
+an array of known implementation build hashes, sitting next to `knownFactoryCodes`. The verdict reads the pair off the
+factory, reads the CODE at the implementation's address and applies the same check the factory does - and re-hashes the
+live code, so it does not trust the factory's own answer alone. A `delegatecall` to an address without code SUCCEEDS,
+so a clone without an implementation would take the ETH and its `markReady`/`claim`/`refund` would appear to go through
+while doing nothing: that case is refused by name (`implementation-has-no-code`).
+
+- **`knownImplementationCodes`** (`src/quotes.mjs`, `src/index.mjs`, `index.d.ts`) - the interface's
+  escrow-implementation policy, next to `knownFactoryCodes`. An empty/absent list means "no policy": the pair is not
+  read and behaviour is as before (needed while a network still runs a factory of the OLDER build, which has no such
+  getters and answers a revert - the deployed one does). A non-empty list refuses an implementation whose recorded
+  hash is not a known build with `quote-factory-code-unknown`; a pair that cannot be read at all is refused with
+  `quote-factory-unchecked`. Proven by four cases beside the existing factory-code ones: a known build is accepted,
+  and a foreign one, a code whose hash does not match the recorded one, and an implementation without code are each
+  refused by a named reason.
+- **`verifyFactoryImplementationOnChain`** (`engine/evm/factory.js`) - one place that reads the pair and applies
+  `verifyFactoryImplementation`, with the chain injected (`read` = `eth_call`, `code` = `eth_getCode`). The module
+  stays pure (no imports, no network) and is the same helper the demo's node and watchtower call with their own reads.
+- **The package source is re-synced from the source-of-truth tree**: `src/**`, `engine/**` and `index.d.ts` are
+  byte-for-byte the demo repository's `sdk/`. The demo's interface config pins the known implementation hash - a
+  protocol constant, because the implementation has no immutable fields, so its runtime code (and its hash) is the
+  same on every network.
+- **Claim and order-creation gas limits are the MEASURED ones** (`engine/evm/claimGas.js`, `engine/evm/funding.js`).
+  `CLAIM_GAS_LIMIT` is raised from 120 000 to 200 000: an honest `claim` whose fee is the FIRST credit to the
+  recipient's cashier costs 120 721 gas on a live chain (124 072 in `forge --gas-report`), so the former limit cut a
+  valid claim. `GAS_CREATE_ORDER_AND_FUND` is lowered from 1 500 000 to 700 000, because an order's escrow is now an
+  EIP-1167 clone - the measured full call is 315 530 gas (1 190 683 for the former full contract). The dead
+  `GAS_CREATE_ORDER` constant (there is no separate creation path) is removed. The node's own claim in the
+  source-of-truth tree signs with the SAME shared limit instead of its own literal.
+- Checks: `node tools/check.mjs` - all green.
+
+## 0.39.2 — 2026-10-08
+
+`fakechain` IS A KNOWN MONERO NETWORK. The withdrawal page takes the Monero network FROM THE NODE, and monerod in
+regtest mode reports its network as `fakechain` - the official name of that mode. On the CI contour (a regtest node)
+the core therefore refused its OWN recovery file (`bad-input`, field `xmrNetwork`) and the withdrawal never started.
+The name is now accepted by every check of the network value, and everything else is still refused by name.
+
+- **`fakechain` joins the accepted networks** (`src/config.mjs`, `index.d.ts`): beside the engine registry's own
+  names and the standard mainnet/stagenet/testnet it is a KNOWN name of the regtest mode. Anything else is still a
+  `bad-input` refusal that names the known list - the value is checked, not "any word accepted".
+- **The recovery-file reader accepts it as well** (`engine/recovery/recoveryFile.js`): a file whose wallet network is
+  `fakechain` reads back; an unknown name is still rejected. Proven by a writer -> reader round trip, with the
+  unknown-name case beside it.
+- **The engine's network registry declares it** (`engine/core/config.js`): the Monero wallet adapter builds its list
+  of known networks from `XMR_NETWORKS`, so `/adapters` knows the name too.
+- **The package source is re-synced from the source-of-truth tree**: `src/**`, `engine/**` and `index.d.ts` are now
+  byte-for-byte the demo repository's `sdk/`. Besides the change above this also carries two changes that were
+  already in that tree: the escrow-implementation address/codehash read and verdict (`engine/evm/factory.js`,
+  `verifyFactoryImplementation`) and the smallest-trade rule that reads the maker's SENT minimum rather than the
+  effective set's first level (`src/levelsWalkSpec.mjs`, the `minAtomic` argument).
+- **A withdrawal no longer loses its refusal code on a chain the wallet library cannot scan** (`src/sweep.mjs`):
+  the FREE REMAINDER is read and judged BEFORE any input selection, and a failed `sync()` no longer pre-empts that
+  verdict. On the CI contour (a regtest node) monero-ts `sync()` throws a bare `failed to get hashes`; that error
+  used to escape ahead of the funds check, so an EMPTY wallet was refused with `code: null` + raw text instead of
+  the named `insufficient-funds` - and the page had no phrase to translate, because the core had named nothing.
+- **Every refusal keeps a code from the package's dictionary** (`src/sweep.mjs`, `walletStep`): a wallet step that
+  fails with anything other than an `SdkError` is re-thrown as one, on `wallet-rejected`, with the library's own
+  message kept as `params.why`. `code: null` + raw text is not a refusal an interface can show or a check assert.
+- Proven by a unit run WITHOUT a browser or a contour (the source-of-truth tree's `tools/check-sweep-empty-wallet.mjs`,
+  part of the fast gates): a zero remainder refuses with `insufficient-funds` and human words while input selection
+  is never touched; a non-zero remainder reaches signing; a low-level library failure comes out WITH a code. Two
+  breaking runs redden - cutting the remainder check (the refusal stops being named) and cutting the wrapper (the
+  run then reproduces the exact CI symptom: `code: null` + `failed to get hashes`).
+- Checks: `node tools/check.mjs` - all green.
+
+ HEAD
+## Unreleased — 2026-10-07
+
+PRERELEASES GET THEIR OWN npm TAGS, AND `latest` STOPS MOVING BY ACCIDENT. The release workflow published whatever
+version `package.json` carried under whatever tag npm chose on its own; now the tag is DERIVED from the version and
+handed to `npm publish` by name. This entry rides the next version - nothing in `src/`, `engine/` or `index.d.ts`
+changes here.
+
+- **The tag comes from the version** (`tools/npm-tag.mjs`): `X.Y.Z` -> `latest`, `X.Y.Z-develop.N` -> `develop`,
+  `X.Y.Z-preview.N` -> `preview`, read from the FIRST identifier of the prerelease part. Anything else is a named
+  refusal, not a guess: a version that is not `X.Y.Z[...]`, a prerelease channel that is not declared, a tag that
+  reads as a version.
+- **A prerelease can never move `latest`.** The publish step works the tag out before it sends anything, and the
+  derivation refuses, naming the case, when a prerelease would take `latest` - even under a manual override. The
+  reverse is refused too: a plain version does not publish into a channel tag with no decision behind it.
+- **The tag is passed explicitly.** "Publishing a package sets the `latest` tag to the published version unless
+  the `--tag` option is used" (https://docs.npmjs.com/cli/v11/commands/npm-dist-tag), and the `tag` config defaults
+  to `latest` (https://docs.npmjs.com/cli/v11/using-npm/config#tag) - so the step now ends in
+  `npm publish --access public --provenance --tag <tag>` and never leans on that default.
+- **A manual run may override the tag** with the new `tag` input; the step echoes the override and the tag the
+  derivation would have produced into the log before the publish, so the decision is readable, not silent.
+- **The cycle is written down** (README, "Releases and prereleases"): a build for ourselves is a prerelease under
+  `develop`/`preview`, the demo pins the EXACT version, and a release is a separate decision - a plain version, the
+  only shape that moves `latest`.
+- **Proven locally:** `node tools/npm-tag.test.mjs` walks the table - plain, both channels, build metadata, an
+  undeclared channel, garbage, every override - 28 cases, all green. A breaking run that cuts the guard reddens 5
+  of those 28, exactly the tooth's own cases, and `tools/npm-tag.mjs` was restored byte for byte. `node
+  tools/check.mjs` stays green, and CI gained the same case table as its own named step.
+
+## 0.39.1 — 2026-10-07
+
+THE FIRST RELEASE CUT BY THE TAG-TRIGGERED WORKFLOW. The package's contents did not change: this entry and the
+version field are the whole difference from 0.39.0, and the release exists to publish once through the
+trusted-publisher setup on npm.
+
+- **Why a release at all.** npm's trusted-publisher link for `@ninsei-labs/sdk` (GitHub Actions, repository `sdk`,
+  workflow `release.yml`) reads "Pending validation" and only becomes active after one publish goes through that
+  workflow. This is that publish.
+- **Nothing in the package moved.** `src/**`, `engine/**` and `index.d.ts` are the same sources as 0.39.0; the only
+  edits are `package.json` (0.39.0 to 0.39.1) and this entry. The dependencies are unchanged, so `pnpm-lock.yaml` is
+  untouched.
+- Checks: `node tools/check.mjs` - all 7 green (syntax, import, surface, mirror, language, pack, secrets).
+
+
 ## 0.39.0 — 2026-10-07
 
 THE PACKAGE IS LEVEL WITH THE MAIN REPOSITORY AGAIN. The `sdk/src` and `sdk/engine` trees were re-synced

package/README.md

@@ -185,3 +185,24 @@ trigger where those exist; on another VM they simply do not appear, rather than
    touch them: `atomic/order-worker.js`, the Monero bundles.
 6. **Strict CSP.** The package is designed for a policy without `eval` and inline.
 7. **Zero dependencies.**
+
+## Releases and prereleases
+
+Every published version rides on an npm dist-tag, and the tag is **derived from the version** - never left to
+npm's default:
+
+| Version | npm dist-tag | What it is |
+|---|---|---|
+| `X.Y.Z` | `latest` | a release - a separate decision, and the only thing that moves `latest` |
+| `X.Y.Z-develop.N` | `develop` | a build for ourselves |
+| `X.Y.Z-preview.N` | `preview` | a build to show |
+
+The loop this serves: build a version for yourself (`0.40.0-develop.1`), publish it under `develop`, and have the
+demo pin the **exact** version (`"@ninsei-labs/sdk": "0.40.0-develop.1"`) rather than a tag. `latest` does not
+move, so `npm install @ninsei-labs/sdk` keeps serving the last real release. Shipping a release is then its own
+decision: a plain `X.Y.Z`, the only shape that publishes under `latest`.
+
+The tag is passed to `npm publish` explicitly (`--tag <tag>`), and `tools/npm-tag.mjs` refuses the two ways this
+can go wrong **by name** - a prerelease that would take `latest`, and a plain version that would slide into a
+channel someone else owns. A manual run of the release workflow may override the tag with an input; when it does,
+the log says so. The derivation and its refusals are covered by `node tools/npm-tag.test.mjs`.