@kaspacom/kcc20-tx-builder 0.1.0

package/src/token-operation.ts

@@ -0,0 +1,384 @@
+import {
+  ownerNativeHolderUtxos,
+  selectActiveMinterUtxo,
+  selectConsolidationBatch,
+  selectOwnerNativeHolderUtxo,
+  summarizeHolderUtxos,
+  type Kcc20IndexedCovenantUtxo,
+} from "./action-source-resolver.js";
+import {
+  kcc20DisplayScaleForDecimals,
+  normalizeKcc20Decimals,
+  normalizeKcc20OwnerIdentifier,
+  parseKcc20DisplayAmountToBaseUnits,
+} from "./token-amount.js";
+import { kcc20ValidatePaidMintAmount } from "./paid-mint-amount.js";
+import {
+  KCC20_PUBLIC_MINT_MAX_DISPLAY_TOKENS,
+  KCC20_PUBLIC_MINT_MAX_DISPLAY_TOKENS_LABEL,
+} from "./protocol.js";
+import { buildKcc20WalletOperationFromPlan } from "./wallet-operation.js";
+
+export interface Kcc20ActionWalletInfo {
+  walletAddress: string;
+  kcc20Owner: string;
+}
+
+export interface Kcc20ActionTokenInfo {
+  covenantId: string;
+  ticker?: string | null;
+  tokenName?: string | null;
+  decimals?: number | null;
+  mintPolicy?: {
+    mintable?: boolean;
+    policy?: string;
+    publicMintActive?: boolean | null;
+    remainingSupply?: string | null;
+    mintPricePerTokenSompi?: string | null;
+    treasuryRecipient?: string | null;
+    protocolFeeRecipient?: string | null;
+    protocolFeeBps?: number | null;
+  };
+}
+
+export interface Kcc20TokenOperationOptions {
+  network?: string;
+  createdAt?: string;
+  requestId?: string;
+}
+
+export function buildKcc20MintTokenOperation(
+  wallet: Kcc20ActionWalletInfo,
+  input: {
+    token: Kcc20ActionTokenInfo;
+    tokenAmount: string;
+    recipientOwner?: string;
+    activeUtxos: readonly Kcc20IndexedCovenantUtxo[];
+    publicRequest?: boolean;
+  },
+  options: Kcc20TokenOperationOptions = {},
+) {
+  const covenantId = requireHex32(input.token.covenantId, "covenantId");
+  const policy = input.token.mintPolicy?.policy;
+  if (
+    !input.token.mintPolicy?.mintable ||
+    (policy !== "public" && policy !== "controlled")
+  ) {
+    throw new Error(
+      `Unsupported KCC20 mint policy: ${policy ?? "not-mintable"}`,
+    );
+  }
+  const pausedPublicMint =
+    policy === "public" && input.token.mintPolicy.publicMintActive === false;
+  if (pausedPublicMint && input.publicRequest !== false) {
+    throw new Error("Public mint is paused by the token creator");
+  }
+  const decimals = normalizeKcc20Decimals(input.token.decimals);
+  const priceScale = kcc20DisplayScaleForDecimals(decimals);
+  const tokenAmount = parseKcc20DisplayAmountToBaseUnits(
+    input.tokenAmount,
+    decimals,
+    "tokenAmount",
+  );
+  if (
+    policy === "public" &&
+    BigInt(tokenAmount) > KCC20_PUBLIC_MINT_MAX_DISPLAY_TOKENS * priceScale
+  ) {
+    throw new Error(
+      `Public mint amount exceeds the maximum per mint transaction of ${KCC20_PUBLIC_MINT_MAX_DISPLAY_TOKENS_LABEL} tokens`,
+    );
+  }
+  const mintPrice = input.token.mintPolicy.mintPricePerTokenSompi;
+  if (mintPrice && /^\d+$/.test(mintPrice) && BigInt(mintPrice) > 0n) {
+    kcc20ValidatePaidMintAmount({
+      tokenAmount: BigInt(tokenAmount),
+      unitPriceSompi: BigInt(mintPrice),
+      priceScale,
+      protocolFeeBps: input.token.mintPolicy.protocolFeeBps,
+    });
+  }
+  const minter = selectActiveMinterUtxo(input.activeUtxos, tokenAmount);
+  if (!minter?.state)
+    throw new Error(
+      "No active KCC20 mint-authority UTXO has enough remaining supply",
+    );
+  const walletOwner = normalizeKcc20OwnerIdentifier(
+    wallet.kcc20Owner,
+    "wallet owner",
+  );
+  const authorityOwner = String(
+    minter.state["ownerIdentifier"] ?? minter.state["owner"] ?? "",
+  ).toLowerCase();
+  const authorityScheme = Number(
+    minter.state["ownerScheme"] ?? minter.state["identifierType"],
+  );
+  if (
+    (policy === "controlled" || pausedPublicMint) &&
+    (authorityScheme !== 0 || authorityOwner !== walletOwner)
+  ) {
+    throw new Error(
+      policy === "controlled"
+        ? "Controlled mint requires the active mint-authority owner"
+        : "Paused public mint requires the active minter owner",
+    );
+  }
+  const recipientOwner = input.recipientOwner
+    ? normalizeKcc20OwnerIdentifier(input.recipientOwner, "recipientOwner")
+    : walletOwner;
+  if (
+    recipientOwner !== walletOwner &&
+    policy !== "controlled" &&
+    !pausedPublicMint
+  ) {
+    throw new Error(
+      "Mint recipient override requires controlled mint authority",
+    );
+  }
+  const mintPath =
+    policy === "controlled" || authorityOwner === walletOwner
+      ? "owner"
+      : "public";
+  return buildKcc20WalletOperationFromPlan(
+    wallet,
+    {
+      builderKey: "kcc20.mint",
+      operation: "mint-token",
+      contract: "KCC20",
+      action: "mint",
+      description: "Build a KCC20 mint transaction request.",
+      params: {
+        covenantId,
+        tokenAmount,
+        tokenDisplayScale: priceScale.toString(),
+        priceScale: priceScale.toString(),
+        recipientOwner,
+        recipientOwnerScheme: 0,
+        mintPath,
+        ticker: input.token.ticker ?? null,
+        tokenName: input.token.tokenName ?? null,
+        mintPolicy: input.token.mintPolicy ?? null,
+        activeMinterUtxo: minter,
+      },
+      sourceRequirements: [
+        {
+          type: "kcc20-mint-authority-utxo",
+          covenantId,
+          outpoint: minter.outpoint,
+          remainingSupply: minter.state["remainingSupply"],
+          purpose: "authorize mint supply reduction and recipient output",
+        },
+        {
+          type: "kcc20-mint-recipient-owner",
+          owner: recipientOwner,
+          ownerType: "pubkey",
+          purpose: "create minted holder output for the intended recipient",
+        },
+        {
+          type: "kaspa-funding-utxo",
+          ownerAddress: wallet.walletAddress,
+          purpose: "fund output dust and network fee",
+        },
+      ],
+      warnings: [
+        "Wallet must enforce remaining-supply accounting before signing.",
+        ...(mintPath === "owner"
+          ? [
+              "Owner-authorized mint requires the wallet to sign the mint-authority covenant input.",
+            ]
+          : []),
+      ],
+    },
+    options,
+  );
+}
+
+export function buildKcc20TransferTokenOperation(
+  wallet: Kcc20ActionWalletInfo,
+  input: {
+    token: Kcc20ActionTokenInfo;
+    tokenAmount: string;
+    recipientOwner: string;
+    activeUtxos: readonly Kcc20IndexedCovenantUtxo[];
+    holderOutpoint?: string;
+  },
+  options: Kcc20TokenOperationOptions = {},
+) {
+  const covenantId = requireHex32(input.token.covenantId, "covenantId");
+  const decimals = normalizeKcc20Decimals(input.token.decimals);
+  const tokenAmount = parseKcc20DisplayAmountToBaseUnits(
+    input.tokenAmount,
+    decimals,
+    "tokenAmount",
+  );
+  const owner = normalizeKcc20OwnerIdentifier(
+    wallet.kcc20Owner,
+    "wallet owner",
+  );
+  const recipientOwner = normalizeKcc20OwnerIdentifier(
+    input.recipientOwner,
+    "recipientOwner",
+  );
+  const holder = selectOwnerNativeHolderUtxo(
+    input.activeUtxos,
+    owner,
+    tokenAmount,
+    input.holderOutpoint,
+  );
+  const ownerUtxos = ownerNativeHolderUtxos(input.activeUtxos, owner);
+  const summary = summarizeHolderUtxos(ownerUtxos, tokenAmount);
+  if (!holder) {
+    throw new Error(
+      summary.fragmented
+        ? "No single KCC20 holder UTXO is large enough; consolidate the token balance first"
+        : "No single KCC20 holder UTXO is available for this wallet and amount",
+    );
+  }
+  const nativeCovenantId = holder.covenantId ?? covenantId;
+  return buildKcc20WalletOperationFromPlan(
+    wallet,
+    {
+      builderKey: "kcc20.transfer",
+      operation: "transfer-token",
+      contract: "KCC20",
+      action: "transfer",
+      description: "Build a KCC20 holder transfer transaction request.",
+      params: {
+        covenantId,
+        appCanonicalCovenantId: covenantId,
+        activeHolderNativeCovenantId: nativeCovenantId,
+        tokenAmount,
+        recipientOwner,
+        recipientOwnerScheme: 0,
+        ticker: input.token.ticker ?? null,
+        tokenName: input.token.tokenName ?? null,
+        activeHolderUtxo: holder,
+      },
+      sourceRequirements: [
+        {
+          type: "kcc20-holder-utxo",
+          covenantId,
+          activeHolderNativeCovenantId: nativeCovenantId,
+          owner,
+          minimumTokenAmount: tokenAmount,
+          ...summary,
+          outpoint: holder.outpoint,
+          amount: holder.state?.["amount"],
+          purpose:
+            "spend native holder balance into recipient output and optional owner change output",
+        },
+        {
+          type: "kcc20-transfer-recipient-owner",
+          owner: recipientOwner,
+          ownerType: "pubkey",
+          purpose:
+            "create transferred holder output for the intended recipient",
+        },
+        {
+          type: "kaspa-funding-utxo",
+          ownerAddress: wallet.walletAddress,
+          purpose: "fund output dust and network fee",
+        },
+      ],
+      warnings: [
+        `This transfers ${input.tokenAmount} KCC20 balance to the selected recipient owner.`,
+        "Only pubkey-owned holder outputs can be transferred directly from this wallet flow.",
+        "Transfer spends one KCC20 holder UTXO; fragmented balances require consolidation.",
+      ],
+    },
+    options,
+  );
+}
+
+export function buildKcc20NativeConsolidationOperation(
+  wallet: Kcc20ActionWalletInfo,
+  input: {
+    token: Kcc20ActionTokenInfo;
+    activeUtxos: readonly Kcc20IndexedCovenantUtxo[];
+    sourceOutpoints?: readonly string[];
+  },
+  options: Kcc20TokenOperationOptions = {},
+) {
+  const covenantId = requireHex32(input.token.covenantId, "covenantId");
+  const owner = normalizeKcc20OwnerIdentifier(
+    wallet.kcc20Owner,
+    "wallet owner",
+  );
+  const compatible = ownerNativeHolderUtxos(input.activeUtxos, owner);
+  const selected = selectConsolidationBatch(
+    compatible,
+    input.sourceOutpoints,
+    8,
+  );
+  if (selected.length < 2)
+    throw new Error(
+      "at least two compatible KCC20 holder UTXOs are required for consolidation",
+    );
+  const nativeIds = new Set(
+    selected.map((utxo) => utxo.covenantId ?? covenantId),
+  );
+  if (nativeIds.size !== 1)
+    throw new Error(
+      "selected holder UTXOs belong to different active covenant ids",
+    );
+  const nativeCovenantId = [...nativeIds][0];
+  const total = selected
+    .reduce(
+      (sum, utxo) => sum + BigInt(String(utxo.state?.["amount"] ?? "0")),
+      0n,
+    )
+    .toString();
+  const summary = summarizeHolderUtxos(compatible, "0");
+  return buildKcc20WalletOperationFromPlan(
+    wallet,
+    {
+      builderKey: "kcc20.consolidate-holders",
+      operation: "consolidate-native-holders",
+      contract: "KCC20",
+      action: "consolidate",
+      description: "Build a KCC20 holder consolidation transaction request.",
+      params: {
+        covenantId,
+        appCanonicalCovenantId: covenantId,
+        activeHolderNativeCovenantId: nativeCovenantId,
+        tokenAmount: total,
+        ticker: input.token.ticker ?? null,
+        tokenName: input.token.tokenName ?? null,
+        activeHolderUtxos: selected,
+      },
+      sourceRequirements: [
+        {
+          type: "kcc20-holder-utxo-batch",
+          covenantId,
+          activeHolderNativeCovenantId: nativeCovenantId,
+          owner,
+          selectedOutpoints: selected.map((utxo) => utxo.outpoint),
+          selectedAmounts: selected.map((utxo) => utxo.state?.["amount"]),
+          aggregateAmount: summary.aggregateAmount,
+          utxoCount: summary.utxoCount,
+          purpose:
+            "merge wallet-owned KCC20 holder outputs into one holder output",
+        },
+        {
+          type: "kaspa-funding-utxo",
+          ownerAddress: wallet.walletAddress,
+          purpose: "fund network fee for holder consolidation",
+        },
+      ],
+      warnings: [
+        "Consolidation merges between two and eight wallet-owned holder UTXOs into one larger holder UTXO.",
+        "Repeat consolidation when more compatible holder UTXOs remain.",
+      ],
+    },
+    options,
+  );
+}
+
+function requireHex32(value: string, field: string): string {
+  const normalized = String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/^0x/, "");
+  if (!/^[a-f0-9]{64}$/.test(normalized))
+    throw new Error(`${field} must be 64 hex characters`);
+  return normalized;
+}

