@kaspacom/kcc20-tx-builder 0.2.5 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.4.0 (unreleased)
+
+- Add signerless snapshot deployment, start, claim, transfer, and verification builders with pinned contract artifacts and transaction tests.
+- Reject conflicting explicit native covenant IDs during transfer while retaining legacy alias resolution.
+- Preserve pre-authorized covenant witnesses and validate wallet signature encodings and sighash bytes.
+- Add 24 executable operation scenarios, a validated live-transfer source adapter, and tests run from extracted package contents.
+- Add integration and API guides, including amount examples, host-supplied WASM,
+  artifact loading, source transport, request schemas, signing, and errors.
+- Include guides, release instructions, and security reporting in the npm tarball.
+- Replace the README's host-specific bridge example with the exported engine API.
+- Document public npm registry overrides and replace obsolete first-release steps.
+
+The engine RPC adapter now supports frozen WASM exports from browser bundlers.
+
+### Public integration examples
+
+- Add runnable browser and Node deploy/transfer examples with WASM and offline fixtures.
+- Fix the engine RPC adapter for frozen WASM module exports produced by bundlers.
+- Verify packed-package browser/Node parity without external network requests.

package/README.md

@@ -7,7 +7,9 @@ frontend and the Node backend.
 ## Install
 
 ```sh
-npm install @kaspacom/kcc20-tx-builder
+npm install --save-exact @kaspacom/kcc20-tx-builder@0.4.0 \
+  --registry=https://registry.npmjs.org/ \
+  --@kaspacom:registry=https://registry.npmjs.org/
 ```
 
 The package provides ESM and CommonJS entry points and requires Node.js 20 or
@@ -16,6 +18,21 @@ Browser consumers must provide their already-loaded browser Kaspa WASM runtime;
 Node consumers provide their Node Kaspa WASM runtime. Kaspa WASM is deliberately
 not bundled or initialized by this package.
 
