@kaspacom/kcc20-tx-builder 0.1.0

package/src/ladder-limit-orders.ts

@@ -0,0 +1,184 @@
+import {
+  calculateKcc20OrderTotalSompi,
+  parseKcc20DisplayAmountToBaseUnits,
+} from "./token-amount.js";
+import {
+  KCC20_MIN_PROTOCOL_FEE_SOMPI,
+  calculateKcc20ProtocolFeeSompi,
+} from "./trade-fee.js";
+
+export const KCC20_LADDER_MAX_ORDERS = 20;
+
+export type Kcc20LadderDirection = "increment" | "decrement";
+
+export interface Kcc20LadderLimitPlan {
+  unitPriceSompi: string[];
+  notionalsSompi: bigint[];
+  minNotionalSompi: bigint;
+  totalNotionalSompi: bigint;
+  totalProtocolFeeSompi: bigint;
+  totalBuySettlementSompi: bigint;
+}
+
+/**
+ * Builds compounded unit prices for a same-amount resting limit-order ladder.
+ */
+export function kcc20LadderUnitPricesSompi(input: {
+  baseUnitPriceSompi: bigint;
+  count: number;
+  direction: Kcc20LadderDirection;
+  percent: number;
+}): bigint[] {
+  const count = Math.min(
+    KCC20_LADDER_MAX_ORDERS,
+    Math.max(1, Math.floor(input.count)),
+  );
+  if (input.baseUnitPriceSompi <= 0n) return [];
+
+  const percent = Number.isFinite(input.percent)
+    ? Math.max(0, input.percent)
+    : 0;
+  const stepPpm = BigInt(Math.round(percent * 10_000));
+  const million = 1_000_000n;
+  const sign = input.direction === "increment" ? 1n : -1n;
+  const prices: bigint[] = [];
+  let current = input.baseUnitPriceSompi;
+
+  for (let index = 0; index < count; index += 1) {
+    if (current <= 0n) break;
+    prices.push(current);
+    if (index === count - 1 || stepPpm === 0n) continue;
+
+    const factor = million + sign * stepPpm;
+    if (factor <= 0n) break;
+    const next = (current * factor + million / 2n) / million;
+    current =
+      next === current
+        ? input.direction === "increment"
+          ? current + 1n
+          : current - 1n
+        : next;
+  }
+  return prices;
+}
+
+export function parseKcc20LadderPercent(value: string): number | undefined {
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  const parsed = Number(trimmed);
+  return Number.isFinite(parsed) && parsed >= 0 && parsed <= 100
+    ? parsed
+    : undefined;
+}
+
+export function planKcc20LadderLimitOrders(input: {
+  tokenAmount: string;
+  baseUnitPriceSompi: string;
+  decimals: number;
+  count: number;
+  direction: Kcc20LadderDirection;
+  percent: number;
+  protocolFeeBps: number;
+}): Kcc20LadderLimitPlan | undefined {
+  let base: bigint;
+  try {
+    base = BigInt(input.baseUnitPriceSompi.trim());
+  } catch {
+    return undefined;
+  }
+  if (base <= 0n) return undefined;
+
+  const prices = kcc20LadderUnitPricesSompi({
+    baseUnitPriceSompi: base,
+    count: input.count,
+    direction: input.direction,
+    percent: input.percent,
+  });
+  const requested = Math.min(
+    KCC20_LADDER_MAX_ORDERS,
+    Math.max(1, Math.floor(input.count)),
+  );
+  if (prices.length !== requested) return undefined;
+
+  const notionalsSompi: bigint[] = [];
+  let totalBuySettlementSompi = 0n;
+  for (const price of prices) {
+    const total = calculateKcc20OrderTotalSompi(
+      input.tokenAmount,
+      price.toString(),
+      input.decimals,
+    );
+    if (!total) return undefined;
+    const notional = BigInt(total.totalSompi);
+    notionalsSompi.push(notional);
+    totalBuySettlementSompi +=
+      notional + calculateKcc20ProtocolFeeSompi(notional, input.protocolFeeBps);
+  }
+  const totalNotionalSompi = notionalsSompi.reduce(
+    (sum, value) => sum + value,
+    0n,
+  );
+  const minNotionalSompi = notionalsSompi.reduce(
+    (min, value) => (value < min ? value : min),
+    notionalsSompi[0],
+  );
+  return {
+    unitPriceSompi: prices.map((price) => price.toString()),
+    notionalsSompi,
+    minNotionalSompi,
+    totalNotionalSompi,
+    totalProtocolFeeSompi: totalBuySettlementSompi - totalNotionalSompi,
+    totalBuySettlementSompi,
+  };
+}
+
+export function kcc20LadderMeetsMinOrderValue(
+  plan: Kcc20LadderLimitPlan,
+  minSompi = KCC20_MIN_PROTOCOL_FEE_SOMPI,
+): boolean {
+  return plan.minNotionalSompi >= minSompi;
+}
+
+export function maxAffordableKcc20LadderCount(input: {
+  side: "buy" | "sell";
+  tokenAmount: string;
+  baseUnitPriceSompi: string;
+  decimals: number;
+  direction: Kcc20LadderDirection;
+  percent: number;
+  protocolFeeBps: number;
+  availableTokenBaseUnits?: bigint;
+  availableKasSompi?: bigint;
+}): number {
+  if (input.side === "sell") {
+    if (input.availableTokenBaseUnits === undefined)
+      return KCC20_LADDER_MAX_ORDERS;
+    let amount: bigint;
+    try {
+      amount = BigInt(
+        parseKcc20DisplayAmountToBaseUnits(
+          input.tokenAmount,
+          input.decimals,
+          "token amount",
+        ),
+      );
+    } catch {
+      return KCC20_LADDER_MAX_ORDERS;
+    }
+    if (amount <= 0n) return KCC20_LADDER_MAX_ORDERS;
+    const affordable = input.availableTokenBaseUnits / amount;
+    if (affordable < 1n) return 1;
+    const asNumber = Number(affordable);
+    return Number.isSafeInteger(asNumber)
+      ? Math.min(KCC20_LADDER_MAX_ORDERS, asNumber)
+      : KCC20_LADDER_MAX_ORDERS;
+  }
+
+  if (input.availableKasSompi === undefined) return KCC20_LADDER_MAX_ORDERS;
+  for (let count = KCC20_LADDER_MAX_ORDERS; count >= 1; count -= 1) {
+    const plan = planKcc20LadderLimitOrders({ ...input, count });
+    if (plan && plan.totalBuySettlementSompi <= input.availableKasSompi)
+      return count;
+  }
+  return 1;
+}

