@kaspacom/kcc20-tx-builder 0.2.5 → 0.4.0

package/examples/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "kcc20-tx-builder-examples",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "backend": "tsx backend/cli.ts",
+    "frontend": "vite frontend --host 127.0.0.1",
+    "build": "tsc --noEmit && vite build frontend",
+    "test": "tsx --test test/build.test.ts test/recipes.test.ts test/sources.test.ts",
+    "test:browser": "tsx test/browser.ts",
+    "recipe": "tsx backend/recipe.ts"
+  },
+  "dependencies": {
+    "@kaspacom/kcc20-tx-builder": "0.2.5"
+  },
+  "devDependencies": {
+    "@types/node": "22.18.8",
+    "playwright": "1.56.0",
+    "tsx": "4.20.6",
+    "typescript": "5.9.3",
+    "vite": "6.4.4"
+  }
+}

package/examples/shared/build.ts

@@ -0,0 +1,179 @@
+import { withTimeout } from "./timeout.ts";
+import { createKcc20PsktBuilderEngine } from "@kaspacom/kcc20-tx-builder/engine";
+import { buildKcc20DeployTokenOperation } from "@kaspacom/kcc20-tx-builder/deploy-operation";
+import { buildKcc20TransferTokenOperation } from "@kaspacom/kcc20-tx-builder/token-operation";
+import {
+  assertKcc20ArtifactScriptHash,
+  isKcc20ArtifactKey,
+} from "@kaspacom/kcc20-tx-builder/artifacts";
+import type { Kcc20IndexedCovenantUtxo } from "@kaspacom/kcc20-tx-builder/action-source-resolver";
+import type * as Wasm from "../vendor/kaspa/kaspa.js";
+
+export const network = "testnet-10";
+export type Runtime = typeof Wasm;
+export type Wallet = { walletAddress: string; kcc20Owner: string };
+export type Operation = ReturnType<typeof buildKcc20DeployTokenOperation>;
+export type Sources = {
+  getUtxosByAddresses(args: { addresses: string[] }): Promise<unknown>;
+};
+export type ScriptArgument =
+  | { type: "i64"; value: string | number }
+  | { type: "data"; hex: string }
+  | { type: "byte"; value: number }
+  | { type: "signature"; prefixHex?: string };
+export type ScriptHint = {
+  inputIndex: number;
+  scriptHex: string;
+  signType?: number;
+  signatureScript?: {
+    mode: "ordered-args" | "signature-first-args" | "wrap-signature";
+    args?: ScriptArgument[];
+  };
+};
+export type Built = {
+  psktTransactionJson: string;
+  signInputs: { index: number; sighashType: number }[];
+  scripts?: ScriptHint[];
+  metadata: Record<string, any>;
+  submitTransactionSupported: boolean;
+};
+
+// This is application wiring, not a second SDK API.
+export function engineInput(operation: Operation) {
+  const p = operation.payload;
+  if (p.network !== network)
+    throw new Error("These examples require testnet-10");
+  if (!p.owner.walletAddress.startsWith("kaspatest:"))
+    throw new Error("Expected a testnet wallet address");
+  return {
+    schema: "kcc20-in-process-pskt-builder-input/v1",
+    schemaVersion: 1,
+    builder: {
+      builderKey: p.signing.builderKey,
+      operation: p.operation,
+      contract: p.contract,
+      action: p.action,
+      requiredSources: p.sourceRequirements,
+    },
+    request: {
+      builderKey: p.signing.builderKey,
+      operation: p.operation,
+      contract: p.contract,
+      action: p.action,
+      network: p.network,
+      params: p.params,
+      owner: p.owner,
+      requiredSources: p.sourceRequirements,
+      sourceRequirements: p.sourceRequirements,
+      signerRequirements: p.signerRequirements,
+    },
+  };
+}
+
+export function createBuilder(
+  wasm: Runtime,
+  sources: Sources,
+  loadArtifact: (key: string) => Promise<unknown>,
+) {
+  for (const key of [
+    "Transaction",
+    "GenesisCovenantGroup",
+    "TransactionOutput",
+    "payToScriptHashScript",
+  ] as const) {
+    if (typeof wasm[key] !== "function")
+      throw new Error(`Incompatible WASM runtime: missing ${key}`);
+  }
+  const engine = createKcc20PsktBuilderEngine({
+    wasm,
+    artifacts: {},
+    sourceProvider: {
+      getUtxosByAddresses: (args) =>
+        withTimeout(sources.getUtxosByAddresses(args), "UTXO query"),
+    },
+    config: { KASPA_NETWORK: network },
+    artifactProvider: async (key) => {
+      if (!isKcc20ArtifactKey(key))
+        throw new Error(`Unsupported artifact: ${key}`);
+      const artifact = await loadArtifact(key);
+      assertKcc20ArtifactScriptHash(key, artifact);
+      return artifact;
+    },
+  });
+  return async (operation: Operation): Promise<Built> => {
+    const result = await engine.build(engineInput(operation));
+    if (
+      typeof result.psktTransactionJson !== "string" ||
+      !Array.isArray(result.signInputs)
+    )
+      throw new Error("Invalid builder output");
+    return result as Built;
+  };
+}
+
+export function deployOperation(wallet: Wallet) {
+  return buildKcc20DeployTokenOperation(
+    wallet,
+    {
+      ticker: "DEMO",
+      tokenName: "Example token",
+      decimals: 2,
+      maxSupply: "1000",
+      premintSupply: "1000",
+      mintPolicy: "fixed",
+      mintPricePerTokenSompi: "0",
+    },
+    {
+      network,
+      requestId: "example-deploy",
+      createdAt: "2026-01-01T00:00:00.000Z",
+    },
+  );
+}
+
+export function transferOperation(
+  wallet: Wallet,
+  holder: Kcc20IndexedCovenantUtxo,
+  recipientOwner: string,
+  tokenAmount = "12.50",
+) {
+  if (!holder.covenantId) throw new Error("A native covenant ID is required");
+  return buildKcc20TransferTokenOperation(
+    wallet,
+    {
+      token: { covenantId: holder.covenantId, ticker: "DEMO", decimals: 2 },
+      activeUtxos: [holder],
+      recipientOwner,
+      tokenAmount,
+    },
+    {
+      network,
+      requestId: "example-transfer",
+      createdAt: "2026-01-01T00:00:00.000Z",
+    },
+  );
+}
+
+export function inspect(result: Built) {
+  const tx = JSON.parse(result.psktTransactionJson);
+  const inputSompi = tx.inputs.reduce(
+    (n: bigint, input: any) => n + BigInt(input.utxo.amount),
+    0n,
+  );
+  const outputSompi = tx.outputs.reduce(
+    (n: bigint, output: any) => n + BigInt(output.value),
+    0n,
+  );
+  return {
+    operation: result.metadata.builderKey,
+    network: result.metadata.network,
+    inputs: tx.inputs.length,
+    outputs: tx.outputs.length,
+    feeSompi: (inputSompi - outputSompi).toString(),
+    signInputs: result.signInputs,
+    intent:
+      result.metadata.intentOutputs?.map(
+        ({ revealScriptHex, ...intent }: any) => intent,
+      ) ?? null,
+  };
+}

