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

package/docs/COMPATIBILITY.json

@@ -1,14 +1,13 @@
 {
   "schema": "kcc20-example-compatibility/v1",
-  "packageVersion": "0.5.0-lastcall.0",
+  "packageVersion": "0.8.0-fee.0",
   "contractsRepository": "https://github.com/KASPACOM/kaspa-covenants",
-  "contractsCommit": null,
+  "contractsCommit": "5deb1769e69142595576ef7c573af9f433a48a3c",
   "compiler": {
     "repository": "https://github.com/kaspanet/silverscript",
     "tag": "v1.0.0",
     "commit": "3ed973335b59269293564805cc2c58a14595ec03",
-    "tree": "2a30f522768d9b4cae6fe30014326c689a25bd41",
-    "build": "verified-source"
+    "tree": "2a30f522768d9b4cae6fe30014326c689a25bd41"
   },
   "wasm": {
     "version": "1.1.1-toc.1",
@@ -31,45 +30,58 @@
       "scriptSha256": "ef9fe81ff7aa2dc2df118d8d7cc126aca6f2f9c181b9c2d15727a538b23c6f71",
       "sourceSha256": "b4216aa3db10f486b2032fa52eb93ec1768c65ea841415bd2fffb85bdc652bbb",
       "constructorArgsSha256": "a3f32dc91fee760df98d0238d60f65a6d1324bce5ab0740e31f035144a90cc61",
-      "abiSha256": "bc5c24dc0e7ccfdd734981bfa81c806672ae90059fd075e93c9254671b25f155"
+      "abiSha256": "bc5c24dc0e7ccfdd734981bfa81c806672ae90059fd075e93c9254671b25f155",
+      "compilerBuild": "verified-source"
     },
     "KCC20Wrapper.placeholder.json": {
       "fileSha256": "2461e39a285d1f135f4891659cb78b3b6e5d2b28b32e153b61e2e336eab02115",
       "scriptSha256": "23cbd5473860cab4e63890d24ae1bd6732fce5beaa34f594dad01e845e3e9b9f",
       "sourceSha256": "030708f5b9c9e5cf7d1c4c9b9d699a681d11fa197635c3225f321dadb92ae37a",
       "constructorArgsSha256": "085f7457aa6456ef49ea3b3181739943d17b498d82fc2c8b6ab61a6f51f95573",
-      "abiSha256": "d4f2fdfd16cd0cd6b42e863de90a8bae90e5b44d9495b85a32f287f88750df2c"
+      "abiSha256": "d4f2fdfd16cd0cd6b42e863de90a8bae90e5b44d9495b85a32f287f88750df2c",
+      "compilerBuild": "verified-source"
     },
     "KCC20.placeholder.json": {
       "fileSha256": "a45d06e8351421dac1ef73f3595c6f34068e4fa1e13d3f8fa1c88be518c6e56f",
       "scriptSha256": "dd9cb334cd9e9220b15644782f271ef3ecdba34fd0762010e3d6bc18176837ae",
       "sourceSha256": "9ae9b13ebc56cd85f072ea6cc78d3a5e5f050b66dda62677e223bc9c29ec231e",
       "constructorArgsSha256": "c86edb17c8e7a338bf35b519caa3c4f955bcf5ab73476f9c5a3baa34bb73926a",
-      "abiSha256": "c2a169d67682b49ce3501f288e73f18ca96c815fd47db8e614d75b20f3678802"
+      "abiSha256": "c2a169d67682b49ce3501f288e73f18ca96c815fd47db8e614d75b20f3678802",
+      "compilerBuild": "verified-source"
     },
     "KCC20FeeTicket.placeholder.json": {
       "fileSha256": "b104ff07adcfe58a1db134bb44782fa59453dadb7716e0a831447f910efb9526",
       "scriptSha256": "c0e95cb8e5226462674647f86d5760626b5c38b7bd97a6e2ec9ba61fdef8941f",
       "sourceSha256": "980294c10d9af5d79218a5d81100df30da7ca80e3bf5c284adac3c8803b51d49",
       "constructorArgsSha256": "66b2ca443a59de6854f29bf2e8aa9c11a3074707070d653310432ac1c31ec81f",
-      "abiSha256": "8bb5f66f91bc296380eaa6b5bcc7d5045b59c2b4783e8b1bcf394a7e1395a420"
+      "abiSha256": "8bb5f66f91bc296380eaa6b5bcc7d5045b59c2b4783e8b1bcf394a7e1395a420",
+      "compilerBuild": "verified-source"
     },
     "KCC20Vesting.placeholder.json": {
       "fileSha256": "b917c9dcd05237fdedf76ac6b0df5791d5953aca1d057909c5fac075fb17ca43",
       "scriptSha256": "e32d9f5bde124526475a61075ba46eef41955d4662b1422713860cfbd7a59661",
       "sourceSha256": "6f32a53c6212bd985c2fad48b3dc66ee0daffd5ac411e5676268d22eccbfa5b3",
       "constructorArgsSha256": "b1adf7afaf5daa150e7bb54e8ddfdc63fae5a23a9b30ad528435ce6346205b40",
-      "abiSha256": "b58ee502376aaf59e0b2d663012b2964a3ae7b30025b2d830e46ea18993e7dc7"
+      "abiSha256": "b58ee502376aaf59e0b2d663012b2964a3ae7b30025b2d830e46ea18993e7dc7",
+      "compilerBuild": "verified-source"
     },
     "KCC20SnapshotBootstrap.placeholder.json": {
-      "fileSha256": "5f0caea9818f5bd6110023a7f089a0d26f87d3fd0901cb52e24a32bd1853b302",
-      "scriptSha256": "3d64211a2b3c5ac24009b9ce59d4e8ecb8f2114dbf0c43b5a060b2ed91704e02"
+      "fileSha256": "daddabe50454e1c6c187c0b027cc8887f79f0f0086a14f26c6a2a56054991ebb",
+      "scriptSha256": "a22b93b0d8cd04096d83d25bbb6c38f0c07ac025b70226677db484fa93fe09ef",
+      "sourceSha256": "6e6e6a8a5d12b68d0bf5a67c4e9a727dbed4605c62896f869c73f1f3e66c0fa8",
+      "constructorArgsSha256": "ccfd363002a8efb2ad8d8c7a3e44be9ad54078c292d294098ec9262326d040ce",
+      "abiSha256": "7cf08a871d29a3fddc988000c6dd0bb01140bcacdf931254c341248e0baa8a3b",
+      "compilerBuild": "verified-release"
     },
     "KCC20SnapshotController.placeholder.json": {
-      "fileSha256": "8c5d2056bb0a445ffc1a6967238fac46378372b5f357524c6795201699bf2b2f",
-      "scriptSha256": "fdc2e396a66a1f708522d68f879ec67d71bd0070c7417b1e7f5dd3a6c8cfda88"
+      "fileSha256": "a73727cfe03108097e1226566cff9dbbbf42a5dc8526aac3196817ffc642212f",
+      "scriptSha256": "8a73c57e309860ff799a71ca9352afa84f71638061cfa427cc5e8d36d1b8b025",
+      "sourceSha256": "1d8697fd967af3278e9fceae5a98ef442eaf29037822c963baf4c9d252288edd",
+      "constructorArgsSha256": "1d6b2ac27fa5fea7e6c419543d4968f5b623b3139e880984d2fa5a116a453635",
+      "abiSha256": "f4e503b480fd8c63194fcbe987e3818998bf4c387c360cb0371bebf542c60050",
+      "compilerBuild": "verified-release"
     }
   },
