@kaspacom/kcc20-tx-builder 0.7.0 → 0.8.0-fee.0

package/src/escrow-fee.ts

@@ -0,0 +1,181 @@
+/** Fee arithmetic for new escrow markets only. Legacy trading is unchanged. */
+export const KCC20_ESCROW_POLICY_VERSION = 1 as const;
+export const KCC20_ESCROW_PROTOCOL_BPS = 100;
+export const KCC20_ESCROW_MAX_CREATOR_BPS = 500;
+export const KCC20_ESCROW_MIN_FEE_SOMPI = 50_000_000n;
+export const KCC20_ESCROW_MAX_CLAIM_RECEIPTS = 5;
+export const KCC20_ESCROW_MAX_INT = 9_223_372_036_854_775_807n;
+
+export interface Kcc20EscrowFeeAmounts {
+  protocolFeeSompi: bigint;
+  creatorFeeSompi: bigint;
+  totalFeeSompi: bigint;
+}
+
+function amount(value: bigint, name: string): bigint {
+  if (typeof value !== "bigint" || value < 0n || value > KCC20_ESCROW_MAX_INT) {
+    throw new Error(`${name} must be a nonnegative signed-64-bit bigint`);
+  }
+  return value;
+}
+
+function add(left: bigint, right: bigint): bigint {
+  return amount(left + right, "sum");
+}
+
+function fee(gross: bigint, bps: number): bigint {
+  // Match the contract without overflowing the intermediate multiplication.
+  const rate = BigInt(bps);
+  const percentage = (gross / 10_000n) * rate + ((gross % 10_000n) * rate) / 10_000n;
+  return percentage < KCC20_ESCROW_MIN_FEE_SOMPI ? KCC20_ESCROW_MIN_FEE_SOMPI : percentage;
+}
+
+/** A waiver here is a quote assumption, never proof of FeeTicket eligibility. */
+export function calculateKcc20EscrowFees(input: {
+  grossSompi: bigint;
+  creatorFeeBps: number;
+  protocolWaived: boolean;
+}): Kcc20EscrowFeeAmounts {
+  const gross = amount(input.grossSompi, "grossSompi");
+  if (gross < 50_000_000n) throw new Error("fill gross must be at least 0.5 KAS");
+  if (!Number.isInteger(input.creatorFeeBps) || input.creatorFeeBps < 0 || input.creatorFeeBps > KCC20_ESCROW_MAX_CREATOR_BPS) {
+    throw new Error("creatorFeeBps must be an integer from 0 to 500");
+  }
+  if (typeof input.protocolWaived !== "boolean") throw new Error("protocolWaived must be boolean");
+  const protocolFeeSompi = input.protocolWaived ? 0n : fee(gross, KCC20_ESCROW_PROTOCOL_BPS);
+  const creatorFeeSompi = input.creatorFeeBps === 0 ? 0n : fee(gross, input.creatorFeeBps);
+  return { protocolFeeSompi, creatorFeeSompi, totalFeeSompi: add(protocolFeeSompi, creatorFeeSompi) };
+}
+
+/** Trading-price components only; excludes network fees and storage deposits.
+ * One matched ask/bid is one fill. Call separately for independent fills. */
+export function quoteKcc20EscrowSettlement(input: {
+  grossSompi: bigint;
+  creatorFeeBps: number;
+  protocolWaived: boolean;
+  kind: "take-ask" | "fill-bid" | "cross-match";
+}) {
+  const fees = calculateKcc20EscrowFees(input);
+  if (!["take-ask", "fill-bid", "cross-match"].includes(input.kind)) throw new Error("unsupported settlement kind");
+  if (input.kind === "fill-bid" && input.grossSompi < fees.totalFeeSompi) {
+    throw new Error("fill gross cannot cover protocol and creator fees");
+  }
+  return {
+    ...fees,
+    grossSompi: input.grossSompi,
+    buyerPaysSompi: input.kind === "take-ask" ? add(input.grossSompi, fees.totalFeeSompi) : input.grossSompi,
+    sellerReceivesSompi: input.kind === "fill-bid" ? input.grossSompi - fees.totalFeeSompi : input.grossSompi,
+    matcherPaysSompi: input.kind === "cross-match" ? fees.totalFeeSompi : 0n,
+    requiresFeeOutput: fees.totalFeeSompi > 0n,
+  };
+}
+
+/** Arithmetic for one atomic trade group. Artifact and UTXO checks belong to
+ * the signed transaction builder; this quote does not authorize a FeeTicket. */
+export function quoteKcc20EscrowTradeGroup(input: {
+  kind: "take-ask" | "fill-bid" | "cross-match";
+  fillGrossSompi: readonly bigint[];
+  creatorFeeBps: number;
+  protocolWaived: boolean;
+}) {
+  const maxFills = input.kind === "take-ask" ? 16 : input.kind === "fill-bid" ? 10 : input.kind === "cross-match" ? 1 : 0;
+  if (!Array.isArray(input.fillGrossSompi) || input.fillGrossSompi.length < 1 || input.fillGrossSompi.length > maxFills) {
+    throw new Error("invalid trade group size");
+  }
+  if (input.kind === "cross-match" && input.protocolWaived) {
+    throw new Error("crossed matches cannot use a FeeTicket");
+  }
+  const feeVector = input.fillGrossSompi.map(grossSompi =>
+    quoteKcc20EscrowSettlement({
+      grossSompi, creatorFeeBps: input.creatorFeeBps,
+      protocolWaived: input.protocolWaived, kind: input.kind,
+    }));
+  const totals = feeVector.reduce((sum, fill) => ({
+    grossSompi: add(sum.grossSompi, fill.grossSompi),
+    protocolFeeSompi: add(sum.protocolFeeSompi, fill.protocolFeeSompi),
+    creatorFeeSompi: add(sum.creatorFeeSompi, fill.creatorFeeSompi),
+    buyerPaysSompi: add(sum.buyerPaysSompi, fill.buyerPaysSompi),
+    sellerReceivesSompi: add(sum.sellerReceivesSompi, fill.sellerReceivesSompi),
+    matcherPaysSompi: add(sum.matcherPaysSompi, fill.matcherPaysSompi),
+  }), {
+    grossSompi: 0n, protocolFeeSompi: 0n, creatorFeeSompi: 0n,
+    buyerPaysSompi: 0n, sellerReceivesSompi: 0n, matcherPaysSompi: 0n,
+  });
+  return {
+    ...totals,
+    feeVector: feeVector.map(fill => ({
+      protocolFeeSompi: fill.protocolFeeSompi,
+      creatorFeeSompi: fill.creatorFeeSompi,
+    })),
+    receiptValueSompi: add(totals.protocolFeeSompi, totals.creatorFeeSompi),
+    requiresFeeOutput: totals.protocolFeeSompi + totals.creatorFeeSompi > 0n,
+  };
+}
+
+/** Accounting description only. The transaction builder must authenticate scripts and live UTXOs. */
+export interface Kcc20FeeReceiptAmounts {
+  outpoint: { transactionId: string; index: number };
+  tokenId: string;
+  marketId: string;
+  policyId: string;
+  protocolAccountId: string;
+  creatorAccountId: string;
+  valueSompi: bigint;
+  protocolSompi: bigint;
+  creatorSompi: bigint;
+}
+
+function id(value: string): string {
+  if (typeof value !== "string" || !/^[0-9a-fA-F]{64}$/.test(value)) throw new Error("identity must be 32-byte hex");
+  return value.toLowerCase();
+}
+
+/** Computes a single claim's conservation amounts, without authorizing a spend. */
+export function calculateKcc20FeeClaim(
+  receipts: readonly Kcc20FeeReceiptAmounts[],
+  party: "protocol" | "creator",
+) {
+  if (party !== "protocol" && party !== "creator") throw new Error("unknown claiming party");
+  if (!Array.isArray(receipts) || receipts.length < 1 || receipts.length > KCC20_ESCROW_MAX_CLAIM_RECEIPTS) {
+    throw new Error("claim must select between one and five receipts");
+  }
+  const seen = new Set<string>();
+  let group: string | undefined;
+  let protocol = 0n;
+  let creator = 0n;
+  let consumed = 0n;
+  for (const receipt of receipts) {
+    const txid = id(receipt.outpoint.transactionId);
+    if (!Number.isInteger(receipt.outpoint.index) || receipt.outpoint.index < 0 || receipt.outpoint.index > 0xffffffff) {
+      throw new Error("outpoint index must be uint32");
+    }
+    const outpoint = `${txid}:${receipt.outpoint.index}`;
+    if (seen.has(outpoint)) throw new Error("duplicate receipt outpoint");
+    seen.add(outpoint);
+    const identity = [receipt.tokenId, receipt.marketId, receipt.policyId, receipt.protocolAccountId, receipt.creatorAccountId].map(id).join(":");
+    const zero = "0".repeat(64);
+    if ([receipt.tokenId, receipt.marketId, receipt.policyId, receipt.protocolAccountId].some(value => id(value) === zero)) {
+      throw new Error("token, market, policy and protocol account must be nonzero");
+    }
+    if (id(receipt.protocolAccountId) === id(receipt.creatorAccountId)) throw new Error("fee accounts must differ");
+    if (id(receipt.creatorAccountId) === zero && receipt.creatorSompi !== 0n) throw new Error("disabled creator account cannot hold fees");
+    if (group !== undefined && identity !== group) throw new Error("receipts must share token, market, policy and accounts");
+    group = identity;
+    const p = amount(receipt.protocolSompi, "protocolSompi");
+    const c = amount(receipt.creatorSompi, "creatorSompi");
+    const value = amount(receipt.valueSompi, "valueSompi");
+    if (value === 0n || value !== add(p, c)) throw new Error("receipt value must equal nonzero entitlements");
+    if ((p > 0n && p < KCC20_ESCROW_MIN_FEE_SOMPI) || (c > 0n && c < KCC20_ESCROW_MIN_FEE_SOMPI)) {
+      throw new Error("nonzero entitlement is below the policy minimum");
+    }
+    if ((party === "protocol" ? p : c) === 0n) throw new Error("receipt has no entitlement for claimant");
+    protocol = add(protocol, p);
+    creator = add(creator, c);
+    consumed = add(consumed, value);
+  }
+  const claimSompi = party === "protocol" ? protocol : creator;
+  const remainingProtocolSompi = party === "protocol" ? 0n : protocol;
+  const remainingCreatorSompi = party === "creator" ? 0n : creator;
+  return { claimSompi, remainingProtocolSompi, remainingCreatorSompi, consumedSompi: consumed,
+    remainderSompi: add(remainingProtocolSompi, remainingCreatorSompi) };
+}

