@kaspacom/kcc20-tx-builder 0.2.5 → 0.4.0

package/docs/snapshot-start.md

@@ -0,0 +1,27 @@
+# Signerless snapshot builders
+
+Protocol: `signerless-start-v2`. Contract source and shared transaction vectors come from `KASPACOM/kaspa-covenants` commit `d968dca9d77632fff5f740adb78b2f8e3fde54f2`. The artifacts and builders are unchanged at `acd14ce0862d7dc87f5c15c93de07df844120303`.
+
+- `snapshot-signerless`: state encoding, commitments and pure transition plans.
+- `snapshot-signerless-transactions`: genesis, start, claim and recipient-transfer transactions.
+- `snapshot-deployment`: deterministic peer-first deployment sequencing and token identity.
+- `snapshot-verification`: metadata payload and reconstruction of the complete deployment/start transaction from approved inputs.
+
+`prepareSnapshotDeployment` accepts an immutable definition and independently confirmed genesis identities. It returns the next controller, bootstrap or start plan. It does not fetch chain state, select a wallet, approve a candidate, sign or broadcast. Hosts own canonical acceptance, UTXO selection, persistence, governance and recovery.
+
+Only the funding input may be signed for genesis/start. Start consumes the bootstrap and every controller, produces all reserves and initialized controllers, and leaves no bootstrap successor. Maximums are eight shards and Merkle depth twenty.
+
+Pin raw artifact hashes in the host approval. The package also verifies compiled script hashes. Compiler and standards pins are in `artifacts/snapshot-standards.lock.json`. Preserve legacy records separately; these artifacts cannot silently replace previously approved artifacts.
+
+## Verification
+
+```sh
+npm ci
+npm test
+SNAPSHOT_TEST_WASM=/path/to/kaspa-covenants/wallet-lab/vendor/kaspa-wasm-toc npm run test:snapshot:transactions
+npm pack --dry-run
+```
+
+The SDK transaction tests use synthetic funded UTXOs. They cover one, two and eight shards, exact reconstruction, metadata, mutated transactions, funding-signature selection, claims and recipient transfers. They do not establish network admission. A funded DEV rehearsal and independent review are required before enabling deployment in a host application.
+
+For the bundled offline test runtime, set `SNAPSHOT_TEST_WASM="$PWD/examples/vendor/kaspa"`. CI runs the transaction and claim tests with these pinned bytes. The public-release compiler gate currently reproduces the five core families; source reproduction of the two snapshot artifacts remains a separate release check.

package/examples/README.md