-  "contractsSourceStatus": "unreviewed Last Call candidate; source commit must be pinned before publication",
+  "contractsSourceStatus": "reviewed source and generated inputs pinned to contractsCommit",
   "standardRevision": "3fbec524abfbc20e87652eb938db218f8c17db17"
 }

package/docs/escrow-fees.md

@@ -0,0 +1,56 @@
+# Experimental fee escrow primitives
+
+These exports support the new DEV fee-market contracts. Existing transaction
+construction still uses the legacy fee version. These functions do not build,
+authorize or submit escrow spends, and this change does not publish a package.
+
+`calculateKcc20EscrowFees` implements the fixed 1% protocol fee and optional
+0–5% creator fee. Each nonzero share has a 0.5 KAS minimum, applied per fill.
+`protocolWaived` is a quote assumption. A transaction builder must independently
+authenticate and consume an eligible FeeTicket before using that assumption.
+
+`quoteKcc20EscrowSettlement` returns the trading-price and fee components for
+take-ask, fill-bid and crossed settlements. Ask buyers pay fees above the price;
+bid sellers receive price minus fees; a crossed matcher funds the fee once.
+The result excludes network fees and storage deposits and is not a complete
+wallet debit/proceeds quote. Fills that cannot cover their fees are rejected.
+
+`quoteKcc20EscrowTradeGroup` takes ordered fills from one atomic trade group.
+It calculates each fill's fee independently, then returns one fee vector and
+one summed receipt value. A ticket waiver applies to every fill in that group;
+crossed matches reject a ticket. The function checks the contract's maximum
+fill counts, but it does not prove a group fits the signed transaction mass
+budget or that all fills share one authenticated market and taker. The builder
+must perform those checks before signing. In the current offline proof, a
+two-ask buy passes the conservative mass target and a three-ask buy does not.
+
+`calculateKcc20FeeClaim` checks the accounting for one through five distinct
+receipts from the same token, market, policy and fee accounts. It returns the
+claim and retained amounts. This does not establish that the receipts exist,
+are unspent or have authenticated scripts. Construction must revalidate all
+inputs against current chain state and the approved artifacts.
+
+`encodeKcc20EscrowPolicy` and `decodeKcc20EscrowPolicy` implement the fixed
+361-byte role policy, with receipt, root, holder, ask, bid and FeeTicket
+template tuples in that order. They reject unsupported versions, noncanonical
+integers, invalid rates and invalid account identities. `kcc20EscrowPolicyId`
+hashes token ID, FeeTicket ID, price scale and the complete policy encoding.
+The protocol rate and fee floors are constants of this contract version.
+
+`kcc20FeeClaimCommitment` binds the ordered receipt outpoints, account outpoint,
+claiming party, amounts, market identity and payout ScriptPublicKey. Supply the
+ScriptPublicKey's two-byte version prefix as well as its script bytes. Receipt
+order must match the native covenant family's input order. The consensus proof
+harness uses the same fixed commitment vector.
+
+Release requires authenticated artifact resolution, settlement and claim
+construction, complete signed-transaction mass checks, application integration,
+funded TN10 lifecycle proof and independent review of the final artifacts.
+# Creator consent
+
+`kcc20CreatorFeeConsent` produces the public message and personal-message hash
+for the new TN10 wrapper. The authenticated creator signs `message` using the
+wallet's standard message-signing API. The commitment covers the native token,
+market, FeeTicket, scale and exact immutable fee policy, including account IDs.
+The helper only constructs the message; it does not authenticate metadata,
+verify a signature, grant creator rights or enable a market.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaspacom/kcc20-tx-builder",
-  "version": "0.6.3",
+  "version": "0.8.0-fee.0",
   "description": "Runtime-independent KCC20 covenant transaction and PSKT construction primitives.",
   "license": "Apache-2.0",
   "author": "KaspaCom",