package/src/mint-availability-operation.ts

@@ -0,0 +1,146 @@
+import { buildKcc20WalletOperationFromPlan } from "./wallet-operation.js";
+import type { Kcc20IndexedCovenantUtxo } from "./action-source-resolver.js";
+
+const HEX_64_RE = /^[a-f0-9]{64}$/;
+
+export interface Kcc20MintAvailabilityWalletInfo {
+  walletAddress: string;
+  kcc20Owner: string;
+}
+
+export interface Kcc20BuildMintAvailabilityOperationInput {
+  covenantId: string;
+  active: boolean;
+  activeMinterUtxo: Record<string, unknown>;
+  activeMinterUtxos: Record<string, unknown>[];
+}
+
+export interface Kcc20MintAvailabilityOperationOptions {
+  network?: string;
+  createdAt?: string;
+  requestId?: string;
+}
+
+export function resolveKcc20MintAvailabilitySources(input: {
+  publicMintControlSupported: boolean;
+  activeUtxos: readonly Kcc20IndexedCovenantUtxo[];
+  owner: string;
+  active: boolean;
+}): {
+  activeMinterUtxo: Kcc20IndexedCovenantUtxo;
+  activeMinterUtxos: Kcc20IndexedCovenantUtxo[];
+} {
+  if (!input.publicMintControlSupported) {
+    throw new Error(
+      "This KCC20 token does not support public mint availability updates",
+    );
+  }
+  const activeMinterUtxos = input.activeUtxos.filter(
+    (utxo) =>
+      utxo.state?.["isMintAuthority"] === true &&
+      Number(utxo.state?.["mintPolicy"]) === 2,
+  );
+  const activeMinterUtxo = activeMinterUtxos[0];
+  if (!activeMinterUtxo?.state)
+    throw new Error("Active public minter UTXO not found");
+
+  const state = activeMinterUtxo.state;
+  const owner = String(
+    state["owner"] ?? state["ownerIdentifier"] ?? "",
+  ).toLowerCase();
+  const ownerScheme = Number(state["ownerScheme"] ?? state["identifierType"]);
+  if (ownerScheme !== 0 || owner !== input.owner.toLowerCase()) {
+    throw new Error(
+      "Public mint availability updates require the active minter owner",
+    );
+  }
+  const currentActive = state["publicMintActive"] === true;
+  if (currentActive === input.active) {
+    throw new Error(
+      input.active
+        ? "Public mint is already active"
+        : "Public mint is already paused",
+    );
+  }
+  return { activeMinterUtxo, activeMinterUtxos };
+}
+
+export function buildKcc20MintAvailabilityOperation(
+  walletInfo: Kcc20MintAvailabilityWalletInfo,
+  input: Kcc20BuildMintAvailabilityOperationInput,
+  options: Kcc20MintAvailabilityOperationOptions = {},
+) {
+  const covenantId = requireHex64(input.covenantId, "covenantId");
+  if (typeof input.active !== "boolean") {
+    throw new Error("active must be a boolean");
+  }
+  if (!input.activeMinterUtxo || typeof input.activeMinterUtxo !== "object") {
+    throw new Error("activeMinterUtxo is required");
+  }
+  if (
+    !Array.isArray(input.activeMinterUtxos) ||
+    !input.activeMinterUtxos.length
+  ) {
+    throw new Error("activeMinterUtxos must contain at least one source");
+  }
+  const outpoints = input.activeMinterUtxos.map((utxo) => utxoOutpoint(utxo));
+  const selectedOutpoint = utxoOutpoint(input.activeMinterUtxo);
+
+  return buildKcc20WalletOperationFromPlan(
+    walletInfo,
+    {
+      builderKey: "kcc20.set-public-mint-active",
+      operation: "set-mint-availability",
+      contract: "KCC20",
+      action: "setPublicMintActive",
+      description: "Build a public mint availability update request.",
+      params: {
+        covenantId,
+        active: input.active,
+        activeMinterUtxo: input.activeMinterUtxo,
+        activeMinterUtxos: input.activeMinterUtxos,
+      },
+      sourceRequirements: [
+        {
+          type: "kcc20-mint-authority-utxo",
+          covenantId,
+          outpoint: selectedOutpoint,
+          outpoints,
+          purpose:
+            "preserve remaining supply while updating public mint availability",
+        },
+        {
+          type: "kaspa-funding-utxo",
+          ownerAddress: walletInfo.walletAddress,
+          purpose: "fund network fee",
+        },
+      ],
+      warnings: [],
+      tokenIdentity: {
+        canonicalCovenantId: covenantId,
+        deployCandidateId: covenantId,
+      },
+    },
+    options,
+  );
+}
+
+function utxoOutpoint(utxo: Record<string, unknown>): string {
+  const txidHex = requireHex64(utxo["txidHex"], "minter txid");
+  const vout = Number(utxo["vout"]);
+  if (!Number.isInteger(vout) || vout < 0) {
+    throw new Error("minter vout must be a non-negative integer");
+  }
+  return `${txidHex}:${vout}`;
+}
+
+function requireHex64(value: unknown, field: string): string {
+  if (typeof value !== "string") {
+    throw new Error(`${field} must be 64 hex characters`);
+  }
+  const normalized = value.trim().toLowerCase().replace(/^0x/, "");
+  if (!HEX_64_RE.test(normalized)) {
+    throw new Error(`${field} must be 64 hex characters`);
+  }
+  return normalized;
+}