@@ -0,0 +1,81 @@
+# Frontend and backend transaction examples
+
+These examples build KCC20 transactions inside the application, without
+KaspaCom backend build, plan, or source endpoints. They share TypeScript
+construction code and include their WASM runtime and license.
+
+## Run from the package repository
+
+```sh
+npm ci
+npm run build
+npm ci --prefix examples --registry=https://registry.npmjs.org/ --@kaspacom:registry=https://registry.npmjs.org/
+npm exec --prefix examples -- playwright install --with-deps --only-shell chromium
+npm run test:examples
+npm --prefix examples run backend -- offline
+npm --prefix examples run frontend
+```
+
+`test:examples` packs the current candidate and installs that tarball into the
+examples extracted from that tarball before testing; it also installs the same candidate into the checkout. This matters before 0.4.0 is published: the lockfile's
+registry bootstrap dependency is 0.2.5, which predates the browser compatibility
+fix. Do not skip the candidate installation when testing a checkout.
+
+After publication, users can copy `examples` from the package or repository,
+run `npm ci` inside it, then install the matching release explicitly:
+
+```sh
+npm install --no-save --package-lock=false @kaspacom/kcc20-tx-builder@0.4.0 \
+  --registry=https://registry.npmjs.org/ --@kaspacom:registry=https://registry.npmjs.org/
+npm run backend -- offline
+npm run frontend
+```
+
+Node 22 is the reference runtime. The browser demo opens on the Vite localhost
+URL. Click **Build offline deploy and transfer**. No wallet, RPC, credentials,
+or private repository is needed. The synthetic addresses are public test vectors:
+do not fund them.
+
+## Build against your TN10 node
+
+Construct an operation with the helpers in `shared/build.ts` or use the
+[operation recipes](../docs/RECIPES.md). Save the result to `examples/operation.json` when running the command below
+from the repository root. npm runs this CLI with `examples` as its working directory.
+
+```sh
+KASPA_WRPC_URL=wss://your-tn10-node npm --prefix examples run backend -- build operation.json
+```
+
+The CLI writes the full unsigned builder result. It never signs or broadcasts.
+For a frontend deploy, click **Prepare deploy from KasWare account** to
+construct the operation locally from your connected TN10 account, then review
+the demo token parameters. For other operations, paste the helper-generated
+operation JSON. Enter your RPC URL in the browser form. Inspect the output, then optionally sign with KasWare and broadcast
+with the separate button. Use a TN10-compatible node and wallet. Your RPC endpoint
+must permit browser WebSocket access; HTTPS pages need a secure `wss://` endpoint.
+
+Read the [transaction guide](../docs/TRANSACTION_GUIDE.md) for source snapshots,
+decimals, fees, covenant script signing, and failure handling. Offline tests do
+not establish that the selected node or wallet supports the current TN10 rules.
+
+## Files to copy into your application
+
+- `shared/build.ts`: helpers, operation-to-engine adapter, source injection, inspection.
+- `backend/runtime.ts` or `frontend/runtime.ts`: initialize WASM and load package artifacts.
+- `shared/signing.ts`: covenant script assembly after wallet signing.
+- `shared/recipes.ts`: typed entry points for the other operation families.
+
+`shared/fixture.ts` is offline test data. Replace it with your RPC provider and
+own indexer/decoded snapshots for live builds. Keep one host-owned connection
+and close it when the host shuts down.
+
+## Complete operation recipes and live transfer
+
+The browser **Offline recipe** selector and `npm run recipe -- <name> --offline`
+construct all 24 documented scenarios. `--arguments` prints their complete typed
+helper arguments as JSON. See [recipes](../docs/RECIPES.md).
+
+To retrieve real holder state independently, follow the
+[live transfer guide](../docs/LIVE_TRANSFER.md). Node supports
+`npm run backend -- transfer transfer.json`; the browser accepts the same config
+through **Build transfer from indexer**. Both verify decoded state against RPC.

package/examples/backend/cli.ts

@@ -0,0 +1,55 @@
+import { liveTransferOperation } from "../shared/live-transfer.ts";
+import { withTimeout } from "../shared/timeout.ts";
+import { readFile } from "node:fs/promises";
+import { runtime, loadArtifact } from "./runtime.ts";
+import {
+  createBuilder,
+  deployOperation,
+  transferOperation,
+  inspect,
+  network,
+} from "../shared/build.ts";
+import { fixture, recipient } from "../shared/fixture.ts";
+const wasm = await runtime();
+const mode = process.argv[2] ?? "offline";
+if (mode === "offline") {
+  const data = fixture(wasm);
+  const build = createBuilder(wasm, data.sources, loadArtifact);
+  const deploy = await build(deployOperation(data.wallet));
+  const transfer = await build(
+    transferOperation(data.wallet, data.addDeploy(deploy), recipient),
+  );
+  console.log(
+    JSON.stringify(
+      { deploy: inspect(deploy), transfer: inspect(transfer) },
+      null,
+      2,
+    ),
+  );
+} else if (mode === "build" || mode === "transfer") {
+  const path = process.argv[3];
+  if (!path || !process.env.KASPA_WRPC_URL)
+    throw new Error(
+      "Usage: KASPA_WRPC_URL=wss://your-node npm run backend -- build operation.json",
+    );
+  const document = JSON.parse(await readFile(path, "utf8"));
+  const rpc = new wasm.RpcClient({
+    url: process.env.KASPA_WRPC_URL,
+    encoding: wasm.Encoding.Borsh,
+    networkId: network,
+  });
+  try {
+    await withTimeout(rpc.connect(), "RPC connection");
+    const info = await withTimeout(rpc.getBlockDagInfo(), "Network query");
+    if (info.network !== network)
+      throw new Error(`RPC network mismatch: ${info.network}`);
+    const operation =
+      mode === "transfer"
+        ? await liveTransferOperation(wasm, rpc, loadArtifact, document)
+        : document;
+    const result = await createBuilder(wasm, rpc, loadArtifact)(operation);
+    console.log(JSON.stringify(result, null, 2));
+  } finally {
+    await withTimeout(rpc.disconnect(), "RPC disconnect", 5_000);
+  }
+} else throw new Error("Expected offline, build or transfer");