@@ -42,6 +42,8 @@
         "default": "./dist/cjs/index.js"
       }
     },
+    "./artifacts/kcc20-snapshot-bootstrap/KCC20SnapshotBootstrap.placeholder.json": "./artifacts/KCC20SnapshotBootstrap.placeholder.json",
+    "./artifacts/kcc20-snapshot-controller/KCC20SnapshotController.placeholder.json": "./artifacts/KCC20SnapshotController.placeholder.json",
     "./artifacts/*": "./artifacts/*",
     "./package.json": "./package.json",
     "./*": {
@@ -86,7 +88,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/write-cjs-package.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run typecheck && npm run build && node test/smoke.mjs && node test/cjs-smoke.cjs && node test/snapshot-plan.mjs && node test/token-profiles.mjs && node test/profile-transfer.mjs && node --test test/mint-availability-limit.mjs test/consolidation-profile.mjs test/consolidation-transaction.mjs && node test/pinned-funding.mjs",
+    "test:escrow-fee": "npm run build && node --test test/escrow-fee.mjs test/escrow-policy.mjs",
+    "test": "npm run typecheck && npm run build && node test/smoke.mjs && node test/cjs-smoke.cjs && node test/snapshot-plan.mjs && node test/token-profiles.mjs && node test/profile-transfer.mjs && node --test test/mint-availability-limit.mjs test/consolidation-profile.mjs test/consolidation-transaction.mjs test/escrow-fee.mjs test/escrow-policy.mjs && node test/pinned-funding.mjs",
     "prepack": "npm test",
     "test:examples": "npm run verify:compatibility && node scripts/test-examples.mjs --browser",
     "verify:compatibility": "node scripts/verify-compatibility.mjs",

package/src/abi.ts

@@ -207,15 +207,41 @@ export function mintExtensionCommitment(extension) {
 
 export function holderExtensionCommitment(extension) {
   const { kind = 1 } = extension;
+  const kindValue = requireByte(kind, "kind");
+  const maxSupply = BigInt(extension.maxSupply);
+  const fixedPrefix = [
+    Uint8Array.of(kindValue),
+    requireBytes(extension.creator, 32, "creator"),
+    requireBytes(extension.ticker, 32, "ticker"),
+    requireBytes(extension.name, 32, "name"),
+    signedI64Payload(BigInt(extension.displayScale)),
+  ];
+  if (kindValue === 2) {
+    if (Number(extension.mintPolicy) !== 0) {
+      throw new Error("wide holder extension is fixed-supply only");
+    }
+    const { high, low } = unsignedWideAmountLimbs(maxSupply, "maxSupply");
+    return blake3(
+      concatBytes(
+        new TextEncoder().encode("KASPACOM/KCC20/HOLDER/V2"),
+        ...fixedPrefix,
+        signedI64Payload(high),
+        signedI64Payload(low),
+        signedI64Payload(BigInt(extension.mintLaneCount ?? 1)),
+        Uint8Array.of(requireByte(extension.mintPolicy, "mintPolicy")),
+        signedI64Payload(BigInt(extension.mintPriceSompi)),
+        requireBytes(extension.treasury, 32, "treasury"),
+        requireBytes(extension.protocolFeeRecipient, 32, "protocolFeeRecipient"),
+        signedI64Payload(BigInt(extension.protocolFeeBps)),
+      ),
+    );
+  }
+  if (kindValue !== 1) throw new Error("unsupported holder extension kind");
   return blake3(
     concatBytes(
       new TextEncoder().encode("KASPACOM/KCC20/HOLDER/V1"),
-      Uint8Array.of(requireByte(kind, "kind")),
-      requireBytes(extension.creator, 32, "creator"),
-      requireBytes(extension.ticker, 32, "ticker"),
-      requireBytes(extension.name, 32, "name"),
-      signedI64Payload(BigInt(extension.displayScale)),
-      signedI64Payload(BigInt(extension.maxSupply)),
+      ...fixedPrefix,
+      signedI64Payload(maxSupply),
       signedI64Payload(BigInt(extension.mintLaneCount ?? 1)),
       Uint8Array.of(requireByte(extension.mintPolicy, "mintPolicy")),
       signedI64Payload(BigInt(extension.mintPriceSompi)),
@@ -226,6 +252,20 @@ export function holderExtensionCommitment(extension) {
   );
 }
 
+function unsignedWideAmountLimbs(value, label) {
+  if (typeof value === "number" && !Number.isSafeInteger(value)) {
+    throw new Error(`${label} must not be an unsafe JavaScript number`);
+  }
+  const amount = BigInt(value);
+  const base = 1n << 63n;
+  const high = amount / base;
+  const low = amount % base;
+  if (amount <= 0n || high > base - 1n) {
+    throw new Error(`${label} is outside the unsigned two-limb range`);
+  }
+  return { high, low };
+}
+
 export function buildKcc20ScriptForState(artifact, state) {
   const normalized = normalizeSilverScriptArtifact(artifact);
   const script = Uint8Array.from(normalized.script);

package/src/artifacts.ts

@@ -8,9 +8,9 @@ export const KCC20_CURRENT_NATIVE_ARTIFACT_KEY =
 
 export const KCC20_ARTIFACT_SCRIPT_SHA256 = Object.freeze({
   "KCC20SnapshotBootstrap.placeholder.json":
-    "3d64211a2b3c5ac24009b9ce59d4e8ecb8f2114dbf0c43b5a060b2ed91704e02",
+    "a22b93b0d8cd04096d83d25bbb6c38f0c07ac025b70226677db484fa93fe09ef",
   "KCC20SnapshotController.placeholder.json":
-    "fdc2e396a66a1f708522d68f879ec67d71bd0070c7417b1e7f5dd3a6c8cfda88",
+    "8a73c57e309860ff799a71ca9352afa84f71638061cfa427cc5e8d36d1b8b025",
   [KCC20_CURRENT_NATIVE_ARTIFACT_KEY]:
     "dd9cb334cd9e9220b15644782f271ef3ecdba34fd0762010e3d6bc18176837ae",
   "KCC20FeeTicket.placeholder.json":
@@ -33,17 +33,17 @@ export const KCC20_SNAPSHOT_ARTIFACT_PINS = Object.freeze({
     key: "KCC20SnapshotBootstrap.placeholder.json",
     contractName: "KCC20SnapshotBootstrap",
     artifactSha256:
-      "5f0caea9818f5bd6110023a7f089a0d26f87d3fd0901cb52e24a32bd1853b302",
-    scriptLength: 33718,
+      "daddabe50454e1c6c187c0b027cc8887f79f0f0086a14f26c6a2a56054991ebb",
+    scriptLength: 35913,
     stateStart: 1,
-    stateLength: 405,
+    stateLength: 414,
   }),
   controller: Object.freeze({
     key: "KCC20SnapshotController.placeholder.json",
     contractName: "KCC20SnapshotController",
     artifactSha256:
-      "8c5d2056bb0a445ffc1a6967238fac46378372b5f357524c6795201699bf2b2f",
-    scriptLength: 15297,
+      "a73727cfe03108097e1226566cff9dbbbf42a5dc8526aac3196817ffc642212f",
+    scriptLength: 15350,
     stateStart: 1,
     stateLength: 432,
   }),

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";

package/src/snapshot-deployment.ts

@@ -49,7 +49,8 @@ export function prepareSnapshotDeployment(kw: any, definition: SnapshotDeploymen
     throw new Error("shard allocations do not equal fixed token supply");
   }
   const extension = {
-    kind: 1, creator: definition.creator, ticker: bytesToHex(asciiToBytes32(definition.ticker)),
+    kind: BigInt(definition.totalSupply) > 9_223_372_036_854_775_807n ? 2 : 1,
+    creator: definition.creator, ticker: bytesToHex(asciiToBytes32(definition.ticker)),
     name: bytesToHex(asciiToBytes32(definition.ticker)), displayScale: definition.displayScale,
     maxSupply: definition.totalSupply, mintLaneCount: 1, mintPolicy: 0, mintPriceSompi: "0",
     treasury: definition.creator, protocolFeeRecipient: definition.creator, protocolFeeBps: "0",

package/src/snapshot-operation.ts

@@ -618,7 +618,7 @@ export function createKcc20SnapshotPsktBuilder(
         params.holderExtensionCommitment,
         "holder extension commitment",
       ),
-      totalSupply: positiveI64(params.totalSupply, "total supply"),
+      totalSupply: positiveWideAmount(params.totalSupply, "total supply"),
       claimNotBeforeDaaScore: positiveI64(
         params.claimNotBeforeDaaScore,
         "claim-not-before DAA score",
@@ -1830,6 +1830,22 @@ export function createKcc20SnapshotPsktBuilder(
     return amount;
   }
 
+  function positiveWideAmount(value, label) {
+    let amount;
+    try {
+      if (typeof value === "number" && !Number.isSafeInteger(value)) {
+        throw new Error("unsafe integer");
+      }
+      amount = BigInt(value);
+    } catch {
+      throw new Error(`${label} must be a positive unsigned two-limb integer`);
+    }
+    if (amount <= 0n || amount > (1n << 126n) - 1n) {
+      throw new Error(`${label} must be a positive unsigned two-limb integer`);
+    }
+    return amount;
+  }
+
   function nonnegativeI64(value, label) {
     let amount;
     try {