package/src/escrow-policy.ts

@@ -0,0 +1,130 @@
+import { blake3 } from "@noble/hashes/blake3";
+import { blake2b } from "@noble/hashes/blake2b";
+import { calculateKcc20FeeClaim, type Kcc20FeeReceiptAmounts } from "./escrow-fee.js";
+
+/** Fixed 361-byte policy for the versioned fee roles. Decoding is not artifact authentication. */
+export interface Kcc20EscrowPolicy {
+  version: 1;
+  creatorFeeBps: number;
+  protocolAccountId: string;
+  creatorAccountId: string;
+  receiptTemplate: { hash: string; prefixLength: number; suffixLength: number };
+  rootTemplate: { hash: string; prefixLength: number; suffixLength: number };
+  holderTemplate: { hash: string; prefixLength: number; suffixLength: number };
+  askTemplate: { hash: string; prefixLength: number; suffixLength: number };
+  bidTemplate: { hash: string; prefixLength: number; suffixLength: number };
+  ticketTemplate: { hash: string; prefixLength: number; suffixLength: number };
+}
+
+const ZERO = "0".repeat(64);
+function hex32(value: string, allowZero = false): Uint8Array {
+  if (typeof value !== "string" || !/^[0-9a-fA-F]{64}$/.test(value) || (!allowZero && value === ZERO)) {
+    throw new Error("expected nonzero 32-byte identity");
+  }
+  return Uint8Array.from(value.match(/../g)!.map(byte => Number.parseInt(byte, 16)));
+}
+function hex(value: Uint8Array): string {
+  return Array.from(value, byte => byte.toString(16).padStart(2, "0")).join("");
+}
+function int64(value: bigint): Uint8Array {
+  if (typeof value !== "bigint" || value < 0n || value > 0x7fff_ffff_ffff_ffffn) throw new Error("expected nonnegative int64");
+  const result = new Uint8Array(8);
+  new DataView(result.buffer).setBigUint64(0, value, true);
+  return result;
+}
+function concat(...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;
+}
+function template(value: Kcc20EscrowPolicy["receiptTemplate"]): Uint8Array {
+  for (const length of [value.prefixLength, value.suffixLength]) {
+    if (!Number.isSafeInteger(length) || length <= 0) throw new Error("template lengths must be positive safe integers");
+  }
+  return concat(hex32(value.hash), int64(BigInt(value.prefixLength)), int64(BigInt(value.suffixLength)));
+}
+
+export function encodeKcc20EscrowPolicy(policy: Kcc20EscrowPolicy): Uint8Array {
+  if (policy.version !== 1) throw new Error("unsupported fee policy version");
+  if (!Number.isInteger(policy.creatorFeeBps) || policy.creatorFeeBps < 0 || policy.creatorFeeBps > 500) throw new Error("creator rate must be 0 to 500 bps");
+  const protocol = hex32(policy.protocolAccountId);
+  const creator = hex32(policy.creatorAccountId, policy.creatorFeeBps === 0);
+  if (hex(protocol) === hex(creator)) throw new Error("fee account identities must differ");
+  if ((policy.creatorFeeBps === 0) !== (hex(creator) === ZERO)) throw new Error("creator rate and account do not match");
+  return concat(Uint8Array.of(1), int64(BigInt(policy.creatorFeeBps)), protocol, creator,
+    template(policy.receiptTemplate), template(policy.rootTemplate), template(policy.holderTemplate),
+    template(policy.askTemplate), template(policy.bidTemplate), template(policy.ticketTemplate));
+}
+
+export function decodeKcc20EscrowPolicy(bytes: Uint8Array): Kcc20EscrowPolicy {
+  if (!(bytes instanceof Uint8Array) || bytes.length !== 361 || bytes[0] !== 1) throw new Error("invalid fee policy encoding");
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const integer = (offset: number): number => {
+    const value = view.getBigUint64(offset, true);
+    if (value > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("noncanonical or oversized policy integer");
+    return Number(value);
+  };
+  const readTemplate = (offset: number) => ({ hash: hex(bytes.slice(offset, offset + 32)),
+    prefixLength: integer(offset + 32), suffixLength: integer(offset + 40) });
+  const policy: Kcc20EscrowPolicy = {
+    version: 1, creatorFeeBps: integer(1),
+    protocolAccountId: hex(bytes.slice(9, 41)), creatorAccountId: hex(bytes.slice(41, 73)),
+    receiptTemplate: readTemplate(73), rootTemplate: readTemplate(121),
+    holderTemplate: readTemplate(169), askTemplate: readTemplate(217),
+    bidTemplate: readTemplate(265), ticketTemplate: readTemplate(313),
+  };
+  encodeKcc20EscrowPolicy(policy);
+  return policy;
+}
+
+export function kcc20EscrowPolicyId(input: {
+  tokenId: string; feeTicketId: string; priceScale: bigint; policy: Kcc20EscrowPolicy;
+}): string {
+  if (typeof input.priceScale !== "bigint" || input.priceScale <= 0n) throw new Error("priceScale must be positive");
+  return hex(blake3(concat(hex32(input.tokenId), hex32(input.feeTicketId, true),
+    int64(input.priceScale), encodeKcc20EscrowPolicy(input.policy))));
+}
+
+/** Public consent can be reused only for this TN10 market and fixed fee policy.
+ * Send `message` to the wallet's standard personal-message signing API. A wallet
+ * signature is still required; creating this payload does not establish authority.
+ */
+export function kcc20CreatorFeeConsent(input: {
+  tokenId: string; marketId: string; feeTicketId: string; priceScale: bigint; policy: Kcc20EscrowPolicy;
+}): { commitment: string; message: string; personalMessageHash: string } {
+  if (typeof input.priceScale !== "bigint" || input.priceScale <= 0n) throw new Error("priceScale must be positive");
+  const policy = encodeKcc20EscrowPolicy(input.policy);
+  if (input.policy.creatorFeeBps === 0) throw new Error("creator consent is only used when creator fees are enabled");
+  const commitment = hex(blake3(concat(Uint8Array.of(0xc1), hex32(input.tokenId), hex32(input.marketId),
+    hex32(input.feeTicketId, true), int64(input.priceScale), policy)));
+  const message = `KCC20 creator fee consent v1 (TN10)\n${commitment}`;
+  const encoder = new TextEncoder();
+  const personalMessageHash = hex(blake2b(encoder.encode(message), {
+    dkLen: 32, key: encoder.encode("PersonalMessageSigningHash"),
+  }));
+  return { commitment, message, personalMessageHash };
+}
+
+function outpoint(value: { transactionId: string; index: number }): Uint8Array {
+  if (!Number.isInteger(value.index) || value.index < 0 || value.index > 0xffffffff) throw new Error("outpoint index must be uint32");
+  return concat(hex32(value.transactionId, true), int64(BigInt(value.index)));
+}
+
+/** Input order must match the covenant family's consensus input order. */
+export function kcc20FeeClaimCommitment(input: {
+  receipts: readonly Kcc20FeeReceiptAmounts[];
+  party: "protocol" | "creator";
+  accountOutpoint: { transactionId: string; index: number };
+  /** Serialized ScriptPublicKey, including its two-byte little-endian version. */
+  payoutScriptPublicKey: Uint8Array;
+}): string {
+  const amounts = calculateKcc20FeeClaim(input.receipts, input.party);
+  if (!(input.payoutScriptPublicKey instanceof Uint8Array) || input.payoutScriptPublicKey.length < 3) throw new Error("serialized payout ScriptPublicKey is required");
+  let receiptHash: Uint8Array = new Uint8Array(32);
+  for (const receipt of input.receipts) receiptHash = blake3(concat(receiptHash, outpoint(receipt.outpoint)));
+  const first = input.receipts[0];
+  return hex(blake3(concat(Uint8Array.of(0xf1), hex32(first.tokenId), hex32(first.marketId), hex32(first.policyId),
+    receiptHash, outpoint(input.accountOutpoint), int64(input.party === "creator" ? 1n : 0n),
+    int64(amounts.claimSompi), int64(amounts.remainderSompi), blake3(input.payoutScriptPublicKey))));
+}

package/src/index.ts

@@ -18,6 +18,8 @@ export * from "./paid-mint-amount.js";
 export * from "./token-amount.js";
 export * from "./token-operation.js";
 export * from "./trade-fee.js";
+export * from "./escrow-fee.js";
+export * from "./escrow-policy.js";
 export * from "./trading-operation.js";
 export * from "./protocol.js";
 export * from "./runtime.js";