package/examples/backend/recipe.ts

@@ -0,0 +1,39 @@
+import { runtime, loadArtifact } from "./runtime.ts";
+import { recipeFixtures } from "../shared/recipe-fixtures.ts";
+import { inspect } from "../shared/build.ts";
+import { readFile } from "node:fs/promises";
+import { recipes } from "../shared/recipes.ts";
+import { engineInput, type Operation } from "../shared/build.ts";
+const name = process.argv[2];
+const path = process.argv[3];
+if (!Object.hasOwn(recipes, name) || !path)
+  throw new Error(
+    `Usage: npm run recipe -- <${Object.keys(recipes).join("|")}> arguments.json`,
+  );
+if (path === "--offline" || path === "--arguments") {
+  const fixture = await recipeFixtures(await runtime(), loadArtifact);
+  const key = name as keyof typeof recipes;
+  const unsigned =
+    path === "--offline"
+      ? await fixture.build(fixture.operation(key))
+      : undefined;
+  console.log(
+    JSON.stringify(
+      unsigned
+        ? { inspection: inspect(unsigned), unsigned }
+        : fixture.args[key],
+      null,
+      2,
+    ),
+  );
+} else {
+  const args = JSON.parse(await readFile(path, "utf8"));
+  if (!Array.isArray(args))
+    throw new Error("arguments.json must contain an array of helper arguments");
+  const fn = recipes[name as keyof typeof recipes] as (
+    ...args: any[]
+  ) => unknown;
+  const operation = fn(...args) as Operation;
+  engineInput(operation); // Reject accidental non-TN10 configuration before RPC access.
+  console.log(JSON.stringify(operation, null, 2));
+}

package/examples/backend/runtime.ts

@@ -0,0 +1,13 @@
+import { readFile } from 'node:fs/promises';
+import * as wasm from '../vendor/kaspa/kaspa.js';
+let initialized: Promise<unknown> | undefined;
+export async function runtime() {
+  initialized ??= readFile(new URL('../vendor/kaspa/kaspa_bg.wasm', import.meta.url)).then(bytes => wasm.default({ module_or_path: bytes }));
+  await initialized;
+  wasm.initWASM32Bindings({ validateClassNames: false });
+  return wasm;
+}
+export async function loadArtifact(key: string) {
+  const path = import.meta.resolve(`@kaspacom/kcc20-tx-builder/artifacts/${key}`);
+  return JSON.parse(await readFile(new URL(path), 'utf8'));
+}

package/examples/frontend/index.html

@@ -0,0 +1,48 @@
+<!doctype html>
+<html lang="en">
+  <meta charset="utf-8" /><meta
+    name="viewport"
+    content="width=device-width, initial-scale=1"
+  />
+  <title>KCC20 transaction builder examples</title>
+  <body>
+    <main>
+      <h1>Build KCC20 transactions locally</h1>
+      <p>
+        TN10 development example. Offline inputs are synthetic and cannot be
+        broadcast.
+      </p>
+      <button id="offline">Build offline deploy and transfer</button>
+      <p>
+        <label
+          >Offline recipe
+          <select id="recipe"></select
+        ></label>
+        <button id="recipe-build">Build offline recipe</button>
+      </p>
+      <h2>Build using your TN10 node</h2>
+      <button id="prepare">Prepare deploy from KasWare account</button>
+      <label
+        >RPC URL <input id="rpc" placeholder="wss://your-tn10-node" size="45"
+      /></label>
+      <p>
+        <label
+          >Operation or transfer configuration JSON
+          <textarea
+            id="operation"
+            rows="12"
+            cols="80"
+            placeholder="Paste the output of deployOperation or transferOperation"
+          ></textarea>
+        </label>
+      </p>
+      <button id="build">Build unsigned transaction</button>
+      <button id="transfer">Build transfer from indexer</button>
+      <button id="sign" disabled>Sign with KasWare</button>
+      <button id="broadcast" disabled>Broadcast signed transaction</button>
+      <p id="status" role="status">Ready</p>
+      <pre id="result"></pre>
+    </main>
+    <script type="module" src="/main.ts"></script>
+  </body>
+</html>

package/examples/frontend/main.ts