package/src/trade-fee.ts

@@ -0,0 +1,264 @@
+import {
+  kcc20DecimalsFromDisplayScale,
+  kcc20DisplayScaleForDecimals,
+} from "./token-amount.js";
+import {
+  KCC20_DEFAULT_PRICE_SCALE,
+  KCC20_DEFAULT_PROTOCOL_FEE_BPS,
+  KCC20_MIN_PROTOCOL_FEE_SOMPI,
+} from "./protocol.js";
+
+export {
+  KCC20_DEFAULT_PRICE_SCALE,
+  KCC20_DEFAULT_PROTOCOL_FEE_BPS,
+  KCC20_MIN_PROTOCOL_FEE_SOMPI,
+} from "./protocol.js";
+
+export interface Kcc20TradeFeeQuote {
+  priceScale: string;
+  grossSompi: string;
+  protocolFeeBps: number;
+  minimumProtocolFeeSompi: string;
+  estimatedProtocolFeeSompi: string;
+  protocolFeeSompi: string;
+  feeTicketApplied: boolean;
+  feePayer: "buyer" | "seller" | "matcher" | "none";
+  feeTiming: "order-creation" | "fill" | "cross-match";
+  buyerPaysSompi?: string;
+  buyerEscrowSompi?: string;
+  buyerTradeEscrowSompi?: string;
+  temporaryKasDepositSompi?: string;
+  sellerReceivesSompi?: string;
+  matcherPaysSompi?: string;
+  buyerSurplusRefundSompi?: string;
+  note: string;
+}
+
+export function buildCreateOrderFeeQuote(input: {
+  side: "buy" | "sell";
+  tokenAmount: string;
+  unitPriceSompi: string;
+  priceScale?: unknown;
+  temporaryKasDepositSompi?: string;
+}): Kcc20TradeFeeQuote {
+  const priceScale = normalizePriceScale(input.priceScale);
+  const gross = exactGross(input.tokenAmount, input.unitPriceSompi, priceScale);
+  const estimatedFee = protocolFee(gross);
+  const deposit =
+    input.side === "buy"
+      ? unsigned(
+          input.temporaryKasDepositSompi ?? "0",
+          "temporaryKasDepositSompi",
+        )
+      : 0n;
+  return {
+    priceScale: priceScale.toString(),
+    grossSompi: gross.toString(),
+    protocolFeeBps: Number(KCC20_DEFAULT_PROTOCOL_FEE_BPS),
+    minimumProtocolFeeSompi: KCC20_MIN_PROTOCOL_FEE_SOMPI.toString(),
+    estimatedProtocolFeeSompi: estimatedFee.toString(),
+    protocolFeeSompi: "0",
+    feeTicketApplied: false,
+    feePayer: "none",
+    feeTiming: "order-creation",
+    ...(input.side === "buy"
+      ? {
+          buyerEscrowSompi: (gross + deposit).toString(),
+          buyerTradeEscrowSompi: gross.toString(),
+          temporaryKasDepositSompi: deposit.toString(),
+        }
+      : {}),
+    note:
+      input.side === "buy"
+        ? "Buy order creation escrows gross KAS plus a Temporary KAS deposit that follows the buyer holder and is returned when that holder lifecycle ends; the protocol fee is paid at settlement."
+        : "Sell order creation locks wrapped tokens; protocol fee is paid at settlement.",
+  };
+}
+
+export function buildStandaloneFillFeeQuote(input: {
+  side: "buy" | "sell";
+  tokenAmount: string;
+  unitPriceSompi: string;
+  priceScale?: unknown;
+  feeTicketApplied: boolean;
+}): Kcc20TradeFeeQuote {
+  const priceScale = normalizePriceScale(input.priceScale);
+  const gross = exactGross(input.tokenAmount, input.unitPriceSompi, priceScale);
+  const estimatedFee = protocolFee(gross);
+  const fee = input.feeTicketApplied ? 0n : estimatedFee;
+  if (input.side === "buy") {
+    return {
+      priceScale: priceScale.toString(),
+      grossSompi: gross.toString(),
+      protocolFeeBps: Number(KCC20_DEFAULT_PROTOCOL_FEE_BPS),
+      minimumProtocolFeeSompi: KCC20_MIN_PROTOCOL_FEE_SOMPI.toString(),
+      estimatedProtocolFeeSompi: estimatedFee.toString(),
+      protocolFeeSompi: fee.toString(),
+      feeTicketApplied: input.feeTicketApplied,
+      feePayer: "buyer",
+      feeTiming: "fill",
+      buyerPaysSompi: (gross + fee).toString(),
+      sellerReceivesSompi: gross.toString(),
+      note: "Buying an ask pays seller gross KAS plus protocol fee unless a FeeTicket is burned.",
+    };
+  }
+  return {
+    priceScale: priceScale.toString(),
+    grossSompi: gross.toString(),
+    protocolFeeBps: Number(KCC20_DEFAULT_PROTOCOL_FEE_BPS),
+    minimumProtocolFeeSompi: KCC20_MIN_PROTOCOL_FEE_SOMPI.toString(),
+    estimatedProtocolFeeSompi: estimatedFee.toString(),
+    protocolFeeSompi: fee.toString(),
+    feeTicketApplied: input.feeTicketApplied,
+    feePayer: "seller",
+    feeTiming: "fill",
+    buyerPaysSompi: gross.toString(),
+    sellerReceivesSompi: (gross > fee ? gross - fee : 0n).toString(),
+    note: "Selling into a bid receives gross KAS minus protocol fee unless a FeeTicket is burned.",
+  };
+}
+
+export function calculateKcc20ProtocolFeeSompi(
+  grossSompi: bigint,
+  feeBps = Number(KCC20_DEFAULT_PROTOCOL_FEE_BPS),
+  minimumFeeSompi = KCC20_MIN_PROTOCOL_FEE_SOMPI,
+): bigint {
+  if (grossSompi <= 0n || feeBps <= 0) return 0n;
+  if (!Number.isInteger(feeBps) || feeBps > 10_000) {
+    throw new Error("feeBps must be an integer from 0 to 10000");
+  }
+  if (minimumFeeSompi < 0n) {
+    throw new Error("minimumFeeSompi must not be negative");
+  }
+  const percentage = (grossSompi * BigInt(feeBps)) / 10_000n;
+  return percentage < minimumFeeSompi ? minimumFeeSompi : percentage;
+}
+
+/**
+ * Largest trade gross that fits a buyer budget after the protocol fee and a
+ * host-selected network reserve. All values are integer sompi.
+ */
+export function calculateKcc20MaximumBuyerGrossSompi(input: {
+  availableSompi: bigint;
+  networkReserveSompi?: bigint;
+  protocolFeeBps?: number;
+  minimumProtocolFeeSompi?: bigint;
+}): bigint {
+  const reserve = input.networkReserveSompi ?? 0n;
+  const feeBps = input.protocolFeeBps ?? Number(KCC20_DEFAULT_PROTOCOL_FEE_BPS);
+  const minimumFee =
+    input.minimumProtocolFeeSompi ?? KCC20_MIN_PROTOCOL_FEE_SOMPI;
+  if (input.availableSompi < 0n) {
+    throw new Error("availableSompi must not be negative");
+  }
+  if (reserve < 0n) {
+    throw new Error("networkReserveSompi must not be negative");
+  }
+  // Validate even when no balance is available.
+  calculateKcc20ProtocolFeeSompi(1n, feeBps, minimumFee);
+  const budget =
+    input.availableSompi > reserve ? input.availableSompi - reserve : 0n;
+  let low = 0n;
+  let high = budget;
+  while (low < high) {
+    const middle = low + (high - low + 1n) / 2n;
+    const fee = calculateKcc20ProtocolFeeSompi(middle, feeBps, minimumFee);
+    if (middle + fee <= budget) low = middle;
+    else high = middle - 1n;
+  }
+  return low;
+}
+
+/** Returns the largest base-unit token amount affordable by a buyer. */
+export function calculateKcc20MaximumBuyTokenBaseUnits(input: {
+  availableSompi: bigint;
+  unitPriceSompi: bigint;
+  priceScale: bigint;
+  networkReserveSompi?: bigint;
+  protocolFeeBps?: number;
+  minimumProtocolFeeSompi?: bigint;
+}): bigint {
+  if (input.unitPriceSompi <= 0n) return 0n;
+  if (input.priceScale <= 0n) {
+    throw new Error("priceScale must be greater than zero");
+  }
+  const gross = calculateKcc20MaximumBuyerGrossSompi(input);
+  return (gross * input.priceScale) / input.unitPriceSompi;
+}
+
+export function buildCrossMatchFeeQuote(input: {
+  tokenAmount: string;
+  askUnitPriceSompi: string;
+  bidUnitPriceSompi: string;
+  priceScale?: unknown;
+}): Kcc20TradeFeeQuote {
+  const priceScale = normalizePriceScale(input.priceScale);
+  const askUnitPrice = unsigned(input.askUnitPriceSompi, "askUnitPriceSompi");
+  const bidUnitPrice = unsigned(input.bidUnitPriceSompi, "bidUnitPriceSompi");
+  const gross = exactGross(
+    input.tokenAmount,
+    input.askUnitPriceSompi,
+    priceScale,
+  );
+  const fee = protocolFee(gross);
+  const surplus =
+    bidUnitPrice > askUnitPrice
+      ? exactGross(
+          input.tokenAmount,
+          (bidUnitPrice - askUnitPrice).toString(),
+          priceScale,
+        )
+      : 0n;
+  return {
+    priceScale: priceScale.toString(),
+    grossSompi: gross.toString(),
+    protocolFeeBps: Number(KCC20_DEFAULT_PROTOCOL_FEE_BPS),
+    minimumProtocolFeeSompi: KCC20_MIN_PROTOCOL_FEE_SOMPI.toString(),
+    estimatedProtocolFeeSompi: fee.toString(),
+    protocolFeeSompi: fee.toString(),
+    feeTicketApplied: false,
+    feePayer: "matcher",
+    feeTiming: "cross-match",
+    buyerPaysSompi: (gross + surplus).toString(),
+    sellerReceivesSompi: gross.toString(),
+    matcherPaysSompi: fee.toString(),
+    buyerSurplusRefundSompi: surplus.toString(),
+    note: "Crossed settlement currently pays seller gross and refunds all buyer surplus; the backend matcher funds the protocol fee under the deployed covenant artifact.",
+  };
+}
+
+function normalizePriceScale(value: unknown): bigint {
+  if (value === undefined || value === null) return KCC20_DEFAULT_PRICE_SCALE;
+  const decimals = kcc20DecimalsFromDisplayScale(value);
+  if (decimals !== null) return kcc20DisplayScaleForDecimals(decimals);
+  throw new Error(
+    "priceScale must be an exact power-of-ten display scale for decimals 0-8",
+  );
+}
+
+function exactGross(
+  amountValue: string,
+  priceValue: string,
+  scale: bigint,
+): bigint {
+  const product =
+    unsigned(amountValue, "tokenAmount") *
+    unsigned(priceValue, "unitPriceSompi");
+  if (product % scale !== 0n)
+    throw new Error("trade gross amount is not an exact sompi value");
+  return product / scale;
+}
+
+function protocolFee(gross: bigint): bigint {
+  const percentage = (gross * KCC20_DEFAULT_PROTOCOL_FEE_BPS) / 10_000n;
+  return percentage < KCC20_MIN_PROTOCOL_FEE_SOMPI
+    ? KCC20_MIN_PROTOCOL_FEE_SOMPI
+    : percentage;
+}
+
+function unsigned(value: unknown, field: string): bigint {
+  const raw = String(value ?? "").trim();
+  if (!/^\d+$/.test(raw))
+    throw new Error(`${field} must be an unsigned integer string`);
+  return BigInt(raw);
+}