package/src/models.ts

@@ -0,0 +1,103 @@
+import type { KaspaWasmRuntime } from "./runtime.js";
+
+export const KCC20_BUILDER_INPUT_SCHEMA =
+  "kcc20-shared-pskt-builder-input/v1" as const;
+export const KCC20_BUILDER_OUTPUT_SCHEMA =
+  "kcc20-shared-pskt-builder-output/v1" as const;
+
+export type Hex64 = string;
+
+export interface TransactionOutpoint {
+  txidHex: Hex64;
+  vout: number;
+}
+
+export interface CovenantUtxo extends TransactionOutpoint {
+  address: string;
+  amountSompi: string;
+  /** Decoded state required by the selected operation. */
+  state: Record<string, unknown>;
+  /** Optional script/artifact data supplied by the source resolver. */
+  scriptHex?: string;
+  artifactKey?: string;
+}
+
+export interface FundingUtxo extends TransactionOutpoint {
+  address: string;
+  amountSompi: string;
+  scriptPublicKeyHex?: string;
+}
+
+export interface BuildSources {
+  covenantUtxos?: CovenantUtxo[];
+  walletUtxos: FundingUtxo[];
+  optionalFeeTicketUtxos?: CovenantUtxo[];
+}
+
+export interface ArtifactDescriptor {
+  key: string;
+  version: string;
+  hash: Hex64;
+  abi?: unknown;
+  script?: unknown;
+}
+
+export interface BuildContext {
+  network: string;
+  walletAddress: string;
+  ownerIdentifier: string;
+  protocolVersion: string;
+  artifacts: Record<string, ArtifactDescriptor>;
+  /** Values normally controlled by backend configuration. */
+  protocolFeeBps?: string;
+  priorityFeeSompi?: string;
+}
+
+export interface Kcc20PsktBuildRequest {
+  schema: typeof KCC20_BUILDER_INPUT_SCHEMA;
+  builderKey: string;
+  operation: string;
+  action: string;
+  params: Record<string, unknown>;
+  context: BuildContext;
+  sources: BuildSources;
+}
+
+export interface SignInput {
+  index: number;
+  sighashType?: number;
+}
+
+export interface CovenantSigningScript {
+  inputIndex: number;
+  scriptHex: string;
+  signType?: string;
+  signatureScriptHex?: string;
+}
+
+export interface Kcc20PsktBuildResult {
+  schema: typeof KCC20_BUILDER_OUTPUT_SCHEMA;
+  psktTransactionJson: string;
+  signInputs: SignInput[];
+  scripts?: CovenantSigningScript[];
+  sourceOutpoints: string[];
+  artifactHashes: Record<string, Hex64>;
+  operationDigest: Hex64;
+  metadata?: Record<string, unknown>;
+}
+
+export interface Kcc20PsktBuilderDependencies {
+  wasm: KaspaWasmRuntime;
+  artifacts?: Record<string, unknown>;
+  artifactProvider?: (key: string) => Promise<unknown>;
+  config?: Record<string, unknown>;
+  /**
+   * Host-owned source transport. When supplied, the builder does not create,
+   * connect, or disconnect an RPC client; the host may therefore back this
+   * provider with one long-lived browser or server connection.
+   */
+  sourceProvider?: {
+    getUtxosByAddresses(args: { addresses: string[] }): Promise<unknown>;
+  };
+  rpcClientFactory?: (config: unknown) => any;
+}

