@kaspacom/kcc20-tx-builder 0.4.0 → 0.6.0

package/docs/INTEGRATION.md

@@ -1,6 +1,6 @@
 # Integrating the TX Builder
 
-This guide describes the API shipped in `@kaspacom/kcc20-tx-builder@0.2.5`.
+This guide describes the API shipped in `@kaspacom/kcc20-tx-builder@0.5.0`.
 The host application supplies wallet identity, network configuration, contract
 artifacts, chain data, and an initialized Kaspa WASM runtime. The package
 constructs operations and transaction JSON. The host signs, validates,
@@ -9,7 +9,7 @@ broadcasts, and tracks the result.
 ## Install from the public registry
 
 ```sh
-npm install --save-exact @kaspacom/kcc20-tx-builder@0.2.5 \
+npm install --save-exact @kaspacom/kcc20-tx-builder@0.5.0 \
   --registry=https://registry.npmjs.org/ \
   --@kaspacom:registry=https://registry.npmjs.org/
 ```

package/docs/LAST_CALL.md

@@ -0,0 +1,50 @@
+# KCC20 Last Call builders
+
+Target revision: `3fbec524abfbc20e87652eb938db218f8c17db17`.
+Local package: `0.5.0-lastcall.1`. Funded TN10 qualification remains a release task.
+
+## Profile boundary
+
+Authenticate the registry digest, then match a bundled profile to a revealed
+program and current RPC output. `authenticateTokenArtifact` checks the entire
+artifact, ABI, state layout and executable template commitment. Names and
+uploaded JSON are not authority.
+
+`buildProfileTransferTransaction` constructs explicit owner or borrowed-receive
+transactions. It supports Schnorr P2PK, Schnorr/ECDSA P2PKH, supplied P2SH
+authorities and covenant-ID authorities. Callers must obtain fresh authenticated
+RPC entries before building and recheck acceptance before signing. Authority
+inputs require a reviewed witness adapter. Outputs preserve authority value,
+script and identity. Pass the trusted registry manifest, its expected digest and
+the selected profile ID; a standalone profile object is not authorization. This
+API does not broadcast.
+
+`planTokenOwnerWitness` checks wallet capabilities before signing. Borrowing is
+never selected automatically. The normal wallet engine supports its reviewed
+public-key paths; advanced authority/borrow callers use the explicit API.
+
+Wrapper construction resolves the bundled token template and its committed
+wrapper artifact. External custom mint/burn operations are rejected.
+Profiles with `displayDecimals` pin the wrapper price scale to that precision.
+
+## Artifact synchronization
+
+From the builder repository:
+
+```sh
+node scripts/sync-reviewed-artifacts.mjs /path/to/kaspa-covenants
+npm test
+npm run verify:compatibility
+SNAPSHOT_TEST_WASM=/path/to/kaspa-covenants/wallet-lab/vendor/kaspa-wasm-toc \
+  npm run test:snapshot:transactions
+npm pack
+```
+
+Both backend and frontend must consume the same archive hash. Snapshot pins
+include the corrected token, bootstrap and controller artifacts. Earlier source
+snapshots are reusable, but previous contract approvals cannot be rebound.
+
+Local tests cover independent bytecode/state offset, profile bounds, owner and
+borrow witness construction, malformed commitments, and one/two/eight-shard
+snapshot construction. Synthetic funding in these tests is not a funded TN10
+proof. Funded deploy and trading checks belong to release qualification.

package/examples/README.md

@@ -17,15 +17,18 @@ 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
+examples extracted from that tarball before testing; it also installs the same candidate into the checkout. This matters before 0.5.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.
 
+Synthetic offline examples use the same digest-authenticated bundled profile as
+live builders. They do not broadcast transactions.
+
 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 \
+npm install --no-save --package-lock=false @kaspacom/kcc20-tx-builder@0.5.0 \
   --registry=https://registry.npmjs.org/ --@kaspacom:registry=https://registry.npmjs.org/
 npm run backend -- offline
 npm run frontend

package/examples/backend/cli.ts

@@ -10,11 +10,12 @@ import {
   network,
 } from "../shared/build.ts";
 import { fixture, recipient } from "../shared/fixture.ts";
