@kaspacom/kcc20-tx-builder 0.1.0

package/src/artifacts.ts

@@ -0,0 +1,87 @@
+import { Kcc20BuilderError } from "./errors.js";
+import type { ArtifactDescriptor, BuildContext } from "./models.js";
+import { sha256 } from "@noble/hashes/sha256";
+
+export const KCC20_ARTIFACT_SCRIPT_SHA256 = Object.freeze({
+  "KCC20.placeholder.json":
+    "4633b082f26adbf14600b767d6e2146e36ce67d63d8202c0281857922c05ac41",
+  "KCC20FeeTicket.placeholder.json":
+    "ed81365466ee4c44db1210b3360783af8145f74e49e847848195e09c71ad6930",
+  "KCC20Orderbook.placeholder.json":
+    "ef9fe81ff7aa2dc2df118d8d7cc126aca6f2f9c181b9c2d15727a538b23c6f71",
+  "KCC20Wrapper.placeholder.json":
+    "f3bdf09be9aa258708a306283a4278a93cfb64f35fc50ed7d316b9b189ef9030",
+  "KCC20Vesting.placeholder.json":
+    "1b84d74aa01b6a50edbff5bf1f9e988a5a6a00ec645458dfd3912ac532b77c33",
+});
+
+export type Kcc20ArtifactKey = keyof typeof KCC20_ARTIFACT_SCRIPT_SHA256;
+
+export function isKcc20ArtifactKey(value: string): value is Kcc20ArtifactKey {
+  return Object.prototype.hasOwnProperty.call(
+    KCC20_ARTIFACT_SCRIPT_SHA256,
+    value,
+  );
+}
+
+export function assertKcc20ArtifactScriptHash(
+  key: Kcc20ArtifactKey,
+  artifact: unknown,
+): void {
+  const script = (artifact as { script?: unknown } | null)?.script;
+  const bytes =
+    script instanceof Uint8Array
+      ? script
+      : Array.isArray(script) &&
+          script.every(
+            (byte) => Number.isInteger(byte) && byte >= 0 && byte <= 0xff,
+          )
+        ? Uint8Array.from(script)
+        : null;
+  if (!bytes) {
+    throw new Kcc20BuilderError(
+      "ARTIFACT_MISMATCH",
+      `contract artifact script is invalid for ${key}`,
+      { artifactKey: key },
+    );
+  }
+  const actualHash = [...sha256(bytes)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+  const expectedHash = KCC20_ARTIFACT_SCRIPT_SHA256[key];
+  if (actualHash !== expectedHash) {
+    throw new Kcc20BuilderError(
+      "ARTIFACT_MISMATCH",
+      `contract artifact hash mismatch for ${key}`,
+      { artifactKey: key, expectedHash, actualHash },
+    );
+  }
+}
+
+export function requireArtifact(
+  context: BuildContext,
+  key: string,
+): ArtifactDescriptor {
+  const artifact = context.artifacts[key];
+  if (!artifact) {
+    throw new Kcc20BuilderError(
+      "ARTIFACT_MISMATCH",
+      `required contract artifact is missing: ${key}`,
+      { artifactKey: key },
+    );
+  }
+  return artifact;
+}
+
+export function assertArtifactHash(
+  artifact: ArtifactDescriptor,
+  expectedHash: string,
+): void {
+  if (artifact.hash.toLowerCase() !== expectedHash.toLowerCase()) {
+    throw new Kcc20BuilderError(
+      "ARTIFACT_MISMATCH",
+      `contract artifact hash mismatch for ${artifact.key}`,
+      { artifactKey: artifact.key, expectedHash, actualHash: artifact.hash },
+    );
+  }
+}

package/src/builder.ts

@@ -0,0 +1,37 @@
+import { Kcc20BuilderError } from "./errors.js";
+import { createKcc20PsktBuilderEngine } from "./engine.js";
+import type { Kcc20PsktBuilderDependencies } from "./models.js";
+
+export const KCC20_PSKT_BUILDER_INPUT_SCHEMA =
+  "kcc20-in-process-pskt-builder-input/v1" as const;
+
+export async function buildKcc20Pskt(
+  dependencies: Kcc20PsktBuilderDependencies,
+  request: Kcc20PsktBuilderInput,
+): Promise<Record<string, unknown>> {
+  if (request.schema !== KCC20_PSKT_BUILDER_INPUT_SCHEMA) {
+    throw new Kcc20BuilderError(
+      "INVALID_INPUT",
+      `unsupported KCC20 builder input schema: ${String(request.schema || "missing")}`,
+    );
+  }
+  const engine = createKcc20PsktBuilderEngine({
+    wasm: dependencies.wasm,
+    artifacts: dependencies.artifacts ?? {},
+    artifactProvider: dependencies.artifactProvider,
+    config: dependencies.config,
+    sourceProvider: dependencies.sourceProvider,
+    rpcClientFactory: dependencies.rpcClientFactory,
+  });
+  return engine.build(request);
+}
+
+export interface Kcc20PsktBuilderInput {
+  schema: typeof KCC20_PSKT_BUILDER_INPUT_SCHEMA;
+  schemaVersion?: number;
+  builder: Record<string, unknown>;
+  request: Record<string, unknown>;
+}
+
+/** @deprecated Use Kcc20PsktBuilderInput. */
+export type Kcc20LegacyPsktBuilderInput = Kcc20PsktBuilderInput;

package/src/deploy-operation.ts

@@ -0,0 +1,458 @@
+import {
+  DEFAULT_KCC20_FEE_BPS,
+  DEFAULT_KCC20_MIN_PROTOCOL_FEE_SOMPI,
+  DEFAULT_KCC20_TOKEN_DECIMALS,
+  KCC20_TICKER_MAX_LENGTH,
+  KCC20_TOKEN_NAME_MAX_LENGTH,
+  KCC20_PLATFORM_PROTOCOL_FEE_RECIPIENT,
+} from "./protocol.js";
+import {
+  KCC20_U64_MAX,
+  kcc20DisplayScaleForDecimals,
+  parseKcc20DisplayAmountToBaseUnits,
+} from "./token-amount.js";
+import { kcc20PaidMintCapacityMeetsMinimumGross } from "./paid-mint-amount.js";
+import { buildKcc20WalletOperationFromPlan } from "./wallet-operation.js";
+
+const HEX_64_RE = /^[a-fA-F0-9]{64}$/;
+const KASPA_ADDRESS_CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
+const KASPA_ADDRESS_GENERATORS = [
+  0x98f2bc8e61n,
+  0x79b76d99e2n,
+  0xf33e5fb3c4n,
+  0xae2eabe2a8n,
+  0x1e4f43e470n,
+];
+
+export interface Kcc20DeployTokenDraft {
+  ticker?: string;
+  tokenName?: string;
+  maxSupply: string;
+  premintSupply: string;
+  decimals?: number;
+  premintRecipient?: string;
+  mintPolicy: "fixed" | "controlled" | "public";
+  mintLaneCount?: number;
+  mintPricePerTokenSompi: string;
+  treasuryRecipient?: string;
+}
+
+export interface Kcc20DeployWalletInfo {
+  walletAddress: string;
+  kcc20Owner: string;
+}
+
+export interface Kcc20DeployOperationOptions {
+  network?: string;
+  protocolFeeRecipient?: string;
+  protocolFeeBps?: number | string | bigint;
+  createdAt?: string;
+  requestId?: string;
+}
+
+export interface Kcc20ValidatedDeployToken {
+  ticker: string;
+  tokenName: string;
+  maxSupply: bigint;
+  premintSupply: bigint;
+  decimals: number;
+  premintRecipient: string;
+  mintPricePerTokenSompi: bigint;
+  mintPolicy: number;
+  treasuryRecipient: string;
+  protocolFeeRecipient: string;
+  protocolFeeBps: number;
+  mintLaneCount?: number;
+}
+
+export function buildKcc20DeployTokenOperation(
+  walletInfo: Kcc20DeployWalletInfo,
+  draft: Kcc20DeployTokenDraft,
+  options: Kcc20DeployOperationOptions = {},
+) {
+  const validated = validateKcc20DeployToken(walletInfo, draft, options);
+  return buildKcc20DeployTokenOperationFromValidated(
+    walletInfo,
+    draft,
+    validated,
+    options,
+  );
+}
+
+export function buildKcc20DeployTokenOperationFromValidated(
+  walletInfo: Kcc20DeployWalletInfo,
+  draft: Kcc20DeployTokenDraft,
+  validated: Kcc20ValidatedDeployToken,
+  options: Kcc20DeployOperationOptions = {},
+) {
+  const requestId =
+    options.requestId ?? `kcc20-deploy-token-${randomOperationId()}`;
+  const network = options.network ?? "testnet-10";
+  const builderKey = "kcc20.deploy-token";
+  const params = {
+    ticker: validated.ticker,
+    tokenName: validated.tokenName,
+    maxSupply: validated.maxSupply.toString(),
+    premintSupply: validated.premintSupply.toString(),
+    decimals: validated.decimals,
+    displayMaxSupply: draft.maxSupply,
+    displayPremintSupply: draft.premintSupply,
+    mintPolicy: draft.mintPolicy,
+    mintPolicyValue: validated.mintPolicy,
+    mintPricePerTokenSompi: validated.mintPricePerTokenSompi.toString(),
+    creator: walletInfo.kcc20Owner,
+    premintRecipient: validated.premintRecipient,
+    premintOwnerScheme: 0,
+    treasuryRecipient: validated.treasuryRecipient,
+    protocolFeeRecipient: validated.protocolFeeRecipient,
+    protocolFeeBps: validated.protocolFeeBps,
+    ...(validated.mintLaneCount == null
+      ? {}
+      : { mintLaneCount: validated.mintLaneCount }),
+    deployTemplate: deployTemplate(walletInfo, validated),
+  };
+  const sourceRequirements = [
+    {
+      type: "kaspa-funding-utxo",
+      ownerAddress: walletInfo.walletAddress,
+      purpose: "fund deploy outputs and network fee",
+    },
+  ];
+  const signerRequirements = [
+    {
+      type: "wallet-owner",
+      owner: walletInfo.kcc20Owner,
+      address: walletInfo.walletAddress,
+    },
+  ];
+
+  return buildKcc20WalletOperationFromPlan(
+    walletInfo,
+    {
+      builderKey,
+      operation: "deploy-token",
+      contract: "KCC20",
+      action: "deploy",
+      description: "Build a KCC20 deploy transaction request.",
+      params,
+      sourceRequirements,
+      signerRequirements,
+      warnings: [
+        "The wallet must build the standard KCC20 transaction, attach genesis covenant bindings, sign, and broadcast.",
+        "Live submission remains wallet-side.",
+      ],
+    },
+    { ...options, requestId, network },
+  );
+}
+
+export function validateKcc20DeployToken(
+  walletInfo: Kcc20DeployWalletInfo,
+  draft: Kcc20DeployTokenDraft,
+  options: Kcc20DeployOperationOptions = {},
+): Kcc20ValidatedDeployToken {
+  const decimals = draft.decimals ?? DEFAULT_KCC20_TOKEN_DECIMALS;
+  const displayScale = kcc20DisplayScaleForDecimals(decimals);
+  const ticker = normalizeKcc20Ticker(draft.ticker);
+  const tokenName = normalizeKcc20TokenName(draft.tokenName);
+  const maxSupply = BigInt(
+    parseKcc20DisplayAmountToBaseUnits(draft.maxSupply, decimals, "maxSupply"),
+  );
+  const premintSupply = BigInt(
+    parseKcc20DisplayAmountToBaseUnits(
+      draft.premintSupply,
+      decimals,
+      "premintSupply",
+      {
+        allowZero: true,
+      },
+    ),
+  );
+  const mintPricePerTokenSompi = parseKcc20U64(
+    draft.mintPricePerTokenSompi,
+    "mintPricePerTokenSompi",
+  );
+  const mintPolicy = { fixed: 0, controlled: 1, public: 2 }[draft.mintPolicy];
+  if (mintPolicy === undefined) {
+    throw new Error("mintPolicy is invalid");
+  }
+  const mintLaneCount = draft.mintLaneCount ?? 10;
+  if (
+    !Number.isInteger(mintLaneCount) ||
+    mintLaneCount < 1 ||
+    mintLaneCount > 10
+  ) {
+    throw new Error("mintLaneCount must be 1..10");
+  }
+  if (!HEX_64_RE.test(walletInfo.kcc20Owner)) {
+    throw new Error("wallet owner must be 64 hex");
+  }
+  if (maxSupply <= 0n) {
+    throw new Error("maxSupply must be greater than zero");
+  }
+  if (premintSupply > maxSupply) {
+    throw new Error("premintSupply cannot exceed maxSupply");
+  }
+  if (mintPolicy === 0 && premintSupply !== maxSupply) {
+    throw new Error("fixed deploys must premint the full maxSupply");
+  }
+  if (mintPolicy !== 0 && premintSupply === maxSupply) {
+    throw new Error(
+      "controlled/public mint deploys must leave remaining mint supply",
+    );
+  }
+  if (mintPolicy !== 2 && mintPricePerTokenSompi > 0n) {
+    throw new Error("mintPricePerTokenSompi is only valid for public deploys");
+  }
+  if (
+    mintPolicy === 2 &&
+    mintPricePerTokenSompi > 0n &&
+    !kcc20PaidMintCapacityMeetsMinimumGross({
+      remainingTokenAmount: maxSupply - premintSupply,
+      unitPriceSompi: mintPricePerTokenSompi,
+      priceScale: displayScale,
+      minimumGrossSompi: DEFAULT_KCC20_MIN_PROTOCOL_FEE_SOMPI,
+    })
+  ) {
+    throw new Error(
+      "public deploys with a mint price must leave enough mintable supply to satisfy the minimum protocol fee",
+    );
+  }
+  if (mintPolicy !== 0 && maxSupply - premintSupply < BigInt(mintLaneCount)) {
+    throw new Error("remaining mint supply must cover every mint lane");
+  }
+  const premintRecipientInput = draft.premintRecipient?.trim();
+  if (premintRecipientInput && (mintPolicy === 0 || premintSupply === 0n)) {
+    throw new Error(
+      "premintRecipient is only valid when controlled/public mint deploys create a premint holder output",
+    );
+  }
+
+  const protocolFeeRecipient =
+    normalizeOptionalOwner(
+      options.protocolFeeRecipient,
+      "protocolFeeRecipient",
+    ) ?? KCC20_PLATFORM_PROTOCOL_FEE_RECIPIENT;
+  const protocolFeeBps = Number(
+    options.protocolFeeBps ?? DEFAULT_KCC20_FEE_BPS,
+  );
+  if (
+    !Number.isSafeInteger(protocolFeeBps) ||
+    protocolFeeBps < 0 ||
+    protocolFeeBps > 10_000
+  ) {
+    throw new Error("protocolFeeBps must be an integer between 0 and 10000");
+  }
+
+  return {
+    ticker,
+    tokenName,
+    maxSupply,
+    premintSupply,
+    decimals,
+    mintPolicy,
+    mintPricePerTokenSompi,
+    premintRecipient:
+      normalizeOptionalOwner(premintRecipientInput, "premintRecipient") ??
+      walletInfo.kcc20Owner,
+    treasuryRecipient:
+      normalizeOptionalOwner(draft.treasuryRecipient, "treasuryRecipient") ??
+      walletInfo.kcc20Owner,
+    protocolFeeRecipient,
+    protocolFeeBps,
+    mintLaneCount: mintPolicy === 0 ? 1 : mintLaneCount,
+  };
+}
+
+function deployTemplate(
+  walletInfo: Kcc20DeployWalletInfo,
+  validated: Kcc20ValidatedDeployToken,
+) {
+  return {
+    tmpl: "KCC20",
+    v: 1,
+    args: [
+      { name: "creator", type: "byte[32]", value: walletInfo.kcc20Owner },
+      { name: "maxSupply", type: "u64", value: validated.maxSupply.toString() },
+      {
+        name: "premintSupply",
+        type: "u64",
+        value: validated.premintSupply.toString(),
+      },
+      {
+        name: "premintRecipient",
+        type: "byte[32]",
+        value: validated.premintRecipient,
+      },
+      { name: "premintOwnerScheme", type: "u64", value: "0" },
+      { name: "mintPolicy", type: "u64", value: String(validated.mintPolicy) },
+      ...(validated.mintLaneCount == null
+        ? []
+        : [
+            {
+              name: "mintLaneCount",
+              type: "u64",
+              value: String(validated.mintLaneCount),
+            },
+          ]),
+      {
+        name: "displayScale",
+        type: "u64",
+        value: kcc20DisplayScaleForDecimals(validated.decimals).toString(),
+      },
+      {
+        name: "mintPriceSompi",
+        type: "u64",
+        value: validated.mintPricePerTokenSompi.toString(),
+      },
+      {
+        name: "treasury",
+        type: "byte[32]",
+        value: validated.treasuryRecipient,
+      },
+      {
+        name: "protocolFeeRecipient",
+        type: "byte[32]",
+        value: validated.protocolFeeRecipient,
+      },
+      {
+        name: "protocolFeeBps",
+        type: "u64",
+        value: String(validated.protocolFeeBps),
+      },
+      { name: "ticker", type: "string", value: validated.ticker },
+      { name: "name", type: "string", value: validated.tokenName },
+    ],
+  };
+}
+
+export function normalizeKcc20Ticker(value: string | undefined): string {
+  const normalized = String(value ?? "")
+    .trim()
+    .toUpperCase();
+  if (!normalized) return "";
+  if (
+    !new RegExp(`^[A-Z0-9]{1,${KCC20_TICKER_MAX_LENGTH}}$`).test(normalized)
+  ) {
+    throw new Error(
+      `ticker must be 1-${KCC20_TICKER_MAX_LENGTH} uppercase alphanumeric characters`,
+    );
+  }
+  return normalized;
+}
+
+export function normalizeKcc20TokenName(value: string | undefined): string {
+  const normalized = String(value ?? "")
+    .trim()
+    .replace(/\s+/g, " ");
+  if (!normalized) return "";
+  if (normalized.length > KCC20_TOKEN_NAME_MAX_LENGTH) {
+    throw new Error(
+      `tokenName must be ${KCC20_TOKEN_NAME_MAX_LENGTH} characters or fewer`,
+    );
+  }
+  if (!/^[\x20-\x7E]+$/.test(normalized)) {
+    throw new Error("tokenName must be printable ASCII");
+  }
+  return normalized;
+}
+
+export function parseKcc20U64(value: string, field: string): bigint {
+  if (!/^\d+$/.test(value)) {
+    throw new Error(`${field} must be an unsigned integer`);
+  }
+  const parsed = BigInt(value);
+  if (parsed > KCC20_U64_MAX) {
+    throw new Error(`${field} exceeds u64 max`);
+  }
+  return parsed;
+}
+
+function normalizeOptionalOwner(
+  value: string | undefined,
+  field: string,
+): string | undefined {
+  const normalized = value?.trim().toLowerCase();
+  if (!normalized) return undefined;
+  if (HEX_64_RE.test(normalized)) return normalized;
+  const owner = ownerFromKaspaAddress(normalized);
+  if (owner) return owner;
+  throw new Error(`${field} must be a 64 hex owner or Kaspa P2PK address`);
+}
+
+function ownerFromKaspaAddress(value: string): string | undefined {
+  const [prefix, payload, extra] = value.split(":");
+  if (!prefix || !payload || extra !== undefined) return undefined;
+  const data: number[] = [];
+  for (const char of payload) {
+    const index = KASPA_ADDRESS_CHARSET.indexOf(char);
+    if (index === -1) return undefined;
+    data.push(index);
+  }
+  if (
+    data.length <= 8 ||
+    kaspaAddressPolymod(kaspaAddressPrefixExpand(prefix).concat(data)) !== 1n
+  ) {
+    return undefined;
+  }
+  const bytes = convertBits(data.slice(0, -8), 5, 8, false);
+  if (!bytes || bytes.length !== 33) return undefined;
+  const [version, ...ownerBytes] = bytes;
+  if (version !== 0 && version !== 1) return undefined;
+  const owner = bytesToHex(ownerBytes);
+  return HEX_64_RE.test(owner) ? owner : undefined;
+}
+
+function kaspaAddressPrefixExpand(prefix: string): number[] {
+  return [...prefix].map((char) => char.charCodeAt(0) & 0x1f).concat([0]);
+}
+
+function kaspaAddressPolymod(values: number[]): bigint {
+  let checksum = 1n;
+  for (const value of values) {
+    const top = checksum >> 35n;
+    checksum = ((checksum & 0x07ffffffffn) << 5n) ^ BigInt(value);
+    for (let index = 0; index < KASPA_ADDRESS_GENERATORS.length; index += 1) {
+      if (((top >> BigInt(index)) & 1n) === 1n) {
+        checksum ^= KASPA_ADDRESS_GENERATORS[index];
+      }
+    }
+  }
+  return checksum;
+}
+
+function convertBits(
+  data: number[],
+  fromBits: number,
+  toBits: number,
+  pad: boolean,
+): number[] | undefined {
+  let accumulator = 0;
+  let bits = 0;
+  const result: number[] = [];
+  const maxValue = (1 << toBits) - 1;
+  const maxAccumulator = (1 << (fromBits + toBits - 1)) - 1;
+  for (const value of data) {
+    if (value < 0 || value >> fromBits) return undefined;
+    accumulator = ((accumulator << fromBits) | value) & maxAccumulator;
+    bits += fromBits;
+    while (bits >= toBits) {
+      bits -= toBits;
+      result.push((accumulator >> bits) & maxValue);
+    }
+  }
+  if (pad) {
+    if (bits > 0) result.push((accumulator << (toBits - bits)) & maxValue);
+  } else if (bits >= fromBits || (accumulator << (toBits - bits)) & maxValue) {
+    return undefined;
+  }
+  return result;
+}
+
+function bytesToHex(bytes: number[]): string {
+  return bytes.map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function randomOperationId(): string {
+  return globalThis.crypto?.randomUUID?.() ?? `${Date.now().toString(36)}`;
+}

package/src/encoding.ts

@@ -0,0 +1,58 @@
+import { Kcc20BuilderError } from "./errors.js";
+
+export function hexToBytes(value: string, label = "hex value"): Uint8Array {
+  const hex = value.trim().replace(/^0x/i, "");
+  if (!/^(?:[0-9a-f]{2})*$/i.test(hex)) {
+    throw new Kcc20BuilderError(
+      "INVALID_INPUT",
+      `${label} must be an even-length hexadecimal string`,
+    );
+  }
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let index = 0; index < bytes.length; index += 1) {
+    bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+export function bytesToHex(bytes: Uint8Array): string {
+  let result = "";
+  for (const byte of bytes) result += byte.toString(16).padStart(2, "0");
+  return result;
+}
+
+export function requireHex(value: string, byteLength: number, label: string) {
+  const bytes = hexToBytes(value, label);
+  if (bytes.length !== byteLength) {
+    throw new Kcc20BuilderError(
+      "INVALID_INPUT",
+      `${label} must be ${byteLength} bytes`,
+    );
+  }
+  return bytesToHex(bytes);
+}
+
+export function asciiToBytes32(value: string, label = "value"): Uint8Array {
+  const encoded = new TextEncoder().encode(value);
+  if (encoded.length > 32) {
+    throw new Kcc20BuilderError(
+      "INVALID_INPUT",
+      `${label} must be at most 32 UTF-8 bytes`,
+    );
+  }
+  const result = new Uint8Array(32);
+  result.set(encoded);
+  return result;
+}
+
+export function concatByteArrays(...parts: Uint8Array[]): Uint8Array {
+  const result = new Uint8Array(
+    parts.reduce((length, part) => length + part.length, 0),
+  );
+  let offset = 0;
+  for (const part of parts) {
+    result.set(part, offset);
+    offset += part.length;
+  }
+  return result;
+}