@kaspacom/kcc20-tx-builder 0.2.0 → 0.4.0

package/examples/test/browser.ts

@@ -0,0 +1,116 @@
+import assert from "node:assert/strict";
+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";
+const server = await preview({
+  root: "frontend",
+  preview: { host: "127.0.0.1", port: 4173, strictPort: true },
+});
+const browser = await chromium.launch({ headless: true });
+try {
+  const page = await browser.newPage();
+  const external: string[] = [];
+  await page.route("**/*", (route) => {
+    if (new URL(route.request().url()).origin !== "http://127.0.0.1:4173") {
+      external.push(route.request().url());
+      return route.abort();
+    }
+    return route.continue();
+  });
+  await page.routeWebSocket(/.*/, (socket) => {
+    external.push(socket.url());
+    socket.close();
+  });
+  await page.goto("http://127.0.0.1:4173");
+  await page.waitForFunction(
+    () => typeof (window as any).runOfflineExample === "function",
+  );
+  const browserResult = await page.evaluate(() =>
+    (window as any).runOfflineExample(),
+  );
+  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),
+  );
+  for (const [key, node] of Object.entries({ deploy, transfer })) {
+    assert.deepEqual(
+      JSON.parse(browserResult[key].psktTransactionJson),
+      JSON.parse(node.psktTransactionJson),
+    );
+    assert.deepEqual(browserResult[key].signInputs, node.signInputs);
+    assert.deepEqual(browserResult[key].scripts, node.scripts);
+  }
+  const all = await recipeFixtures(wasm, loadArtifact);
+  for (const name of Object.keys(recipes) as (keyof typeof recipes)[]) {
+    const nodeResult = await all.build(all.operation(name));
+    const browserRecipe = await page.evaluate(
+      (name) => (window as any).runOfflineRecipe(name),
+      name,
+    );
+    assert.deepEqual(
+      JSON.parse(browserRecipe.psktTransactionJson),
+      JSON.parse(nodeResult.psktTransactionJson),
+      name,
+    );
+    assert.deepEqual(browserRecipe.scripts, nodeResult.scripts, name);
+    assert.deepEqual(browserRecipe.signInputs, nodeResult.signInputs, name);
+  }
+  assert.deepEqual(external, []);
+  await page
+    .getByRole("button", { name: "Build offline deploy and transfer" })
+    .click();
+  await page.waitForFunction(
+    () => document.querySelector("#status")?.textContent === "Complete",
+  );
+  assert.equal(await page.locator("#sign").isDisabled(), true);
+  assert.equal(await page.locator("#broadcast").isDisabled(), true);
+  await page.evaluate(`window.kasware = {
+    getNetwork: async () => 'kaspa_testnet_10',
+    requestAccounts: async () => [${JSON.stringify(data.wallet.walletAddress)}],
+    getPublicKey: async () => ${JSON.stringify("02" + owner)},
+    signPskt: async () => { throw new Error('Preparing an operation must not sign'); }
+  }`);
+  await page
+    .getByRole("button", { name: "Prepare deploy from KasWare account" })
+    .click();
+  await page.waitForFunction(
+    () =>
+      (document.querySelector("#operation") as HTMLTextAreaElement).value
+        .length > 0,
+  );
+  const prepared = JSON.parse(await page.locator("#operation").inputValue());
+  assert.equal(prepared.payload.owner.kcc20Owner, owner);
+  assert.equal(prepared.payload.signing.builderKey, "kcc20.deploy-token");
+  assert.equal(await page.locator("#sign").isDisabled(), true);
+  await page
+    .getByRole("button", { name: "Build offline recipe", exact: true })
+    .click();
+  await page.waitForFunction(
+    () => document.querySelector("#status")?.textContent === "Complete",
+  );
+  assert.equal(await page.locator("#sign").isDisabled(), true);
+  assert.equal(await page.locator("#broadcast").isDisabled(), true);
+  await page.screenshot({
+    path: "/tmp/kcc20-public-examples.png",
+    fullPage: false,
+  });
+  console.log(
+    "Browser/Node all 24 recipes are identical; no external requests; offline signing disabled.",
+  );
+} finally {
+  await browser.close();
+  await new Promise<void>((resolve, reject) =>
+    server.httpServer.close((error) => (error ? reject(error) : resolve())),
+  );
+}

package/examples/test/build.test.ts