package/examples/shared/fixture.ts

@@ -0,0 +1,24 @@
+import { network, type Runtime, type Wallet, type Built, type Sources } from './build.ts';
+import type { Kcc20IndexedCovenantUtxo } from '@kaspacom/kcc20-tx-builder/action-source-resolver';
+
+// Public secp256k1 generator coordinates, not a wallet intended to receive funds.
+export const owner = '79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798';
+export const recipient = 'c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5';
+export function fixture(wasm: Runtime) {
+  const wallet: Wallet = { kcc20Owner: owner, walletAddress: new wasm.XOnlyPublicKey(owner).toAddress(network).toString() };
+  const rows = new Map<string, any[]>();
+  rows.set(wallet.walletAddress, [{ address: wallet.walletAddress, outpoint: { transactionId: 'ab'.repeat(32), index: 0 }, amount: 100_000_000_000n, scriptPublicKey: wasm.payToAddressScript(wallet.walletAddress), blockDaaScore: 1n, isCoinbase: false }]);
+  const sources: Sources = { async getUtxosByAddresses({ addresses }) { return { entries: addresses.flatMap(address => rows.get(address) ?? []) }; } };
+  function addDeploy(result: Built): Kcc20IndexedCovenantUtxo {
+    const tx = JSON.parse(result.psktTransactionJson);
+    const m = result.metadata;
+    const address = String(m.contractAddress);
+    const index = Number(m.covenantOutputIndex);
+    const output = tx.outputs[index];
+    const txid = 'cd'.repeat(32); // Synthetic, never submitted or asserted to exist on-chain.
+    rows.set(address, [{ address, outpoint: { transactionId: txid, index }, amount: BigInt(output.value), scriptPublicKey: output.scriptPublicKey, covenantId: m.covenantId, blockDaaScore: 1n, isCoinbase: false }]);
+    return { txidHex: txid, vout: index, outpoint: `${txid}:${index}`, address, amountSompi: output.value, covenantId: m.covenantId,
+      state: { ownerIdentifier: owner, ownerScheme: 0, amount: m.maxSupply, extensionCommitment: m.holderExtensionCommitment, borrowScheme: 0, borrowGuard: '00'.repeat(32), isMintAuthority: false } };
+  }
+  return { wallet, sources, rows, addDeploy };
+}