package/src/operations.ts

@@ -0,0 +1,46 @@
+export const KCC20_BUILDER_KEYS = [
+  "kcc20.deploy-token",
+  "kcc20.mint",
+  "kcc20.set-public-mint-active",
+  "kcc20.transfer",
+  "kcc20.consolidate-holders",
+  "kcc20.reveal-token",
+  "kcc20wrapper.deploy-market",
+  "kcc20wrapper.wrap",
+  "kcc20wrapper.unwrap",
+  "kcc20orderbook.create-bid",
+  "kcc20orderbook.create-ask",
+  "kcc20orderbook.fill-ask",
+  "kcc20orderbook.fill-bid",
+  "kcc20orderbook.sweep-asks",
+  "kcc20orderbook.sweep-bids",
+  "kcc20orderbook.consolidate-holders",
+  "kcc20orderbook.cancel-ask",
+  "kcc20orderbook.cancel-bid",
+  "fee-ticket.deploy-root",
+  "fee-ticket.update-denomination",
+  "fee-ticket.create-from-utility-burn",
+  "fee-ticket.burn",
+  "fee-ticket.transfer",
+] as const;
+
+export type Kcc20BuilderKey = (typeof KCC20_BUILDER_KEYS)[number];
+
+export function isKcc20BuilderKey(value: string): value is Kcc20BuilderKey {
+  return (KCC20_BUILDER_KEYS as readonly string[]).includes(value);
+}
+
+export const BACKEND_ONLY_BUILDER_KEYS = [
+  "kcc20orderbook.matcher-settle-crossed",
+] as const;
+
+export type BackendOnlyBuilderKey = (typeof BACKEND_ONLY_BUILDER_KEYS)[number];
+
+export function isBackendOnlyBuilderKey(
+  value: unknown,
+): value is BackendOnlyBuilderKey {
+  return (
+    typeof value === "string" &&
+    (BACKEND_ONLY_BUILDER_KEYS as readonly string[]).includes(value)
+  );
+}