@@ -0,0 +1,197 @@
+import { recipes } from "../shared/recipes.ts";
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { runtime, loadArtifact } from "../backend/runtime.ts";
+import {
+  createBuilder,
+  deployOperation,
+  transferOperation,
+  engineInput,
+  inspect,
+  type Runtime,
+} from "../shared/build.ts";
+import { fixture, recipient } from "../shared/fixture.ts";
+import { attachScripts, signingInputs } from "../shared/signing.ts";
+const wasm = await runtime();
+// Offline construction must not silently fall back to any backend or RPC.
+globalThis.fetch = async () => {
+  throw new Error("Network access forbidden in offline examples");
+};
+
+test("build deploy and transfer with actual WASM, covenant bindings, amounts and change", async () => {
+  const data = fixture(wasm);
+  const build = createBuilder(
+    Object.freeze({ ...wasm }),
+    data.sources,
+    loadArtifact,
+  );
+  const deploy = await build(deployOperation(data.wallet));
+  const deployTx = JSON.parse(deploy.psktTransactionJson);
+  assert.equal(deployTx.version, 1);
+  assert.equal(
+    deployTx.outputs[0].covenant.covenantId,
+    deploy.metadata.covenantId,
+  );
+  const holder = data.addDeploy(deploy);
+  const transfer = await build(
+    transferOperation(data.wallet, holder, recipient),
+  );
+  const tx = JSON.parse(transfer.psktTransactionJson);
+  assert.equal(tx.inputs.length, 2);
+  assert.equal(tx.outputs.length, 3);
+  assert.equal(tx.outputs[0].covenant.covenantId, deploy.metadata.covenantId);
+  assert.equal(
+    transfer.metadata.tokenAmount ?? transfer.metadata.transferAmount,
+    "1250",
+  );
+  assert(BigInt(inspect(transfer).feeSompi) > 0n);
+  assert.equal(tx.inputs[0].transactionId, holder.txidHex);
+  assert.equal(signingInputs(transfer).length, 2);
+  // Exercise script assembly with a synthetic signature only, never submit.
+  for (const input of tx.inputs)
+    input.signatureScript = "41" + "11".repeat(64) + "01";
+  const signed = JSON.parse(attachScripts(wasm, JSON.stringify(tx), transfer));
+  assert(signed.inputs[0].signatureScript.length > 132);
+  assert.equal(signed.inputs[1].signatureScript, tx.inputs[1].signatureScript);
+  tx.outputs[0].value = (BigInt(tx.outputs[0].value) + 1n).toString();
+  assert.throws(
+    () => attachScripts(wasm, JSON.stringify(tx), transfer),
+    /changed the transaction intent/,
+  );
+});
+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 operation = deployOperation(data.wallet);
+  const deploy = await build(operation);
+  const holder = data.addDeploy(deploy);
+  const transfer = transferOperation(data.wallet, holder, recipient);
+  data.rows.delete(holder.address);
+  await assert.rejects(build(transfer), /not found/);
+  data.rows.clear();
+  await assert.rejects(build(operation), /funding|UTXO|insufficient/i);
+  assert.throws(
+    () =>
+      engineInput({
+        ...operation,
+        payload: { ...operation.payload, network: "mainnet" },
+      }),
+    /testnet-10/,
+  );
+  assert.throws(
+    () =>
+      transferOperation(
+        data.wallet,
+        { ...holder, state: { ...holder.state, ownerIdentifier: recipient } },
+        recipient,
+      ),
+    /holder UTXO/,
+  );
+  await assert.rejects(
+    createBuilder(wasm, fixture(wasm).sources, async () => ({
+      script: [1, 2],
+    }))(operation),
+    /hash mismatch/,
+  );
+  assert.throws(
+    () => createBuilder({} 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 holder = data.addDeploy(await build(deployOperation(data.wallet)));
+  const operation = transferOperation(data.wallet, holder, recipient);
+  const entry = data.rows.get(holder.address)![0];
+  entry.covenantId = "ff".repeat(32);
+  await assert.rejects(build(operation), /covenant id does not match/);
+  delete entry.covenantId;
+  await assert.rejects(build(operation), /missing covenant id/);
+  entry.covenantId = holder.covenantId;
+  const aliasedOperation = recipes.transfer(
+    data.wallet,
+    {
+      token: { covenantId: "ff".repeat(32), decimals: 2 },
+      activeUtxos: [{ ...holder, covenantId: undefined }],
+      recipientOwner: recipient,
+      tokenAmount: "1.00",
+    },
+    { network: "testnet-10" },
+  );
+  assert.equal(
+    aliasedOperation.payload.params.activeHolderNativeCovenantId,
+    undefined,
+  );
+  const aliased = await build(aliasedOperation);
+  assert.equal(aliased.metadata.covenantId, holder.covenantId);
+});
+
+test("preserve witnesses outside requested signing inputs and reject malformed signatures", async () => {
+  const data = fixture(wasm);
+  const build = createBuilder(wasm, data.sources, loadArtifact);
+  const deploy = await build(deployOperation(data.wallet));
+  const holder = data.addDeploy(deploy);
+  const transfer = await build(
+    transferOperation(data.wallet, holder, recipient),
+  );
+  // Model a pre-authorized covenant input: the wallet must sign funding only.
+  const original = JSON.parse(transfer.psktTransactionJson);
+  original.inputs[0].signatureScript = "0101";
+  const preauthorized = {
+    ...transfer,
+    scripts: [],
+    psktTransactionJson: JSON.stringify(original),
+  };
+  original.inputs[1].signatureScript = "41" + "11".repeat(64) + "01";
+  assert.equal(
+    JSON.parse(attachScripts(wasm, JSON.stringify(original), preauthorized))
+      .inputs[0].signatureScript,
+    "0101",
+  );
+  original.inputs[0].signatureScript = "";
+  assert.throws(
+    () => attachScripts(wasm, JSON.stringify(original), preauthorized),
+    /changed the transaction intent/,
+  );
+  for (const signatureScript of [
+    "00",
+    "41" + "11".repeat(64) + "02",
+    "11".repeat(65),
+  ]) {
+    const tx = JSON.parse(deploy.psktTransactionJson);
+    tx.inputs[0].signatureScript = signatureScript;
+    assert.throws(
+      () => attachScripts(wasm, JSON.stringify(tx), deploy),
+      /signature encoding or sighash/,
+    );
+  }
+});
+
+test("generic transfer rejects conflicting RPC scripts and KAS amounts", async () => {
+  const data = fixture(wasm),
+    build = createBuilder(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];
+  const originalScript = row.scriptPublicKey;
+  row.scriptPublicKey = wasm.payToAddressScript(data.wallet.walletAddress);
+  await assert.rejects(build(operation), /RPC script does not match/);
+  row.scriptPublicKey = originalScript;
+  row.amount += 1n;
+  await assert.rejects(build(operation), /KAS amount does not match/);
+});
+
+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(
+      wasm,
+      data.sources,
+      loadArtifact,
+    )(deployOperation(data.wallet)),
+    /no single funding UTXO can cover/,
+  );
+});