package/examples/shared/live-transfer.ts

@@ -0,0 +1,155 @@
+import { buildKcc20ScriptForState } from "@kaspacom/kcc20-tx-builder/abi";
+import { buildKcc20TransferTokenOperation } from "@kaspacom/kcc20-tx-builder/token-operation";
+import {
+  normalizeKcc20IndexedUtxos,
+  selectOwnerNativeHolderUtxo,
+} from "@kaspacom/kcc20-tx-builder/action-source-resolver";
+import { parseKcc20DisplayAmountToBaseUnits } from "@kaspacom/kcc20-tx-builder/token-amount";
+import { assertKcc20ArtifactScriptHash } from "@kaspacom/kcc20-tx-builder/artifacts";
+import { network, type Runtime, type Sources, type Wallet } from "./build.ts";
+import { withTimeout } from "./timeout.ts";
+
+export interface LiveTransferConfig {
+  network: "testnet-10";
+  stateUrl: string;
+  wallet: Wallet;
+  covenantId: string;
+  decimals: number;
+  recipientOwner: string;
+  tokenAmount: string;
+}
+function bytes(value: unknown, field: string): Uint8Array {
+  if (typeof value !== "string" || !/^[a-f0-9]{64}$/i.test(value))
+    throw new Error(`Invalid ${field}`);
+  return Uint8Array.from(value.match(/../g)!, (x) => parseInt(x, 16));
+}
+// Endpoint response: { network: 'testnet-10', utxos: Kcc20IndexedCovenantUtxo[] }.
+// It supplies decoded state; RPC independently confirms the current output.
+export async function liveTransferOperation(
+  wasm: Runtime,
+  rpc: Sources,
+  loadArtifact: (key: string) => Promise<unknown>,
+  config: LiveTransferConfig,
+  fetcher: typeof fetch = fetch,
+) {
+  if (config.network !== network)
+    throw new Error("Transfer config requires testnet-10");
+  if (
+    !Number.isInteger(config.decimals) ||
+    config.decimals < 0 ||
+    config.decimals > 8
+  )
+    throw new Error("Invalid decimals");
+  bytes(config.covenantId, "native covenant ID");
+  bytes(config.recipientOwner, "recipient owner");
+  bytes(config.wallet.kcc20Owner, "wallet owner");
+  if (
+    new wasm.XOnlyPublicKey(config.wallet.kcc20Owner)
+      .toAddress(network)
+      .toString() !== config.wallet.walletAddress
+  )
+    throw new Error("Wallet address and owner do not match");
+  const url = new URL(config.stateUrl);
+  if (!["http:", "https:"].includes(url.protocol))
+    throw new Error("State URL must use HTTP or HTTPS");
+  const document = await withTimeout(
+    (async () => {
+      const response = await fetcher(url, {
+        signal: AbortSignal.timeout(20_000),
+      });
+      if (!response.ok)
+        throw new Error(`State endpoint returned HTTP ${response.status}`);
+      return await response.json();
+    })(),
+    "Decoded state query",
+  );
+  if (
+    document.network !== network ||
+    !Array.isArray(document.utxos) ||
+    document.utxos.length > 1000
+  )
+    throw new Error("Invalid or wrong-network state response");
+  const rows = normalizeKcc20IndexedUtxos(document.utxos);
+  if (rows.length !== document.utxos.length)
+    throw new Error("State response contains malformed or duplicate outputs");
+  const amount = parseKcc20DisplayAmountToBaseUnits(
+    config.tokenAmount,
+    config.decimals,
+    "tokenAmount",
+  );
+  const holder = selectOwnerNativeHolderUtxo(
+    rows.filter((row) => row.covenantId === config.covenantId),
+    config.wallet.kcc20Owner,
+    amount,
+  );
+  if (!holder?.state)
+    throw new Error("No matching owner holder can cover the transfer");
+  const state = holder.state;
+  if (
+    state.isMintAuthority !== false ||
+    state.ownerScheme !== 0 ||
+    state.borrowScheme !== 0
+  )
+    throw new Error("Expected an unborrowed Schnorr holder");
+  if (
+    typeof state.amount !== "string" ||
+    !/^[0-9]+$/.test(state.amount) ||
+    BigInt(String(state.amount)) <= 0n
+  )
+    throw new Error("Invalid holder token amount");
+  const artifact = await loadArtifact("KCC20.placeholder.json");
+  assertKcc20ArtifactScriptHash("KCC20.placeholder.json", artifact);
+  const script = buildKcc20ScriptForState(artifact, {
+    amount: BigInt(String(state.amount)),
+    owner: bytes(state.ownerIdentifier, "holder owner"),
+    ownerScheme: 0,
+    borrowScheme: 0,
+    borrowGuard: bytes(state.borrowGuard, "borrow guard"),
+    extensionCommitment: bytes(
+      state.extensionCommitment,
+      "extension commitment",
+    ),
+  });
+  const expectedAddress = wasm
+    .addressFromScriptPublicKey(wasm.payToScriptHashScript(script), network)!
+    .toString();
+  if (holder.address !== expectedAddress)
+    throw new Error("Decoded state does not match the holder address");
+  const response = (await withTimeout(
+    rpc.getUtxosByAddresses({ addresses: [holder.address] }),
+    "Holder UTXO query",
+  )) as {
+    entries?: {
+      outpoint: { transactionId: string; index: number };
+      amount: bigint | string;
+      covenantId?: string;
+      scriptPublicKey: Parameters<Runtime["addressFromScriptPublicKey"]>[0];
+    }[];
+  };
+  const current = response.entries?.find(
+    (row) =>
+      String(row.outpoint.transactionId) === holder.txidHex &&
+      row.outpoint.index === holder.vout,
+  );
+  if (!current) throw new Error("Holder is spent or missing from RPC");
+  if (String(current.covenantId) !== config.covenantId)
+    throw new Error("Holder native covenant ID differs from RPC");
+  if (BigInt(current.amount) !== BigInt(holder.amountSompi))
+    throw new Error("Holder KAS amount differs from RPC");
+  if (
+    wasm
+      .addressFromScriptPublicKey(current.scriptPublicKey, network)
+      ?.toString() !== expectedAddress
+  )
+    throw new Error("Holder script differs from RPC");
+  return buildKcc20TransferTokenOperation(
+    config.wallet,
+    {
+      token: { covenantId: config.covenantId, decimals: config.decimals },
+      activeUtxos: [holder],
+      recipientOwner: config.recipientOwner,
+      tokenAmount: config.tokenAmount,
+    },
+    { network },
+  );
+}