+## Documentation
+
+- [Integration guide](docs/INTEGRATION.md): amount calculations, engine setup,
+  artifacts, source providers, signing boundaries, and error handling.
+- [API guide](docs/API.md): public entry points and operation families.
+- [Independent indexing](https://github.com/KASPACOM/kaspa-covenants/blob/develop/docs/INDEPENDENT_INDEXING.md): self-hosted data boundaries and lightweight-indexer release gates. The lightweight indexer is not yet a live data source.
+- [Snapshot builders](docs/snapshot-start.md): signerless deployment, claims and verification; funded DEV rehearsal is still required.
+- [Release guide](RELEASING.md): publishing and consumer verification.
+
+Public npm installation does not require a GitHub token. The explicit scoped
+registry flag overrides project settings that route `@kaspacom` to GitHub Packages.
+This branch prepares `0.4.0` with expanded documentation and signerless snapshot
+builders. Pin the same exact version across wallet and server adapters. See
+[the changelog](CHANGELOG.md) for the release contents.
+
 ## Runtime boundary
 
 The package deliberately does not import Kaspa WASM, Angular, NestJS, Node
@@ -33,21 +50,35 @@ amount/fee calculations, and action-specific UTXO selection. It supports
 deploy, verify, mint, mint availability, transfer, native/wrapped
 consolidation, wrap, unwrap, wrapper-market deploy, create/fill/sweep/cancel
 orders, FeeTicket root/create/burn/transfer/update operations, and the
-deterministic matcher/operator transaction builders. Matcher/operator
+immutable bootstrap and controller deployments, signerless snapshot start,
+claims, recipient transfers, and deterministic matcher/operator transaction
+builders. Matcher/operator
 invocation, authorization, scheduling, and key custody remain backend-only;
 hosts must explicitly enable those builders with `allowBackendOnly`.
 
 The package ships the KCC20 contract artifacts under `artifacts/`, but the
 engine still accepts supplied artifacts and UTXO/RPC access and never reads
 files, environment variables, or WASM assets itself. Browser and backend hosts
-decide how to load package artifacts for their runtime. The frontend host can
-configure the bridge with its already-loaded runtime:
+decide how to load package artifacts for their runtime. The host can
+configure the exported engine with its already-loaded runtime:
 
 ```ts
-clientBuilder.configure({
+import { createKcc20PsktBuilderEngine } from "@kaspacom/kcc20-tx-builder";
+
+createKcc20PsktBuilderEngine({
   wasm: loadedKaspa,
-  artifactProvider: (key) =>
-    fetch(`/kcc20-artifacts/${key}`).then((response) => response.json()),
+  artifacts: {},
+  artifactProvider: async (key) => {
+    const response = await fetch(
+      `/kcc20-artifacts/${encodeURIComponent(key)}`,
+    );
+    if (!response.ok) throw new Error(`Cannot load artifact ${key}`);
+    const rawBytes = new Uint8Array(await response.arrayBuffer());
+    return {
+      artifact: JSON.parse(new TextDecoder().decode(rawBytes)),
+      rawBytes,
+    };
+  },
   sourceProvider: {
     getUtxosByAddresses: (request) =>
       applicationRpcConnection.getUtxosByAddresses(request),
@@ -59,6 +90,11 @@ The artifact and source providers are host policies. Private operator keys
 must never be embedded in this package; a trusted backend may inject one at
 runtime for an explicitly authorized operator build.
 
+Snapshot builds require the raw artifact bytes so the package can compare the
+file SHA-256 with the migration's frozen artifact pins before constructing a
+transaction. Returning only parsed JSON is intentionally insufficient for that
+check.
+
 When `sourceProvider` is present, its connection lifecycle belongs entirely to
 the host: the builder does not construct, connect, or disconnect an RPC client.
 This allows a browser application to reuse one reconnecting websocket across
@@ -85,7 +121,8 @@ import kcc20Artifact from "@kaspacom/kcc20-tx-builder/artifacts/KCC20.placeholde
 ```
 
 The published, hash-pinned set contains `KCC20`, `KCC20Wrapper`,
-`KCC20Orderbook`, `KCC20FeeTicket`, and `KCC20Vesting`. Consumers should not
+`KCC20Orderbook`, `KCC20FeeTicket`, `KCC20Vesting`,
+`KCC20SnapshotBootstrap`, and `KCC20SnapshotController`. Consumers should not
 vendor separate copies of these files.
 
 How JSON modules are loaded depends on the consuming runtime and bundler. A
@@ -102,3 +139,12 @@ backend secrets into this package in a browser.
 ## License
 
 Apache-2.0
+
+## Runnable transaction examples
+
+Start with the [frontend and backend examples](examples/README.md), then read
+the [transaction construction guide](docs/TRANSACTION_GUIDE.md) and
+[operation recipes](docs/RECIPES.md). Both applications construct transactions
+locally using packaged artifacts and host-supplied chain data.
+
+For independently retrieved holder state, see the [live transfer walkthrough](docs/LIVE_TRANSFER.md); all supported user operation families have [runnable offline recipes](docs/RECIPES.md).

package/RELEASING.md

@@ -0,0 +1,93 @@
+# Releasing
+
+The package is published under the same version to both registries:
+
+- npmjs (`https://registry.npmjs.org`) is the public distribution for general
+  consumers and the backend.
+- GitHub Packages (`https://npm.pkg.github.com`) supports KaspaCom projects
+  whose `.npmrc` maps the entire `@kaspacom` scope to GitHub Packages.
+
+Never publish different contents under the same version. npm package versions
+are immutable, so update `package.json` before each release.
+
+## Publishing setup
+
+The package is already public on npmjs at `0.2.5`. GitHub Releases trigger
+`.github/workflows/publish.yml`, which has independent npmjs and GitHub Packages
+jobs. Both jobs install dependencies, run tests, and require the release tag to
+match `v` plus the checked-out `package.json` version.
+
+npmjs uses trusted OIDC publishing with provenance on Node 24. Its trusted
+publisher identifies organization `KASPACOM`, repository `kcc20-tx-builder`,
+and workflow `publish.yml`, with no GitHub environment configured. GitHub
+Packages uses the workflow's short-lived `GITHUB_TOKEN` and `packages: write`.
+Do not add long-lived npm tokens or publish from an unreviewed checkout.
+
+## Prepare a release
+
+1. Start from reviewed `main` and update the version in a release PR.
+2. Run `npm ci`, `npm test`, and `npm pack --dry-run`.
+3. Inspect the tarball for compiled ESM/CommonJS entry points, declarations,
+   artifacts, documentation, and license. Check that no credentials or local
+   wallet files are included.
+4. Merge the release PR after CI and review pass.
+5. Create the matching `v<version>` tag and GitHub Release from that commit.
+6. Confirm both publish jobs succeed and inspect registry metadata and the
+   package tarball before upgrading consumers.
+
+Creating a GitHub Release publishes the package automatically. Prepare and
+review the release first; do not create a release merely to test the workflow.
+
+## Consumer upgrades
+
+Install the exact released version using the registry used by your CI:
+
+```sh
+npm install --save-exact @kaspacom/kcc20-tx-builder@0.2.5 \
+  --registry=https://registry.npmjs.org/ \
+  --@kaspacom:registry=https://registry.npmjs.org/
+```
+
+Replace `0.2.5` with the reviewed version for a later upgrade. Commit both
+`package.json` and `package-lock.json`. Keep frontend and backend on the same
+exact package version. Remove any `file:../kcc20-tx-builder` resolution before
+independent CI or deployment. Run package, backend, and frontend verification
+against the registry package rather than a neighboring checkout.
+
+## Live release gate
+
+Before deploying either consumer, run one TN10 wallet smoke test with the
+published package (not the local `file:` dependency):
+
+1. Deploy and verify a token, then reload the page and confirm unfinished
+   deploy recovery and backend settlement tracking still find it.
+2. Mint, transfer, wrap, unwrap, and consolidate both native and wrapped
+   holder UTXOs.
+3. Create buy and sell orders; fill, sweep, and cancel both sides.
+4. Deploy/update the FeeTicket root; create, use, transfer, and burn a ticket.
+5. Confirm browser network traffic contains no KCC20 `/plan`, `/build`, or
+   `/sources` requests and that all RPC-backed actions reuse one persistent
+   Kaspa WebSocket connection.
+
+Treat this as a release gate: unit tests prove deterministic construction and
+adapter behavior, while this smoke test proves compatibility with the live
+wallet, WASM, node, and indexer versions being deployed.
+
+## Verify registry metadata
+
+Projects may map the entire `@kaspacom` scope to GitHub Packages. Override that
+mapping when checking public npm:
+
+```sh
+npm view @kaspacom/kcc20-tx-builder version dist-tags \
+  --registry=https://registry.npmjs.org/ \
+  --@kaspacom:registry=https://registry.npmjs.org/
+```
+
+A green publishing workflow confirms an upload, not consumer compatibility.
+Inspect the installed tarball and complete the live release gate before
+consumer deployment. Record any unverified operation families explicitly.
+
+## Snapshot release gate
+
+The current candidate is version `0.4.0`. Keep publication blocked until the release workflow and trusted-publisher configuration are verified for the final release revision. Run `test:snapshot:transactions` with the pinned WASM and close the snapshot artifact reproduction and funded-rehearsal gates before creating the `v0.4.0` tag.

package/SECURITY.md

@@ -0,0 +1,16 @@
+# Security policy
+
+Report wallet, transaction-construction, artifact, or publishing vulnerabilities
+through GitHub private vulnerability reporting when available. Otherwise email
+`security@kaspa.com` with a summary and request a private disclosure channel
+before sending exploit details. Do not post private keys, signed transaction
+payloads containing sensitive data, or exploit details in a public issue.
+
+Use a reviewed package version and its matching artifacts. Applications must
+validate transaction intent, source ownership, recipients, and resulting chain
+state independently. Browser-built PSKTs are untrusted at a server boundary.
+The backend-only engine flag enables construction; your host remains responsible
+for authorization, private-key custody, signing, and broadcasting.
+
+Fixes are prepared on `main`. Historical package versions are not guaranteed
+to receive backports; consult release notes before upgrading.