package/examples/test/recipes.test.ts

@@ -0,0 +1,59 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { runtime, loadArtifact } from "../backend/runtime.ts";
+import { recipeFixtures } from "../shared/recipe-fixtures.ts";
+import { inspect } from "../shared/build.ts";
+import { recipes } from "../shared/recipes.ts";
+import { attachScripts, signingInputs } from "../shared/signing.ts";
+import { owner } from "../shared/fixture.ts";
+const wasm = await runtime();
+const fixture = await recipeFixtures(wasm, loadArtifact);
+for (const name of Object.keys(recipes) as (keyof typeof recipes)[]) {
+  test(`${name}: helper to unsigned transaction to offline signing`, async () => {
+    const operation = fixture.operation(name);
+    const result = await fixture.build(operation);
+    assert.equal(
+      result.metadata.builderKey,
+      operation.payload.signing.builderKey,
+    );
+    assert(BigInt(inspect(result).feeSompi) > 0n);
+    const tx = wasm.Transaction.deserializeFromSafeJSON(
+      result.psktTransactionJson,
+    );
+    // Public generator test vectors (scalars 1 and 2), never funded wallets.
+    const scalar = operation.payload.owner.kcc20Owner === owner ? 1n : 2n;
+    const key = new wasm.PrivateKey(scalar.toString(16).padStart(64, "0"));
+    for (const input of signingInputs(result)) {
+      assert.equal(input.sighashType, 1); // Wire SIGHASH_ALL byte; WASM enum All is 0.
+      tx.inputs[input.index].signatureScript = wasm.createInputSignature(
+        tx,
+        input.index,
+        key,
+        wasm.SighashType.All,
+      );
+    }
+    const signed = JSON.parse(
+      attachScripts(wasm, tx.serializeToSafeJSON(), result),
+    );
+    assert(
+      signed.inputs.every(
+        (input: { signatureScript: string }) =>
+          input.signatureScript.length > 0,
+      ),
+    );
+    if (name === "publicMint") {
+      assert.equal(result.scripts?.length ?? 0, 0);
+      assert(
+        JSON.parse(result.psktTransactionJson).inputs[0].signatureScript
+          .length > 100,
+      );
+      signed.inputs[0].signatureScript = "";
+      assert.throws(
+        () => attachScripts(wasm, JSON.stringify(signed), result),
+        /changed the transaction intent/,
+      );
+    }
+    key.free();
+    tx.free();
+  });
+}

