@kassealhq/sdk 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to `@kassealhq/sdk`. The versioning rules are in [STABILITY.md](STABILITY.md).
 
+## 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).
@@ -153,17 +155,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

@@ -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

@@ -25,7 +25,8 @@ Changes to these happen only in a minor release, listed in the CHANGELOG:
 - **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`.
+- **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