+import { createOfflineBuilder } from "../shared/offline-profile.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 build = createOfflineBuilder(wasm, data.sources, loadArtifact);
   const deploy = await build(deployOperation(data.wallet));
   const transfer = await build(
     transferOperation(data.wallet, data.addDeploy(deploy), recipient),

package/examples/frontend/main.ts

@@ -12,6 +12,7 @@ import {
   type Built,
 } from "../shared/build.ts";
 import { fixture, recipient } from "../shared/fixture.ts";
+import { createOfflineBuilder } from "../shared/offline-profile.ts";
 import { attachScripts, signingInputs } from "../shared/signing.ts";
 const status = document.querySelector("#status")!;
 const output = document.querySelector("#result")!;
@@ -60,7 +61,7 @@ async function clear() {
 export async function offline() {
   const wasm = await runtime();
   const data = fixture(wasm);
-  const build = createBuilder(wasm, data.sources, loadArtifact);
+  const build = createOfflineBuilder(wasm, data.sources, loadArtifact);
   const deploy = await build(deployOperation(data.wallet));
   const transfer = await build(
     transferOperation(data.wallet, data.addDeploy(deploy), recipient),

package/examples/shared/build.ts

@@ -7,6 +7,7 @@ import {
   isKcc20ArtifactKey,
 } from "@kaspacom/kcc20-tx-builder/artifacts";
 import type { Kcc20IndexedCovenantUtxo } from "@kaspacom/kcc20-tx-builder/action-source-resolver";
+import type { AuthenticatedTokenProfileRegistry } from "@kaspacom/kcc20-tx-builder/token-profiles";
 import type * as Wasm from "../vendor/kaspa/kaspa.js";
 
 export const network = "testnet-10";
@@ -74,6 +75,7 @@ export function createBuilder(
   wasm: Runtime,
   sources: Sources,
   loadArtifact: (key: string) => Promise<unknown>,
+  options: { tokenProfileRegistry?: AuthenticatedTokenProfileRegistry } = {},
 ) {
   for (const key of [
     "Transaction",
@@ -99,6 +101,7 @@ export function createBuilder(
       assertKcc20ArtifactScriptHash(key, artifact);
       return artifact;
     },
+    tokenProfileRegistry: options.tokenProfileRegistry,
   });
   return async (operation: Operation): Promise<Built> => {
     const result = await engine.build(engineInput(operation));

package/examples/shared/offline-profile.ts

@@ -0,0 +1,27 @@
+import {
+  BUNDLED_TOKEN_PROFILES,
+  BUNDLED_TOKEN_PROFILE_DIGEST,
+} from "@kaspacom/kcc20-tx-builder/token-profiles.generated";
+import type { AuthenticatedTokenProfileRegistry } from "@kaspacom/kcc20-tx-builder/token-profiles";
+import {
+  createBuilder,
+  type Runtime,
+  type Sources,
+} from "./build.ts";
+
+/** Offline fixtures use the same authenticated registry as live construction. */
+export const OFFLINE_EXAMPLE_TOKEN_PROFILE_REGISTRY: AuthenticatedTokenProfileRegistry =
+  Object.freeze({
+    manifest: BUNDLED_TOKEN_PROFILES,
+    sha256: BUNDLED_TOKEN_PROFILE_DIGEST,
+  });
+
+export function createOfflineBuilder(
+  wasm: Runtime,
+  sources: Sources,
+  loadArtifact: (key: string) => Promise<unknown>,
+) {
+  return createBuilder(wasm, sources, loadArtifact, {
+    tokenProfileRegistry: OFFLINE_EXAMPLE_TOKEN_PROFILE_REGISTRY,
+  });
+}

package/examples/shared/recipe-fixtures.ts

@@ -10,7 +10,6 @@ import {
 } from "@kaspacom/kcc20-tx-builder/sale-common";
 import type { Kcc20IndexedCovenantUtxo } from "@kaspacom/kcc20-tx-builder/action-source-resolver";
 import {
-  createBuilder,
   deployOperation,
   network,
   type Runtime,
@@ -18,6 +17,7 @@ import {
 } from "./build.ts";
 import { fixture, owner, recipient } from "./fixture.ts";
 import { recipes } from "./recipes.ts";
+import { createOfflineBuilder } from "./offline-profile.ts";
 
 // These are independent synthetic source snapshots, not a simulated chain ledger.
 // Never broadcast their transactions or fund their public test-vector addresses.
@@ -26,7 +26,7 @@ export async function recipeFixtures(
   loadArtifact: (key: string) => Promise<unknown>,
 ) {
   const data = fixture(wasm);
-  const build = createBuilder(wasm, data.sources, loadArtifact);
+  const build = createOfflineBuilder(wasm, data.sources, loadArtifact);
   const options = {
     network,
     createdAt: "2026-01-01T00:00:00.000Z",
@@ -416,6 +416,7 @@ export async function recipeFixtures(
       wallet,
       {
         canonicalCovenantId: tokenId,
+        tokenUtxo: baseHolder,
         tokenDecimals: 2,
         wrappedRootAmount: "0",
       },

package/examples/test/browser.ts

@@ -3,13 +3,13 @@ import { preview } from "vite";
 import { chromium } from "playwright";
 import { runtime, loadArtifact } from "../backend/runtime.ts";
 import {
-  createBuilder,
   deployOperation,
   transferOperation,
 } from "../shared/build.ts";
 import { recipeFixtures } from "../shared/recipe-fixtures.ts";
 import { recipes } from "../shared/recipes.ts";
 import { fixture, recipient, owner } from "../shared/fixture.ts";
+import { createOfflineBuilder } from "../shared/offline-profile.ts";
 const server = await preview({
   root: "frontend",
   preview: { host: "127.0.0.1", port: 4173, strictPort: true },
@@ -38,7 +38,7 @@ try {
   );
   const wasm = await runtime();
   const data = fixture(wasm);
-  const build = createBuilder(wasm, data.sources, loadArtifact);
+  const build = createOfflineBuilder(wasm, data.sources, loadArtifact);
   const deploy = await build(deployOperation(data.wallet));
   const transfer = await build(
     transferOperation(data.wallet, data.addDeploy(deploy), recipient),

package/examples/test/build.test.ts

@@ -11,6 +11,7 @@ import {
   type Runtime,
 } from "../shared/build.ts";
 import { fixture, recipient } from "../shared/fixture.ts";
+import { createOfflineBuilder } from "../shared/offline-profile.ts";
 import { attachScripts, signingInputs } from "../shared/signing.ts";
 const wasm = await runtime();
 // Offline construction must not silently fall back to any backend or RPC.
@@ -18,9 +19,21 @@ globalThis.fetch = async () => {
   throw new Error("Network access forbidden in offline examples");
 };
 
+test("production and offline builders use the same bundled profile", async () => {
+  const data = fixture(wasm);
+  await assert.doesNotReject(
+    createBuilder(wasm, data.sources, loadArtifact)(deployOperation(data.wallet)),
+  );
+  await assert.doesNotReject(
+    createOfflineBuilder(wasm, data.sources, loadArtifact)(
+      deployOperation(data.wallet),
+    ),
+  );
+});
+
 test("build deploy and transfer with actual WASM, covenant bindings, amounts and change", async () => {
   const data = fixture(wasm);
-  const build = createBuilder(
+  const build = createOfflineBuilder(
     Object.freeze({ ...wasm }),
     data.sources,
     loadArtifact,
@@ -61,7 +74,7 @@ test("build deploy and transfer with actual WASM, covenant bindings, amounts and
 });
 test("reject missing funding, stale source, wrong owner, network and incompatible artifact/runtime", async () => {
   const data = fixture(wasm);
-  const build = createBuilder(wasm, data.sources, loadArtifact);
+  const build = createOfflineBuilder(wasm, data.sources, loadArtifact);
   const operation = deployOperation(data.wallet);
   const deploy = await build(operation);
   const holder = data.addDeploy(deploy);
@@ -88,20 +101,20 @@ test("reject missing funding, stale source, wrong owner, network and incompatibl
     /holder UTXO/,
   );
   await assert.rejects(
-    createBuilder(wasm, fixture(wasm).sources, async () => ({
+    createOfflineBuilder(wasm, fixture(wasm).sources, async () => ({
       script: [1, 2],
     }))(operation),
     /hash mismatch/,
   );
   assert.throws(
-    () => createBuilder({} as Runtime, data.sources, loadArtifact),
+    () => createOfflineBuilder({} as Runtime, data.sources, loadArtifact),
     /Incompatible WASM/,
   );
 });
 
 test("reject conflicting explicit native identity, but retain legacy alias resolution", async () => {
   const data = fixture(wasm);
-  const build = createBuilder(wasm, data.sources, loadArtifact);
+  const build = createOfflineBuilder(wasm, data.sources, loadArtifact);
   const holder = data.addDeploy(await build(deployOperation(data.wallet)));
   const operation = transferOperation(data.wallet, holder, recipient);
   const entry = data.rows.get(holder.address)![0];
@@ -130,7 +143,7 @@ test("reject conflicting explicit native identity, but retain legacy alias resol
 
 test("preserve witnesses outside requested signing inputs and reject malformed signatures", async () => {
   const data = fixture(wasm);
-  const build = createBuilder(wasm, data.sources, loadArtifact);
+  const build = createOfflineBuilder(wasm, data.sources, loadArtifact);
   const deploy = await build(deployOperation(data.wallet));
   const holder = data.addDeploy(deploy);
   const transfer = await build(
@@ -171,7 +184,7 @@ test("preserve witnesses outside requested signing inputs and reject malformed s
 
 test("generic transfer rejects conflicting RPC scripts and KAS amounts", async () => {
   const data = fixture(wasm),
-    build = createBuilder(wasm, data.sources, loadArtifact);
+    build = createOfflineBuilder(wasm, data.sources, loadArtifact);
   const holder = data.addDeploy(await build(deployOperation(data.wallet)));
   const operation = transferOperation(data.wallet, holder, recipient);
   const row = data.rows.get(holder.address)![0];
@@ -187,7 +200,7 @@ test("reject a present funding input that cannot cover the required KAS", async
   const data = fixture(wasm);
   data.rows.get(data.wallet.walletAddress)![0].amount = 1n;
   await assert.rejects(
-    createBuilder(
+    createOfflineBuilder(
       wasm,
       data.sources,
       loadArtifact,

package/examples/test/sources.test.ts

@@ -1,13 +1,14 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { runtime, loadArtifact } from "../backend/runtime.ts";
-import { createBuilder, deployOperation, network } from "../shared/build.ts";
+import { deployOperation, network } from "../shared/build.ts";
 import { fixture, recipient } from "../shared/fixture.ts";
+import { createOfflineBuilder } from "../shared/offline-profile.ts";
 import { liveTransferOperation } from "../shared/live-transfer.ts";
 const wasm = await runtime();
 async function setup() {
   const data = fixture(wasm);
-  const build = createBuilder(wasm, data.sources, loadArtifact);
+  const build = createOfflineBuilder(wasm, data.sources, loadArtifact);
   const holder = data.addDeploy(await build(deployOperation(data.wallet)));
   const config = {
     network,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaspacom/kcc20-tx-builder",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Runtime-independent KCC20 covenant transaction and PSKT construction primitives.",
   "license": "Apache-2.0",
   "author": "KaspaCom",
@@ -86,7 +86,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/write-cjs-package.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run typecheck && npm run build && node test/smoke.mjs && node test/cjs-smoke.cjs && node test/snapshot-plan.mjs",
+    "test": "npm run typecheck && npm run build && node test/smoke.mjs && node test/cjs-smoke.cjs && node test/snapshot-plan.mjs && node test/token-profiles.mjs && node test/profile-transfer.mjs",
     "prepack": "npm test",
     "test:examples": "npm run verify:compatibility && node scripts/test-examples.mjs --browser",
     "verify:compatibility": "node scripts/verify-compatibility.mjs",

package/src/action-source-resolver.ts

@@ -1,3 +1,4 @@
+import { tokenPublicKeyHash } from "./token-authorization.js";
 export interface Kcc20IndexedCovenantUtxo {
   [field: string]: unknown;
   txidHex: string;
@@ -125,6 +126,16 @@ export function ownerNativeHolderUtxos(
   owner: string,
 ): Kcc20IndexedCovenantUtxo[] {
   const normalizedOwner = owner.toLowerCase();
+  const hashedOwner = /^[a-f0-9]{64}$/.test(normalizedOwner)
+    ? Array.from(
+        tokenPublicKeyHash(
+          Uint8Array.from(normalizedOwner.match(/../g)!, (b) =>
+            parseInt(b, 16),
+          ),
+        ),
+        (b) => b.toString(16).padStart(2, "0"),
+      ).join("")
+    : null;
   return utxos.filter((utxo) => {
     const state = utxo.state;
     const value = amount(state?.["amount"]);
@@ -132,10 +143,17 @@ export function ownerNativeHolderUtxos(
       value !== null &&
       value > 0n &&
       state?.["isMintAuthority"] !== true &&
-      numberValue(state?.["ownerScheme"] ?? state?.["identifierType"]) === 0 &&
-      stringValue(
-        state?.["ownerIdentifier"] ?? state?.["owner"],
-      )?.toLowerCase() === normalizedOwner
+      ((numberValue(state?.["ownerScheme"] ?? state?.["identifierType"]) ===
+        0 &&
+        stringValue(
+          state?.["ownerIdentifier"] ?? state?.["owner"],
+        )?.toLowerCase() === normalizedOwner) ||
+        (numberValue(state?.["ownerScheme"] ?? state?.["identifierType"]) ===
+          1 &&
+          hashedOwner !== null &&
+          stringValue(
+            state?.["ownerIdentifier"] ?? state?.["owner"],
+          )?.toLowerCase() === hashedOwner))
     );
   });
 }

package/src/artifacts.ts

@@ -7,18 +7,20 @@ export const KCC20_CURRENT_NATIVE_ARTIFACT_KEY =
   "KCC20.placeholder.json" as const;
 
 export const KCC20_ARTIFACT_SCRIPT_SHA256 = Object.freeze({
-  "KCC20SnapshotBootstrap.placeholder.json": "85edea7401eb415c447e6a0d0a45e1667802a269dde9fbe33d5881c4a4de51e2",
-  "KCC20SnapshotController.placeholder.json": "8f90525afcc1c23240f1d18eed30b3b377a72a323e8b48925dfac53bd5aab0ae",
+  "KCC20SnapshotBootstrap.placeholder.json":
+    "3d64211a2b3c5ac24009b9ce59d4e8ecb8f2114dbf0c43b5a060b2ed91704e02",
+  "KCC20SnapshotController.placeholder.json":
+    "fdc2e396a66a1f708522d68f879ec67d71bd0070c7417b1e7f5dd3a6c8cfda88",
   [KCC20_CURRENT_NATIVE_ARTIFACT_KEY]:
-    "4633b082f26adbf14600b767d6e2146e36ce67d63d8202c0281857922c05ac41",
+    "dd9cb334cd9e9220b15644782f271ef3ecdba34fd0762010e3d6bc18176837ae",
   "KCC20FeeTicket.placeholder.json":
-    "ed81365466ee4c44db1210b3360783af8145f74e49e847848195e09c71ad6930",
+    "c0e95cb8e5226462674647f86d5760626b5c38b7bd97a6e2ec9ba61fdef8941f",
   "KCC20Orderbook.placeholder.json":
     "ef9fe81ff7aa2dc2df118d8d7cc126aca6f2f9c181b9c2d15727a538b23c6f71",
   "KCC20Wrapper.placeholder.json":
-    "f3bdf09be9aa258708a306283a4278a93cfb64f35fc50ed7d316b9b189ef9030",
+    "23cbd5473860cab4e63890d24ae1bd6732fce5beaa34f594dad01e845e3e9b9f",
   "KCC20Vesting.placeholder.json":
-    "1b84d74aa01b6a50edbff5bf1f9e988a5a6a00ec645458dfd3912ac532b77c33",
+    "e32d9f5bde124526475a61075ba46eef41955d4662b1422713860cfbd7a59661",
 });
 
 /**
@@ -31,7 +33,7 @@ export const KCC20_SNAPSHOT_ARTIFACT_PINS = Object.freeze({
     key: "KCC20SnapshotBootstrap.placeholder.json",
     contractName: "KCC20SnapshotBootstrap",
     artifactSha256:
-      "bc566a964b5feb1c2055d5130af25951142d695472287b888c5537e9a56ee3d2",
+      "5f0caea9818f5bd6110023a7f089a0d26f87d3fd0901cb52e24a32bd1853b302",
     scriptLength: 33718,
     stateStart: 1,
     stateLength: 405,
@@ -40,7 +42,7 @@ export const KCC20_SNAPSHOT_ARTIFACT_PINS = Object.freeze({
     key: "KCC20SnapshotController.placeholder.json",
     contractName: "KCC20SnapshotController",
     artifactSha256:
-      "f0d7b082e0680a90736948cd6658ccbc8600e097d9b4d5568013acdaafb39bf5",
+      "8c5d2056bb0a445ffc1a6967238fac46378372b5f357524c6795201699bf2b2f",
     scriptLength: 15297,
     stateStart: 1,
     stateLength: 432,
@@ -49,9 +51,9 @@ export const KCC20_SNAPSHOT_ARTIFACT_PINS = Object.freeze({
 
 /** Canonical KCC20 template committed by both snapshot contracts. */
 export const KCC20_SNAPSHOT_TOKEN_TEMPLATE_PIN = Object.freeze({
-  hash: "911f0638ccb7368bf36d117f1725073ae7ee487ce8b58ca3e8375051c2d40f6c",
+  hash: "5d6cacdf57c734536fcb8a9c833f0318671226727ec77c503a98fc5be59f9e29",
   prefixLength: 1,
-  suffixLength: 25439,
+  suffixLength: 25264,
 });
 
 export type Kcc20ArtifactKey = keyof typeof KCC20_ARTIFACT_SCRIPT_SHA256;