@kassealhq/sdk 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,72 @@
 
 All notable changes to `@kassealhq/sdk`. The versioning rules are in [STABILITY.md](STABILITY.md).
 
+## 0.3.0
+
+**The creator window (new contract builds)**
+
+- New launch builds `v1-kasseal-mainnet-3` (mainnet) and `v1-kasseal-mainnet-3-tn10` (testnet-10). Their curve's `buy`
+  has the creator window: on a curve nothing has traded on, only a buy funded by the token's creator is valid until
+  the curve is 200 DAA (about 20 seconds) old. The creator's own first buy is therefore always first; after the first
+  trade, buys are unrestricted. The pool program is the same file as in the earlier builds, byte for byte.
+- Both builds of each network are bundled: tokens launched before keep trading on `v1-kasseal-mainnet-2` and
+  `v1-kasseal-mainnet-2-tn10`. The builders recognise a token's build from its curve or pool program, as before.
+- `buildBuy` sets the curve input's sequence to `CREATOR_WINDOW_DAA` (200) when the window applies to the buyer
+  (`curveBuySequence`; the creator, read from the first funding input, needs none). A buy submitted inside the window
+  is refused by the node and can be sent again once the window has passed.
+
+**API**
+
+- `BUILD_OF_NETWORK` now names each network's launch build (`v1-kasseal-mainnet-3`, `v1-kasseal-mainnet-3-tn10`).
+  New `BUILDS_OF_NETWORK` lists every build of a network, launch build first; `SUPPORTED_BUILDS` lists all four.
+- `createContext(preset, network, 'v1', build)` accepts either build of the network; the default is the launch build.
+  `createTxBuilder` accepts contexts of either.
+- New exports: `CREATOR_WINDOW_DAA`, `hasCreatorWindow`, `curveBuySequence`, `fundedByCreator`,
+  `V1_CREATOR_WINDOW_REVISION`, `V1_CREATOR_WINDOW_TWIN_REVISION`.
+- The per-network browser entries load both builds of their network and add `WEB_BUILDS`; `WEB_BUILD` is the launch
+  build.
+
+**What to do**
+
+- Code that compared `BUILD_OF_NETWORK` or `WEB_BUILD` with a token's build: use `BUILDS_OF_NETWORK` / `WEB_BUILDS`.
+- Code that builds its own curve buys without `buildBuy`: set the curve input's sequence as `curveBuySequence` returns.
+
+## 0.2.0
+
+**Entry points**
+
+- New per-network browser entries, `@kassealhq/sdk/web/mainnet` and `@kassealhq/sdk/web/testnet-10`. Each has the
+  same exports as `@kassealhq/sdk/web`, plus `WEB_NETWORK` and `WEB_BUILD`, and its import graph reaches only its own
+  network's contract artifact chunks. A bundler or extension packager that ships every file reachable by import now
+  ships one build (about 3.9 MB reachable from the entry, Kaspa `kaspa.js` included, WASM not) instead of both
+  (about 6.8 MB). Their `initWeb` takes the network as optional and refuses any other one (`UNSUPPORTED_NETWORK`).
+- `@kassealhq/sdk/web` is unchanged: same exports, same behaviour, still able to load either network. All web entries
+  share one state, so a page still runs one Kaspa SDK and one network.
+- No change to the contract builds, their artifacts, the builders or the Node and root entries.
+
+**Smaller browser artifacts**
+
+- Each curve preset chunk of `@kassealhq/sdk/web` is now a patch against one curve template
+  per build, 0.3 to 1.8 KB instead of about 42 KB (web artifact chunks of both builds: 5.8 MB to 0.42 MB). The SDK
+  rebuilds the exact artifact files from template and patch and checks them against the same pinned SHA-256 digests
+  as before. The contract builds, their files under `dist/artifacts/`, the manifest, the Node entry and the API are
+  unchanged. See [docs/contract-artifacts.md](docs/contract-artifacts.md#how-the-browser-build-stores-the-curve-programs).
+
+**Your own Kaspa SDK**
+
+- `initWeb` takes an optional `kaspa: { module, wasm?, sha256? }`: your own rusty-kaspa v2.1.0 web build (its bindings
+  module and WASM) instead of the bundled one, for apps such as wallets that already ship it. It is installed only
+  after it reports 2.1.0, exposes the API the builders use and passes a known-answer test against the pinned build
+  (transactions with a genesis group and covenant bindings, txids, serialisation, sighashes, signatures with a public
+  test key, finalize); `sha256`, when given, is checked against your WASM bytes first. A refusal is the new
+  `SdkCompatibilityError` (`SDK_INCOMPATIBLE`) and installs nothing. Without the option `initWeb` is unchanged.
+- New exports: `SdkCompatibilityError`; types `KaspaSdkOption` and `WasmSource` (web entries).
+- New lite browser entries for apps that ship their own Kaspa SDK, `@kassealhq/sdk/web-lite/mainnet` and
+  `@kassealhq/sdk/web-lite/testnet-10`: the API of the per-network entry without the bundled Kaspa SDK (no
+  `webWasmUrl`, `WEB_WASM_SHA256`, `WEB_JS_SHA256`). Their import graph reaches neither `kaspa.js` nor
+  `kaspa_bg.wasm`: about 0.65 MB in all, instead of about 1.2 MB of JavaScript plus the 11.5 MB WASM. Their `initWeb`
+  requires the `kaspa` option.
+
 ## 0.1.1
 
 Kasseal is live on Kaspa mainnet.

package/README.md

@@ -34,6 +34,8 @@ ESM only. Node 22 or later, or any modern browser through a bundler. No runtime
 | `@kassealhq/sdk` | Pure logic: quotes, slippage, state codecs, launch-proof format, API types | None |
 | `@kassealhq/sdk/node` | Everything, in Node: builders, signing, launch-proof verification | Loads the pinned Kaspa WASM SDK and the contract artifacts, each checked against its SHA-256 first |
 | `@kassealhq/sdk/web` | Everything, in the browser | None until you call `initWeb`, which checks the WASM and the artifacts the same way |
+| `@kassealhq/sdk/web/mainnet` | The same as `/web`, for mainnet only: bundles only the mainnet contract build | As `/web` |
+| `@kassealhq/sdk/web/testnet-10` | The same as `/web`, for testnet-10 only: bundles only the testnet-10 contract build | As `/web` |
 
 The SDK bundles rusty-kaspa's WASM SDK v2.1.0 and the compiled Kasseal contracts. Both are checked against pinned
 SHA-256 hashes when they load. On any difference the SDK refuses to start (it fails closed).
@@ -113,13 +115,23 @@ The complete program, with the safe retry, is [examples/pool-buy.ts](examples/po
 
 ## Networks
 
-| Network | Network id | API base URL | Contract build | Status |
+| Network | Network id | API base URL | Contract builds | Status |
 |---|---|---|---|---|
-| Kaspa mainnet | `mainnet` | `https://app.kasseal.com/v1` | `v1-kasseal-mainnet-2` | Live |
-| Kaspa testnet-10 | `testnet-10` | `https://testnet.kasseal.com/v1` | `v1-kasseal-mainnet-2-tn10` | Live |
+| Kaspa mainnet | `mainnet` | `https://app.kasseal.com/v1` | `v1-kasseal-mainnet-3` (new launches), `v1-kasseal-mainnet-2` | Live |
+| Kaspa testnet-10 | `testnet-10` | `https://testnet.kasseal.com/v1` | `v1-kasseal-mainnet-3-tn10` (new launches), `v1-kasseal-mainnet-2-tn10` | Live |
 
-The testnet build mirrors the mainnet build: the same contract sources, with Kasseal's testnet wallet as the fee
-recipient. Template hashes for both are in [docs/contract-artifacts.md](docs/contract-artifacts.md).
+A token keeps the build it was launched on, and the SDK trades both: it recognises a token's build from its curve or
+pool program. The two builds share one pool program; the newer curve adds the creator window (below). Each testnet
+build mirrors its mainnet build: the same contract sources, with Kasseal's testnet wallet as the fee recipient.
+
+### The creator window
+
+On a curve of `v1-kasseal-mainnet-3` that nothing has traded on yet, only a buy funded by the token's creator (the
+transaction's first funding input pays from the creator's key) is valid until the curve is 200 DAA (about 20 seconds)
+old. Anyone else's first buy must carry that age on its curve input, and the network holds it back until then. Once
+anything has traded, buys are unrestricted. The builders do this for you: `buildBuy` sets the curve input's sequence
+to `CREATOR_WINDOW_DAA` when the window applies (`curveBuySequence`); a submit inside the window is refused by the
+node and can be sent again once the window has passed. `hasCreatorWindow(ctx.curve)` tells whether a curve has it. Template hashes for both are in [docs/contract-artifacts.md](docs/contract-artifacts.md).
 
 ## What a trade costs
 
@@ -153,17 +165,71 @@ await ensurePresetArtifacts('standard-k180');       // a curve preset's artifact
 
 `initWeb` fetches the WASM from `webWasmUrl()` (a URL next to `web.js`) unless you pass `wasm` yourself (bytes, a
 URL or a `Response`); the bytes are hashed against the pinned digest before they are instantiated. Contract
-artifacts are code-split per curve preset; pass `preload: 'all'` to load every preset up front. If your bundler
+artifacts are code-split per curve preset (a preset chunk is under 2 KB: a patch against one shared curve template per
+build, rebuilt to the exact files and checked against their pinned SHA-256); pass `preload: 'all'` to load every
+preset up front. If your bundler
 pre-bundles dependencies (for example Vite's `optimizeDeps`), exclude this package so the WASM URL stays next to
 the module, or pass `wasm` explicitly.
 
+`@kassealhq/sdk/web` can load either network, so its import graph names the artifact chunks of both contract builds
+(about 2.9 MB each). A browser extension or any packager that ships every file reachable by import ends up with
+both. If your app serves one network, import its own entry instead: it has the same exports as `/web` plus
+`WEB_NETWORK` and `WEB_BUILD`, and its import graph reaches only that network's chunks.
+
+```js
+import { initWeb, ensurePresetArtifacts } from '@kassealhq/sdk/web/mainnet';   // or '@kassealhq/sdk/web/testnet-10'
+
+await initWeb();                                     // network optional; any other network is refused (UNSUPPORTED_NETWORK)
+await ensurePresetArtifacts('standard');
+```
+
+All web entries share one state: a page runs one Kaspa SDK and one network, whichever entry starts it.
+
+**Your own Kaspa SDK build.** An app that already ships rusty-kaspa v2.1.0 (web target) can pass its own build instead
+of the bundled one:
+
+```js
+import * as kaspa from './vendor/kaspa/kaspa.js';  // your bindings module (its default export is the WASM init)
+
+await initWeb({
+  network: 'mainnet',
+  kaspa: {
+    module: kaspa,
+    wasm: new URL('./vendor/kaspa/kaspa_bg.wasm', import.meta.url), // or bytes / a Response; omit if already initialised
+    sha256: '…',                                                     // optional: your WASM's own digest
+  },
+});
+```
+
+Before it is installed, your build must report version 2.1.0, expose every function the builders call, and pass a
+known-answer test: a fixed set of transactions (a P2PK transfer with payload and change; a covenant spend with a bound
+continuation, a two-output genesis group and a lock time; P2PK and P2SH scripts and addresses on both networks) is
+built, serialised, signed with a public test key and finalized through the SDK's own code paths, and every txid,
+serialised transaction, sighash and covenant id must equal, byte for byte, what the pinned build produced. Signatures
+are randomised by the Kaspa SDK, so they are checked by verifying them against the SDK's own sighash and the key.
+Any difference rejects with `SdkCompatibilityError` (`SDK_INCOMPATIBLE`, with `stage` and every `failures` line) and
+nothing is installed; a `sha256` that does not match your bytes rejects with `SdkIntegrityError`. Leave out the
+top-level `wasm` when you pass `kaspa`. Without `kaspa`, `initWeb` behaves exactly as before.
+
+To leave the bundled Kaspa SDK out of your package altogether, import the lite entry of your network: the same API
+without the bundled SDK, so neither `kaspa.js` nor the 11.5 MB `kaspa_bg.wasm` is reachable from it.
+
+```js
+import * as kaspa from './vendor/kaspa/kaspa.js';
+import { initWeb } from '@kassealhq/sdk/web-lite/mainnet';     // or '@kassealhq/sdk/web-lite/testnet-10'
+
+await initWeb({ kaspa: { module: kaspa, wasm: new URL('./vendor/kaspa/kaspa_bg.wasm', import.meta.url) } });
+```
+
 ## Integrity
 
 - Contract artifacts: only the two builds above are bundled. `dist/artifacts/manifest.json` lists each build's
   template hashes and the SHA-256 of every file; the same manifest is compiled into the code, and every file is
   checked before use. A missing, altered or unlisted file is refused (`ArtifactIntegrityError`).
 - Kaspa WASM SDK: rusty-kaspa v2.1.0, unmodified. The Node build is hashed before it is loaded; the web WASM is
-  hashed before it is instantiated (`SdkIntegrityError`).
+  hashed before it is instantiated (`SdkIntegrityError`). A Kaspa SDK you pass to `initWeb` yourself (`kaspa` option)
+  is not held to the pinned hash: it is checked against your own `sha256` if you give one, and must pass the
+  known-answer test against the pinned build before it is used (`SdkCompatibilityError`).
 
 ## Errors
 

package/SECURITY.md

@@ -10,7 +10,7 @@ open a public issue, post on social media or discuss it in a public channel unti
 
 Please include:
 
-- what is affected: the SDK version, the contract build (`v1-kasseal-mainnet-2` or `v1-kasseal-mainnet-2-tn10`), the
+- what is affected: the SDK version, the contract build (`v1-kasseal-mainnet-3`, `v1-kasseal-mainnet-2` or a testnet-10 build), the
   API route, or the app page;
 - the steps to reproduce, or a proof of concept (testnet-10 only);
 - the impact as you understand it: whose funds, how much, under what conditions;
@@ -52,7 +52,9 @@ compromised user device or key.
   did not sign for it.
 - A way to make the SDK build, or ask a user to sign, a transaction other than the one it showed.
 - A way to make the launch-proof verifier report `bound` for a token, curve or pool that is not genuine.
-- A way to make the SDK accept artifacts or a WASM build that do not match their pinned hashes.
+- A way to make the SDK accept artifacts or a WASM build that do not match their pinned hashes, or a Kaspa SDK passed
+  to `initWeb` (`kaspa` option) that builds, serialises or signs differently from the pinned build and still passes
+  the known-answer test.
 
 ## Supported versions
 

package/STABILITY.md

@@ -23,9 +23,10 @@ Changes to these happen only in a minor release, listed in the CHANGELOG:
 - **Error codes**: the `code` string of every error class in [docs/errors.md](docs/errors.md). A code is never reused
   for a different meaning.
 - **The launch-proof verdicts**: `bound`, `unverified`, `invalid`, `malformed`, and what each means.
-- **The bundled contract builds**: `v1-kasseal-mainnet-2` and `v1-kasseal-mainnet-2-tn10`, their artifacts and
-  their hashes. A new contract build is added in a minor release; a bundled build is never modified.
-- **Entry points**: `@kassealhq/sdk`, `@kassealhq/sdk/node`, `@kassealhq/sdk/web`.
+- **The bundled contract builds**: `v1-kasseal-mainnet-3`, `v1-kasseal-mainnet-2` and their testnet-10 builds
+  `v1-kasseal-mainnet-3-tn10`, `v1-kasseal-mainnet-2-tn10`, their artifacts and their hashes. A new contract build is added in a minor release; a bundled build is never modified.
+- **Entry points**: `@kassealhq/sdk`, `@kassealhq/sdk/node`, `@kassealhq/sdk/web`, `@kassealhq/sdk/web/mainnet`,
+  `@kassealhq/sdk/web/testnet-10`, `@kassealhq/sdk/web-lite/mainnet`, `@kassealhq/sdk/web-lite/testnet-10`.
 
 ## What may change in a minor release
 

package/dist/artifacts/contracts/curve/v1/artifacts/v1-kasseal-mainnet-3/curve.ctor.standard-k103.json

@@ -0,0 +1,251 @@
+[
+ {
+  "kind": "bytes",
+  "value": [
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0,
+   0
+  ]
+ },
+ {
+  "kind": "int",
+  "value": 0
+ },
+ {
+  "kind": "int",
+  "value": 0
+ },
+ {
+  "kind": "byte",
+  "value": 0
+ },
+ {
+  "kind": "int",
+  "value": 8240000
+ },
+ {
+  "kind": "int",
+  "value": 103
+ },
+ {
+  "kind": "int",
+  "value": 1000
+ },
+ {
+  "kind": "int",
+  "value": 800000
+ },
+ {
+  "kind": "int",
+  "value": 400000000
+ },
+ {
+  "kind": "int",
+  "value": 100
+ },
+ {
+  "kind": "bytes",
+  "value": [
+   0,
+   0,
+   32,
+   214,
+   240,
+   158,
+   13,
+   162,
+   15,
+   104,
+   158,
+   59,
+   17,
+   144,
+   5,
+   147,
+   254,
+   205,
+   236,
+   220,
+   136,
+   237,
+   129,
+   240,
+   19,
+   3,
+   28,
+   116,
+   155,
+   222,
+   146,
+   217,
+   40,
+   229,
+   116,
+   172
+  ]
+ },
+ {
+  "kind": "bytes",
+  "value": [
+   0,
+   0,
+   32,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   34,
+   172
+  ]
+ },
+ {
+  "kind": "bytes",
+  "value": [
+   151,
+   3,
+   17,
+   46,
+   230,
+   227,
+   85,
+   81,
+   7,
+   205,
+   22,
+   136,
+   88,
+   153,
+   43,
+   119,
+   211,
+   183,
+   79,
+   101,
+   82,
+   5,
+   178,
+   180,
+   99,
+   177,
+   249,
+   236,
+   46,
+   199,
+   60,
+   247
+  ]
+ },
+ {
+  "kind": "int",
+  "value": 1
+ },
+ {
+  "kind": "int",
+  "value": 3885
+ },
+ {
+  "kind": "bytes",
+  "value": [
+   146,
+   172,
+   215,
+   97,
+   80,
+   78,
+   79,
+   160,
+   90,
+   207,
+   112,
+   103,
+   94,
+   241,
+   174,
+   160,
+   198,
+   110,
+   250,
+   33,
+   38,
+   236,
+   92,
+   114,
+   110,
+   71,
+   121,
+   184,
+   174,
+   240,
+   84,
+   224
+  ]
+ },
+ {
+  "kind": "int",
+  "value": 1000000000
+ },
+ {
+  "kind": "int",
+  "value": 0
+ },
+ {
+  "kind": "int",
+  "value": 8000
+ }
+]