@@ -0,0 +1,213 @@
+import { recipeFixtures } from "../shared/recipe-fixtures.ts";
+import { recipes } from "../shared/recipes.ts";
+import { liveTransferOperation } from "../shared/live-transfer.ts";
+import { withTimeout } from "../shared/timeout.ts";
+import { runtime, loadArtifact } from "./runtime.ts";
+import {
+  createBuilder,
+  deployOperation,
+  transferOperation,
+  inspect,
+  network,
+  type Built,
+} from "../shared/build.ts";
+import { fixture, recipient } from "../shared/fixture.ts";
+import { attachScripts, signingInputs } from "../shared/signing.ts";
+const status = document.querySelector("#status")!;
+const output = document.querySelector("#result")!;
+const sign = document.querySelector<HTMLButtonElement>("#sign")!;
+const broadcast = document.querySelector<HTMLButtonElement>("#broadcast")!;
+let built: Built | undefined;
+let signed: string | undefined;
+let rpc:
+  | InstanceType<Awaited<ReturnType<typeof runtime>>["RpcClient"]>
+  | undefined;
+let buildAddress = "";
+let busy = false;
+async function action(fn: () => Promise<void>) {
+  if (busy) return;
+  busy = true;
+  document
+    .querySelectorAll("button, input, textarea, select")
+    .forEach((element) => ((element as HTMLInputElement).disabled = true));
+  status.textContent = "Working";
+  try {
+    await fn();
+    status.textContent = "Complete";
+  } catch (error) {
+    await clear();
+    status.textContent = String(error);
+  } finally {
+    busy = false;
+    document
+      .querySelectorAll("button, input, textarea, select")
+      .forEach((element) => ((element as HTMLInputElement).disabled = false));
+    sign.disabled = !built;
+    broadcast.disabled = !signed;
+  }
+}
+async function clear() {
+  built = undefined;
+  signed = undefined;
+  sign.disabled = true;
+  broadcast.disabled = true;
+  if (rpc)
+    await withTimeout(rpc.disconnect(), "RPC disconnect", 5_000).catch(
+      () => undefined,
+    );
+  rpc = undefined;
+}
+export async function offline() {
+  const wasm = await runtime();
+  const data = fixture(wasm);
+  const build = createBuilder(wasm, data.sources, loadArtifact);
+  const deploy = await build(deployOperation(data.wallet));
+  const transfer = await build(
+    transferOperation(data.wallet, data.addDeploy(deploy), recipient),
+  );
+  return { deploy, transfer };
+}
+// Used by the browser acceptance test, which blocks every external request.
+let preparedFixtures: ReturnType<typeof recipeFixtures> | undefined;
+async function offlineRecipe(name: keyof typeof recipes) {
+  preparedFixtures ??= runtime().then((wasm) =>
+    recipeFixtures(wasm, loadArtifact),
+  );
+  const data = await preparedFixtures;
+  return await data.build(data.operation(name));
+}
+Object.assign(window, {
+  runOfflineExample: offline,
+  runOfflineRecipe: offlineRecipe,
+});
+const recipeSelect = document.querySelector<HTMLSelectElement>("#recipe")!;
+for (const name of Object.keys(recipes))
+  recipeSelect.add(new Option(name, name));
+document.querySelector("#recipe-build")!.addEventListener("click", () =>
+  action(async () => {
+    await clear();
+    const result = await offlineRecipe(
+      recipeSelect.value as keyof typeof recipes,
+    );
+    output.textContent = JSON.stringify(
+      { inspection: inspect(result), unsigned: result },
+      null,
+      2,
+    );
+  }),
+);
+document.querySelector("#offline")!.addEventListener("click", () =>
+  action(async () => {
+    await clear();
+    const result = await offline();
+    output.textContent = JSON.stringify(
+      { deploy: inspect(result.deploy), transfer: inspect(result.transfer) },
+      null,
+      2,
+    );
+  }),
+);
+document.querySelector("#prepare")!.addEventListener("click", () =>
+  action(async () => {
+    await clear();
+    const wallet = (window as any).kasware;
+    if (!wallet?.getPublicKey)
+      throw new Error("Install KasWare to prepare a live deploy");
+    if ((await wallet.getNetwork()) !== "kaspa_testnet_10")
+      throw new Error("Select TN10 in KasWare");
+    const [walletAddress] = await wallet.requestAccounts();
+    if (!walletAddress) throw new Error("Wallet did not return an account");
+    const wasm = await runtime();
+    const publicKey = await wallet.getPublicKey();
+    const owner =
+      publicKey.length === 64
+        ? publicKey
+        : new wasm.PublicKey(publicKey).toXOnlyPublicKey().toString();
+    if (
+      new wasm.XOnlyPublicKey(owner).toAddress(network).toString() !==
+      walletAddress
+    )
+      throw new Error("Wallet address and public key do not match");
+    const operation = deployOperation({ walletAddress, kcc20Owner: owner });
+    document.querySelector<HTMLTextAreaElement>("#operation")!.value =
+      JSON.stringify(operation, null, 2);
+    output.textContent =
+      "Deploy operation prepared locally. Review the token parameters, choose your RPC, then build.";
+  }),
+);
+async function buildLive(fromIndexer = false) {
+  await clear();
+  const wasm = await runtime();
+  const documentInput = JSON.parse(
+    document.querySelector<HTMLTextAreaElement>("#operation")!.value,
+  );
+  const url = document.querySelector<HTMLInputElement>("#rpc")!.value;
+  if (!/^wss?:\/\//.test(url))
+    throw new Error("Enter your TN10 WebSocket RPC URL");
+  rpc = new wasm.RpcClient({
+    url,
+    networkId: network,
+    encoding: wasm.Encoding.Borsh,
+  });
+  await withTimeout(rpc.connect(), "RPC connection");
+  if (
+    (await withTimeout(rpc.getBlockDagInfo(), "Network query")).network !==
+    network
+  )
+    throw new Error("RPC network mismatch");
+  const operation = fromIndexer
+    ? await liveTransferOperation(wasm, rpc, loadArtifact, documentInput)
+    : documentInput;
+  built = await createBuilder(wasm, rpc, loadArtifact)(operation);
+  buildAddress = operation.payload.owner.walletAddress;
+  output.textContent = JSON.stringify(
+    { inspection: inspect(built), transaction: built },
+    null,
+    2,
+  );
+  sign.disabled = false;
+}
+document
+  .querySelector("#build")!
+  .addEventListener("click", () => action(() => buildLive()));
+document
+  .querySelector("#transfer")!
+  .addEventListener("click", () => action(() => buildLive(true)));
+sign.addEventListener("click", () =>
+  action(async () => {
+    signed = undefined;
+    broadcast.disabled = true;
+    const wallet = (window as any).kasware;
+    if (!built || !wallet?.signPskt)
+      throw new Error("Install a KasWare version with PSKT signing");
+    if ((await wallet.getNetwork()) !== "kaspa_testnet_10")
+      throw new Error("Select TN10 in KasWare");
+    if ((await wallet.requestAccounts())[0] !== buildAddress)
+      throw new Error("Wallet account differs from transaction owner");
+    const json = await wallet.signPskt({
+      txJsonString: built.psktTransactionJson,
+      options: { signInputs: signingInputs(built) },
+    });
+    signed = attachScripts(await runtime(), json, built);
+    output.textContent = signed!;
+    broadcast.disabled = false;
+  }),
+);
+broadcast.addEventListener("click", () =>
+  action(async () => {
+    if (!signed || !rpc) throw new Error("Build and sign first");
+    if (!confirm("Broadcast this signed transaction to TN10?")) return;
+    const wasm = await runtime();
+    const result = await withTimeout(
+      rpc.submitTransaction({
+        transaction: wasm.Transaction.deserializeFromSafeJSON(signed),
+        allowOrphan: false,
+      }),
+      "Submission; check transaction acceptance before retrying",
+    );
+    output.textContent = JSON.stringify(result);
+    signed = undefined;
+    built = undefined;
+    await clear();
+  }),
+);

package/examples/frontend/runtime.ts

@@ -0,0 +1,14 @@
+import * as wasm from '../vendor/kaspa/kaspa.js';
+let initialized: Promise<unknown> | undefined;
+export async function runtime() {
+  initialized ??= wasm.default({ module_or_path: new URL('../vendor/kaspa/kaspa_bg.wasm', import.meta.url) });
+  await initialized;
+  wasm.initWASM32Bindings({ validateClassNames: false });
+  return wasm;
+}
+const artifacts = import.meta.glob('../node_modules/@kaspacom/kcc20-tx-builder/artifacts/*.json', { import: 'default' });
+export async function loadArtifact(key: string) {
+  const load = artifacts[`../node_modules/@kaspacom/kcc20-tx-builder/artifacts/${key}`];
+  if (!load) throw new Error(`Missing packaged artifact ${key}`);
+  return load();
+}