@kaspacom/kcc20-tx-builder 0.8.0-fee.4 → 0.8.0-fee.6

package/src/escrow-market-artifacts.ts

@@ -0,0 +1,129 @@
+import { sha256 } from "@noble/hashes/sha256";
+import { blake2b } from "@noble/hashes/blake2b";
+import { normalizeSilverScriptArtifact, templateParts } from "./abi.js";
+import { assertKcc20ArtifactScriptHash } from "./artifacts.js";
+import { encodeKcc20EscrowPolicy, type Kcc20EscrowPolicy } from "./escrow-policy.js";
+
+const PINS = {
+  receipt: ["KCC20FeeEscrowV1.placeholder.json", "KCC20FeeEscrowV1", "2ff79d6e8ca7176d6346ab7523c72b789f7238865cd9d3b056c83a8af1b5b2cd"],
+  root: ["KCC20OrderbookFeeRootV1.placeholder.json", "KCC20OrderbookFeeRootV1", "4f913975eebb0342272912573b9901f84551d9f421b80608c0b872a42479c011"],
+  holder: ["KCC20OrderbookFeeHolderV1.placeholder.json", "KCC20OrderbookFeeHolderV1", "78a3fe1ef7a4d7ae142ab78a3a71cef2c1a70ea638cd695e89ea891dd17eec67"],
+  ask: ["KCC20OrderbookFeeAskV1.placeholder.json", "KCC20OrderbookFeeAskV1", "b60465af84c75121820323aa83155b6ddcfaae4bff2c64b06740058f5ebc0f95"],
+  bid: ["KCC20OrderbookFeeBidV1.placeholder.json", "KCC20OrderbookFeeBidV1", "98d7c97319bbe1ca954c7f4f6a02467e90a7f3e84c14c91db650f8ef5887ee0e"],
+  ticket: ["KCC20FeeTicket.placeholder.json", "KCC20FeeTicket", "289f3f74914deb383d2cccc11128187a77e4bcea90e61c83e05d86c5c9d63bc5"],
+  wrapper: ["KCC20WrapperFeeV1.placeholder.json", "KCC20WrapperFeeV1", "84c3844493efd4bdf6b2e3435e1ac511f5b5a7f58b5b6c093c91e2edcae1a2e0"],
+  argentWrapper: ["KCC20WrapperFeeArgentV1.placeholder.json", "KCC20WrapperFeeArgentV1", "130f25462e070523821579d28809577fac6d010f8d5deabc66ad2de1c11d2c73"],
+} as const;
+
+export type Kcc20FeeArtifactRole = keyof typeof PINS;
+export type Kcc20FeeArtifactSet = { [K in Kcc20FeeArtifactRole]: unknown };
+const POLICY_ROLES = ["receipt", "root", "holder", "ask", "bid", "ticket"] as const;
+
+function hex(bytes: Uint8Array): string {
+  return Array.from(bytes, byte => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function fixedBytes(value: unknown, width: number, field: string): Uint8Array {
+  if (typeof value !== "string" || !new RegExp(`^[0-9a-fA-F]{${width * 2}}$`).test(value)) {
+    throw new Error(`${field} must be ${width}-byte hex`);
+  }
+  return Uint8Array.from(value.match(/../g)!, part => Number.parseInt(part, 16));
+}
+
+/** Render a pinned versioned role with exact SilverScript runtime-state encoding. */
+export function buildKcc20FeeMarketRoleScript(input: {
+  artifact: unknown;
+  role: "root" | "holder" | "ask" | "bid" | "wrapper" | "argentWrapper";
+  state: Record<string, unknown>;
+}) {
+  const [key, name, metadataHash] = PINS[input.role];
+  const raw = input.artifact as {
+    contracts?: Record<string, { runtime_state?: { fields?: Array<{ name: string; type: { kind: string; len?: number } }> } }>;
+  };
+  if (!raw || typeof raw !== "object" ||
+      hex(sha256(new TextEncoder().encode(JSON.stringify(raw)))) !== metadataHash) {
+    throw new Error(`${input.role} fee-market artifact metadata mismatch`);
+  }
+  const artifact = normalizeSilverScriptArtifact(raw);
+  if (artifact.contract_name !== name) throw new Error(`${input.role} contract mismatch`);
+  assertKcc20ArtifactScriptHash(key, artifact);
+  const fields = Object.values(raw.contracts ?? {})[0]?.runtime_state?.fields;
+  if (!fields || Object.keys(input.state).length !== fields.length ||
+      fields.some(field => !Object.hasOwn(input.state, field.name))) {
+    throw new Error(`${input.role} runtime state fields mismatch`);
+  }
+  const encoded: number[] = [];
+  for (const field of fields) {
+    const value = input.state[field.name];
+    const { kind, len } = field.type;
+    let bytes: Uint8Array;
+    if (kind === "fixed_bytes" && Number.isInteger(len) && len! > 0) {
+      bytes = fixedBytes(value, len!, field.name);
+    } else if (kind === "bool" && typeof value === "boolean") {
+      bytes = Uint8Array.of(value ? 1 : 0);
+    } else if (kind === "byte" && Number.isInteger(value) && Number(value) >= 0 && Number(value) <= 255) {
+      bytes = Uint8Array.of(Number(value));
+    } else if (kind === "int" && typeof value === "string" && /^(0|[1-9]\d*)$/.test(value) &&
+        BigInt(value) <= (1n << 63n) - 1n) {
+      bytes = new Uint8Array(8);
+      new DataView(bytes.buffer).setBigUint64(0, BigInt(value), true);
+    } else {
+      throw new Error(`invalid ${input.role} state field ${field.name}`);
+    }
+    if (bytes.length <= 75) encoded.push(bytes.length, ...bytes);
+    else if (bytes.length <= 65535) encoded.push(77, bytes.length & 255, bytes.length >> 8, ...bytes);
+    else throw new Error(`${field.name} exceeds script push size`);
+  }
+  const layout = artifact.state_layout;
+  if (!layout || encoded.length !== layout.len) throw new Error(`${input.role} state width mismatch`);
+  const parts = templateParts(artifact);
+  const redeemScript = Uint8Array.from([...parts.prefix, ...encoded, ...parts.suffix]);
+  const scriptHash = hex(blake2b(redeemScript, { dkLen: 32 }));
+  return {
+    redeemScript,
+    scriptHash,
+    scriptPublicKey: { version: 0 as const, scriptHex: `aa20${scriptHash}87` },
+    template: { hash: hex(parts.hash), prefixLength: parts.prefixLength, suffixLength: parts.suffixLength },
+  };
+}
+
+/** Check the compiled programs and immutable policy before any fee-market PSKT is built. */
+export function verifyKcc20FeeMarketArtifacts(input: {
+  policy: Kcc20EscrowPolicy;
+  artifacts: Kcc20FeeArtifactSet;
+  wrapperProfile: "native" | "argent";
+}) {
+  if (encodeKcc20EscrowPolicy(input.policy).length !== 361) {
+    throw new Error("invalid fee-market policy width");
+  }
+  const verified = {} as Record<Kcc20FeeArtifactRole, ReturnType<typeof templateParts>>;
+  for (const role of [...POLICY_ROLES, input.wrapperProfile === "native" ? "wrapper" : "argentWrapper"] as Kcc20FeeArtifactRole[]) {
+    const artifact = input.artifacts[role];
+    const [key, name, metadataHash] = PINS[role];
+    if (!artifact || typeof artifact !== "object") throw new Error(`missing ${role} fee-market artifact`);
+    const actualMetadataHash = hex(sha256(new TextEncoder().encode(JSON.stringify(artifact))));
+    if (actualMetadataHash !== metadataHash) throw new Error(`${role} fee-market artifact metadata mismatch`);
+    const normalized = normalizeSilverScriptArtifact(artifact);
+    if (normalized.contract_name !== name) throw new Error(`${role} fee-market artifact contract mismatch`);
+    assertKcc20ArtifactScriptHash(key, normalized);
+    verified[role] = templateParts(normalized);
+  }
+  for (const role of POLICY_ROLES) {
+    const actual = verified[role];
+    const expected = input.policy[`${role}Template`];
+    if (hex(actual.hash) !== expected.hash.toLowerCase() ||
+        actual.prefixLength !== expected.prefixLength ||
+        actual.suffixLength !== expected.suffixLength) {
+      throw new Error(`${role} fee-market policy template mismatch`);
+    }
+  }
+  return {
+    wrapper: input.wrapperProfile === "native" ? verified.wrapper : verified.argentWrapper,
+    receipt: verified.receipt,
+    root: verified.root,
+    holder: verified.holder,
+    ask: verified.ask,
+    bid: verified.bid,
+    ticket: verified.ticket,
+  };
+}

package/src/escrow-market-setup.ts

@@ -0,0 +1,182 @@
+import { encodeKcc20EscrowPolicy, kcc20EscrowPolicyId, type Kcc20EscrowPolicy } from "./escrow-policy.js";
+import {
+  buildKcc20FeeMarketRoleScript,
+  verifyKcc20FeeMarketArtifacts,
+  type Kcc20FeeArtifactSet,
+} from "./escrow-market-artifacts.js";
+
+const ZERO = "00".repeat(32);
+const MAX = (1n << 63n) - 1n;
+
+function hex32(value: unknown, label: string, allowZero = false): string {
+  if (typeof value !== "string" || !/^[0-9a-f]{64}$/i.test(value) ||
+      (!allowZero && value.toLowerCase() === ZERO)) {
+    throw new Error(`${label} must be a ${allowZero ? "valid" : "nonzero"} 32-byte hex value`);
+  }
+  return value.toLowerCase();
+}
+
+export interface Kcc20FeeMarketGenesisInput {
+  tokenId: string;
+  feeTicketId: string;
+  priceScale: bigint;
+  policy: Kcc20EscrowPolicy;
+  wrapperProfile: "native" | "argent";
+  artifacts: Kcc20FeeArtifactSet;
+}
+
+/** Produce the only genesis role: an unbound wrapper with no orderbook root. */
+export function prepareKcc20FeeMarketGenesis(input: Kcc20FeeMarketGenesisInput) {
+  const tokenId = hex32(input.tokenId, "token ID");
+  const feeTicketId = hex32(input.feeTicketId, "FeeTicket ID", true);
+  if (typeof input.priceScale !== "bigint" || input.priceScale <= 0n || input.priceScale > MAX) {
+    throw new Error("market price scale is outside the contract range");
+  }
+  if (input.wrapperProfile !== "native" && input.wrapperProfile !== "argent") {
+    throw new Error("unsupported fee-market wrapper profile");
+  }
+  if (input.wrapperProfile === "argent" && input.policy.creatorFeeBps !== 0) {
+    throw new Error("Argent token profile cannot authorize creator fees");
+  }
+  verifyKcc20FeeMarketArtifacts(input);
+  const feePolicy = Array.from(encodeKcc20EscrowPolicy(input.policy),
+    byte => byte.toString(16).padStart(2, "0")).join("");
+  const policyId = kcc20EscrowPolicyId({ tokenId, feeTicketId, priceScale: input.priceScale, policy: input.policy });
+  const state = {
+    canonicalTokenId: tokenId, enabled: false, priceScale: input.priceScale.toString(),
+    feeTicketId, feePolicy, authenticatedMarketId: ZERO,
+  };
+  const role = input.wrapperProfile === "native" ? "wrapper" : "argentWrapper";
+  const wrapper = buildKcc20FeeMarketRoleScript({ artifact: input.artifacts[role], role, state });
+  return { tokenId, feeTicketId, policyId, state, wrapper };
+}
+
+/** Render both bound outputs after the accepted genesis has fixed market ID. */
+export function prepareKcc20FeeMarketBinding(input: Kcc20FeeMarketGenesisInput & {
+  marketId: string;
+  rootOwner: string;
+  rootOwnerScheme: number;
+  rootPayoutScriptHash: string;
+}) {
+  const genesis = prepareKcc20FeeMarketGenesis(input);
+  const marketId = hex32(input.marketId, "market ID");
+  const rootOwner = hex32(input.rootOwner, "root owner");
+  const rootPayoutScriptHash = hex32(input.rootPayoutScriptHash, "root payout script hash");
+  if (!Number.isInteger(input.rootOwnerScheme) || input.rootOwnerScheme < 0 || input.rootOwnerScheme > 4) {
+    throw new Error("unsupported root owner scheme");
+  }
+  const role = input.wrapperProfile === "native" ? "wrapper" : "argentWrapper";
+  const wrapperState = { ...genesis.state, enabled: true, authenticatedMarketId: marketId };
+  const wrapper = buildKcc20FeeMarketRoleScript({ artifact: input.artifacts[role], role, state: wrapperState });
+  const rootState = {
+    canonicalTokenId: genesis.tokenId, owner: rootOwner, owner_scheme: input.rootOwnerScheme,
+    amount: "0", mode: "1", unitPrice: "0", feeTicketId: genesis.feeTicketId,
+    priceScale: input.priceScale.toString(), feePolicy: genesis.state.feePolicy,
+    payout_script_hash: rootPayoutScriptHash, wrapper_spk_hash: wrapper.scriptHash,
+  };
+  const root = buildKcc20FeeMarketRoleScript({ artifact: input.artifacts.root, role: "root", state: rootState });
+  return { genesis, marketId, wrapperState, wrapper, rootState, root };
+}
+
+/** Render a wrapped holder against the exact enabled wrapper for this market. */
+export function prepareKcc20FeeMarketWrappedHolder(input: Kcc20FeeMarketGenesisInput & {
+  marketId: string;
+  recipientOwner: string;
+  recipientOwnerScheme: number;
+  recipientPayoutScriptHash: string;
+  tokenAmount: bigint;
+}) {
+  const genesis = prepareKcc20FeeMarketGenesis(input);
+  const marketId = hex32(input.marketId, "market ID");
+  const recipientOwner = hex32(input.recipientOwner, "wrapped recipient");
+  const payoutScriptHash = hex32(input.recipientPayoutScriptHash, "wrapped payout script hash");
+  if (!Number.isInteger(input.recipientOwnerScheme) ||
+      input.recipientOwnerScheme < 0 || input.recipientOwnerScheme > 4) {
+    throw new Error("unsupported wrapped recipient scheme");
+  }
+  if (typeof input.tokenAmount !== "bigint" || input.tokenAmount <= 0n || input.tokenAmount > MAX) {
+    throw new Error("wrapped token amount is outside the contract range");
+  }
+  const wrapperRole = input.wrapperProfile === "native" ? "wrapper" : "argentWrapper";
+  const wrapperState = { ...genesis.state, enabled: true, authenticatedMarketId: marketId };
+  const wrapper = buildKcc20FeeMarketRoleScript({
+    artifact: input.artifacts[wrapperRole], role: wrapperRole, state: wrapperState,
+  });
+  const holderState = {
+    canonicalTokenId: genesis.tokenId,
+    owner: recipientOwner,
+    owner_scheme: input.recipientOwnerScheme,
+    amount: input.tokenAmount.toString(),
+    mode: "0",
+    unitPrice: "0",
+    feeTicketId: genesis.feeTicketId,
+    priceScale: input.priceScale.toString(),
+    feePolicy: genesis.state.feePolicy,
+    payout_script_hash: payoutScriptHash,
+    wrapper_spk_hash: wrapper.scriptHash,
+  };
+  const holder = buildKcc20FeeMarketRoleScript({
+    artifact: input.artifacts.holder, role: "holder", state: holderState,
+  });
+  return { marketId, wrapperState, wrapper, holderState, holder };
+}
+
+/** Render an ask and any holder continuation against a pinned market policy. */
+export function prepareKcc20FeeMarketAsk(input: Kcc20FeeMarketGenesisInput & {
+  marketId: string;
+  owner: string;
+  ownerScheme: number;
+  payoutScriptHash: string;
+  holderAmount: bigint;
+  askAmount: bigint;
+  askUnitPrice: bigint;
+}) {
+  if (input.askAmount <= 0n || input.askAmount > input.holderAmount ||
+      input.askUnitPrice <= 0n || input.askUnitPrice > MAX) {
+    throw new Error("fee-market ask amount or price is invalid");
+  }
+  const holder = prepareKcc20FeeMarketWrappedHolder({ ...input,
+    recipientOwner: input.owner, recipientOwnerScheme: input.ownerScheme,
+    recipientPayoutScriptHash: input.payoutScriptHash,
+    tokenAmount: input.holderAmount,
+  });
+  const askState = { ...holder.holderState, amount: input.askAmount.toString(),
+    mode: "2", unitPrice: input.askUnitPrice.toString() };
+  const ask = buildKcc20FeeMarketRoleScript({ artifact: input.artifacts.ask,
+    role: "ask", state: askState });
+  const remaining = input.holderAmount - input.askAmount;
+  const change = remaining > 0n ? prepareKcc20FeeMarketWrappedHolder({ ...input,
+    recipientOwner: input.owner, recipientOwnerScheme: input.ownerScheme,
+    recipientPayoutScriptHash: input.payoutScriptHash, tokenAmount: remaining,
+  }) : null;
+  return { holder, askState, ask, remaining, change };
+}
+
+/** Render a bid while preserving the single market root unchanged. */
+export function prepareKcc20FeeMarketBid(input: Kcc20FeeMarketGenesisInput & {
+  marketId: string;
+  rootOwner: string;
+  rootOwnerScheme: number;
+  rootPayoutScriptHash: string;
+  buyer: string;
+  buyerScheme: number;
+  buyerPayoutScriptHash: string;
+  bidAmount: bigint;
+  bidUnitPrice: bigint;
+}) {
+  if (input.bidAmount <= 0n || input.bidAmount > MAX ||
+      input.bidUnitPrice <= 0n || input.bidUnitPrice > MAX ||
+      !Number.isInteger(input.buyerScheme) || input.buyerScheme < 0 ||
+      input.buyerScheme > 4) {
+    throw new Error("fee-market bid amount, price or buyer scheme is invalid");
+  }
+  const binding = prepareKcc20FeeMarketBinding(input);
+  const bidState = { ...binding.rootState,
+    owner: hex32(input.buyer, "bid buyer"), owner_scheme: input.buyerScheme,
+    amount: input.bidAmount.toString(), mode: "3",
+    unitPrice: input.bidUnitPrice.toString(),
+    payout_script_hash: hex32(input.buyerPayoutScriptHash, "bid payout hash") };
+  const bid = buildKcc20FeeMarketRoleScript({ artifact: input.artifacts.bid,
+    role: "bid", state: bidState });
+  return { binding, bidState, bid };
+}

package/src/index.ts

@@ -20,6 +20,8 @@ export * from "./token-operation.js";
 export * from "./trade-fee.js";
 export * from "./escrow-fee.js";
 export * from "./escrow-policy.js";
+export * from "./escrow-market-artifacts.js";
+export * from "./escrow-market-setup.js";
 export * from "./escrow-group.js";
 export * from "./escrow-receipt.js";
 export * from "./escrow-claim-plan.js";

package/src/operations.ts

@@ -24,6 +24,20 @@ export const KCC20_BUILDER_KEYS = [
   "fee-ticket.transfer",
   "kcc20fee.create-account",
   "kcc20fee.bind-account",
+  "kcc20fee.deploy-market-genesis",
+  "kcc20fee.bind-market",
+  "kcc20fee.wrap",
+  "kcc20fee.unwrap",
+  "kcc20fee.merge-holders",
+  "kcc20fee.create-ask",
+  "kcc20fee.cancel-ask",
+  "kcc20fee.create-bid",
+  "kcc20fee.cancel-bid",
+  "kcc20fee.buy-ask",
+  "kcc20fee.buy-two-asks",
+  "kcc20fee.sell-into-bids",
+  "kcc20fee.claim",
+  "kcc20fee.rotate-account",
   "kcc20-snapshot.deploy-bootstrap",
   "kcc20-snapshot.deploy-controller",
   "kcc20-snapshot.start",