package/examples/test/sources.test.ts

@@ -0,0 +1,73 @@
+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 { fixture, recipient } from "../shared/fixture.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 holder = data.addDeploy(await build(deployOperation(data.wallet)));
+  const config = {
+    network,
+    stateUrl: "https://indexer.example/holders",
+    wallet: data.wallet,
+    covenantId: holder.covenantId!,
+    decimals: 2,
+    recipientOwner: recipient,
+    tokenAmount: "12.50",
+  } as const;
+  const document = { network, utxos: [holder] };
+  const fetcher: typeof fetch = async () =>
+    new Response(JSON.stringify(document), { status: 200 });
+  return { data, build, config, document, fetcher, holder };
+}
+test("decoded endpoint data and RPC produce a real unsigned transfer", async () => {
+  const { data, build, config, fetcher } = await setup();
+  const operation = await liveTransferOperation(
+    wasm,
+    data.sources,
+    loadArtifact,
+    config,
+    fetcher,
+  );
+  const result = await build(operation);
+  assert.equal(result.metadata.tokenAmount, "1250");
+  assert.equal(result.metadata.covenantId, config.covenantId);
+});
+for (const failure of [
+  "network",
+  "spent",
+  "amount",
+  "identity",
+  "script",
+  "state",
+  "duplicate",
+  "decimals",
+  "owner",
+] as const) {
+  test(`reject invalid live transfer source: ${failure}`, async () => {
+    const { data, config, document, fetcher, holder } = await setup();
+    const row = data.rows.get(holder.address)![0];
+    if (failure === "network") document.network = "mainnet";
+    if (failure === "spent") data.rows.delete(holder.address);
+    if (failure === "amount") row.amount += 1n;
+    if (failure === "identity") row.covenantId = "ff".repeat(32);
+    if (failure === "script")
+      row.scriptPublicKey = wasm.payToAddressScript(data.wallet.walletAddress);
+    if (failure === "state")
+      holder.state!.extensionCommitment = "ff".repeat(32);
+    if (failure === "duplicate") document.utxos.push(holder);
+    const input = {
+      ...config,
+      ...(failure === "decimals" ? { decimals: 9 } : {}),
+      ...(failure === "owner"
+        ? { wallet: { ...config.wallet, kcc20Owner: recipient } }
+        : {}),
+    };
+    await assert.rejects(
+      liveTransferOperation(wasm, data.sources, loadArtifact, input, fetcher),
+    );
+  });
+}

package/examples/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "lib": [
+      "ES2022",
+      "DOM"
+    ],
+    "types": [
+      "node",
+      "vite/client"
+    ]
+  },
+  "include": [
+    "shared/**/*.ts",
+    "backend/**/*.ts",
+    "frontend/**/*.ts",
+    "test/**/*.ts"
+  ]
+}

package/examples/vendor/NOTICE.md

@@ -0,0 +1,15 @@
+# Bundled WASM runtime
+
+`kaspa/` contains the unmodified `kaspa-wasm` 1.1.1-toc.1 JavaScript, declarations,
+and WASM bundle from `KASPACOM/kaspa-covenants` commit
+`acd14ce0862d7dc87f5c15c93de07df844120303`, path
+`wallet-lab/vendor/kaspa-wasm-toc`. Copyright Kaspa developers; ISC license
+retained in `kaspa/LICENSE`.
+
+Upstream project: https://github.com/kaspanet/rusty-kaspa.
+The exact upstream source/build commit is not recorded in the supplied bundle.
+See `docs/COMPATIBILITY.json` for file hashes; these pin the tested distribution,
+not a claim that an upstream release builds the identical binary.
+
+The TX Builder and example application code use the package's Apache-2.0 license.
+Vendored runtime code retains its own license.

package/examples/vendor/kaspa/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2022-2024 Kaspa developers
+
+Permission to use, copy, modify, and distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.