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

package/CHANGELOG.md

@@ -1,9 +1,13 @@
 # Changelog
 
-- Remove duplicate nested snapshot artifact files while preserving their public package subpaths as aliases to the canonical root artifacts.
+## 0.8.0-fee.0
+
+- Add fee arithmetic, grouped quotes, policy encoding, creator consent and claim commitments for DEV integration tests.
+- Keep transaction construction on the legacy market path; this prerelease does not build or authorize fee-market spends.
 
 ## 0.7.0
 
+- Remove duplicate nested snapshot artifact files while preserving their public package subpaths as aliases to the canonical root artifacts.
 - Support fixed snapshot supplies above one signed-64-bit KCC1 integer while keeping every holder and reserve amount signed-64-bit.
 - Bind wide fixed supplies with the domain-separated `KASPACOM/KCC20/HOLDER/V2` commitment and preserve V1 commitments for ordinary supplies.
 - Package the two-limb snapshot bootstrap/controller artifacts and encode their updated immutable state and start-plan commitments.

package/RELEASING.md

@@ -9,6 +9,8 @@ The package is published under the same version to both registries:
 
 Never publish different contents under the same version. npm package versions
 are immutable, so update `package.json` before each release.
+Prerelease versions use the `next` tag in both registries; stable versions use
+`latest`. Consumers must pin the full prerelease version.
 
 ## Publishing setup
 
@@ -90,9 +92,11 @@ A green publishing workflow confirms an upload, not consumer compatibility.
 Inspect the installed tarball and complete the live release gate before
 consumer deployment. Record any unverified operation families explicitly.
 
-## Snapshot release gate
+## Fee integration prerelease
 
-The current candidate is version `0.7.0`. Run `test:snapshot:transactions` with
-the pinned WASM and close the snapshot artifact reproduction and funded TN10
-construction gates before merging the release PR. The first publish run must
-confirm npm trusted publishing for this workflow.
+Version `0.8.0-fee.0` exposes accounting and policy helpers for DEV integration
+tests. It does not construct fee-market transactions. Run the existing snapshot
+and example tests against the pinned WASM before publishing it under `next`.
+Funded fee-market journeys and signed settlement construction remain required
+before enabling markets or promoting a stable fee release. Confirm trusted npm
+publishing in the first workflow run.

package/dist/cjs/escrow-fee.d.ts

@@ -0,0 +1,79 @@
+/** Fee arithmetic for new escrow markets only. Legacy trading is unchanged. */
+export declare const KCC20_ESCROW_POLICY_VERSION: 1;
+export declare const KCC20_ESCROW_PROTOCOL_BPS = 100;
+export declare const KCC20_ESCROW_MAX_CREATOR_BPS = 500;
+export declare const KCC20_ESCROW_MIN_FEE_SOMPI = 50000000n;
+export declare const KCC20_ESCROW_MAX_CLAIM_RECEIPTS = 5;
+export declare const KCC20_ESCROW_MAX_INT = 9223372036854775807n;
+export interface Kcc20EscrowFeeAmounts {
+    protocolFeeSompi: bigint;
+    creatorFeeSompi: bigint;
+    totalFeeSompi: bigint;
+}
+/** A waiver here is a quote assumption, never proof of FeeTicket eligibility. */
+export declare function calculateKcc20EscrowFees(input: {
+    grossSompi: bigint;
+    creatorFeeBps: number;
+    protocolWaived: boolean;
+}): Kcc20EscrowFeeAmounts;
+/** Trading-price components only; excludes network fees and storage deposits.
+ * One matched ask/bid is one fill. Call separately for independent fills. */
+export declare function quoteKcc20EscrowSettlement(input: {
+    grossSompi: bigint;
+    creatorFeeBps: number;
+    protocolWaived: boolean;
+    kind: "take-ask" | "fill-bid" | "cross-match";
+}): {
+    grossSompi: bigint;
+    buyerPaysSompi: bigint;
+    sellerReceivesSompi: bigint;
+    matcherPaysSompi: bigint;
+    requiresFeeOutput: boolean;
+    protocolFeeSompi: bigint;
+    creatorFeeSompi: bigint;
+    totalFeeSompi: bigint;
+};
+/** Arithmetic for one atomic trade group. Artifact and UTXO checks belong to
+ * the signed transaction builder; this quote does not authorize a FeeTicket. */
+export declare function quoteKcc20EscrowTradeGroup(input: {
+    kind: "take-ask" | "fill-bid" | "cross-match";
+    fillGrossSompi: readonly bigint[];
+    creatorFeeBps: number;
+    protocolWaived: boolean;
+}): {
+    feeVector: {
+        protocolFeeSompi: bigint;
+        creatorFeeSompi: bigint;
+    }[];
+    receiptValueSompi: bigint;
+    requiresFeeOutput: boolean;
+    grossSompi: bigint;
+    protocolFeeSompi: bigint;
+    creatorFeeSompi: bigint;
+    buyerPaysSompi: bigint;
+    sellerReceivesSompi: bigint;
+    matcherPaysSompi: bigint;
+};
+/** 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;
+}
+/** Computes a single claim's conservation amounts, without authorizing a spend. */
+export declare function calculateKcc20FeeClaim(receipts: readonly Kcc20FeeReceiptAmounts[], party: "protocol" | "creator"): {
+    claimSompi: bigint;
+    remainingProtocolSompi: bigint;
+    remainingCreatorSompi: bigint;
+    consumedSompi: bigint;
+    remainderSompi: bigint;
+};

package/dist/cjs/escrow-fee.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KCC20_ESCROW_MAX_INT = exports.KCC20_ESCROW_MAX_CLAIM_RECEIPTS = exports.KCC20_ESCROW_MIN_FEE_SOMPI = exports.KCC20_ESCROW_MAX_CREATOR_BPS = exports.KCC20_ESCROW_PROTOCOL_BPS = exports.KCC20_ESCROW_POLICY_VERSION = void 0;
+exports.calculateKcc20EscrowFees = calculateKcc20EscrowFees;
+exports.quoteKcc20EscrowSettlement = quoteKcc20EscrowSettlement;
+exports.quoteKcc20EscrowTradeGroup = quoteKcc20EscrowTradeGroup;
+exports.calculateKcc20FeeClaim = calculateKcc20FeeClaim;
+/** Fee arithmetic for new escrow markets only. Legacy trading is unchanged. */
+exports.KCC20_ESCROW_POLICY_VERSION = 1;
+exports.KCC20_ESCROW_PROTOCOL_BPS = 100;
+exports.KCC20_ESCROW_MAX_CREATOR_BPS = 500;
+exports.KCC20_ESCROW_MIN_FEE_SOMPI = 50000000n;
+exports.KCC20_ESCROW_MAX_CLAIM_RECEIPTS = 5;
+exports.KCC20_ESCROW_MAX_INT = 9223372036854775807n;
+function amount(value, name) {
+    if (typeof value !== "bigint" || value < 0n || value > exports.KCC20_ESCROW_MAX_INT) {
+        throw new Error(`${name} must be a nonnegative signed-64-bit bigint`);
+    }
+    return value;
+}
+function add(left, right) {
+    return amount(left + right, "sum");
+}
+function fee(gross, bps) {
+    // Match the contract without overflowing the intermediate multiplication.
+    const rate = BigInt(bps);
+    const percentage = (gross / 10000n) * rate + ((gross % 10000n) * rate) / 10000n;
+    return percentage < exports.KCC20_ESCROW_MIN_FEE_SOMPI ? exports.KCC20_ESCROW_MIN_FEE_SOMPI : percentage;
+}
+/** A waiver here is a quote assumption, never proof of FeeTicket eligibility. */
+function calculateKcc20EscrowFees(input) {
+    const gross = amount(input.grossSompi, "grossSompi");
+    if (gross < 50000000n)
+        throw new Error("fill gross must be at least 0.5 KAS");
+    if (!Number.isInteger(input.creatorFeeBps) || input.creatorFeeBps < 0 || input.creatorFeeBps > exports.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, exports.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. */
+function quoteKcc20EscrowSettlement(input) {
+    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. */
+function quoteKcc20EscrowTradeGroup(input) {
+    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,
+    };
+}
+function id(value) {
+    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. */
+function calculateKcc20FeeClaim(receipts, party) {
+    if (party !== "protocol" && party !== "creator")
+        throw new Error("unknown claiming party");
+    if (!Array.isArray(receipts) || receipts.length < 1 || receipts.length > exports.KCC20_ESCROW_MAX_CLAIM_RECEIPTS) {
+        throw new Error("claim must select between one and five receipts");
+    }
+    const seen = new Set();
+    let group;
+    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 < exports.KCC20_ESCROW_MIN_FEE_SOMPI) || (c > 0n && c < exports.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) };
+}
+//# sourceMappingURL=escrow-fee.js.map

package/dist/cjs/escrow-fee.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escrow-fee.js","sourceRoot":"","sources":["../../src/escrow-fee.ts"],"names":[],"mappings":"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"}

package/dist/cjs/escrow-policy.d.ts

@@ -0,0 +1,72 @@
+import { 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;
+    };
+}
+export declare function encodeKcc20EscrowPolicy(policy: Kcc20EscrowPolicy): Uint8Array;
+export declare function decodeKcc20EscrowPolicy(bytes: Uint8Array): Kcc20EscrowPolicy;
+export declare function kcc20EscrowPolicyId(input: {
+    tokenId: string;
+    feeTicketId: string;
+    priceScale: bigint;
+    policy: Kcc20EscrowPolicy;
+}): string;
+/** 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 declare function kcc20CreatorFeeConsent(input: {
+    tokenId: string;
+    marketId: string;
+    feeTicketId: string;
+    priceScale: bigint;
+    policy: Kcc20EscrowPolicy;
+}): {
+    commitment: string;
+    message: string;
+    personalMessageHash: string;
+};
+/** Input order must match the covenant family's consensus input order. */
+export declare 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;

package/dist/cjs/escrow-policy.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeKcc20EscrowPolicy = encodeKcc20EscrowPolicy;
+exports.decodeKcc20EscrowPolicy = decodeKcc20EscrowPolicy;
+exports.kcc20EscrowPolicyId = kcc20EscrowPolicyId;
+exports.kcc20CreatorFeeConsent = kcc20CreatorFeeConsent;
+exports.kcc20FeeClaimCommitment = kcc20FeeClaimCommitment;
+const blake3_1 = require("@noble/hashes/blake3");
+const blake2b_1 = require("@noble/hashes/blake2b");
+const escrow_fee_js_1 = require("./escrow-fee.js");
+const ZERO = "0".repeat(64);
+function hex32(value, allowZero = false) {
+    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) {
+    return Array.from(value, byte => byte.toString(16).padStart(2, "0")).join("");
+}
+function int64(value) {
+    if (typeof value !== "bigint" || value < 0n || value > 0x7fffffffffffffffn)
+        throw new Error("expected nonnegative int64");
+    const result = new Uint8Array(8);
+    new DataView(result.buffer).setBigUint64(0, value, true);
+    return result;
+}
+function concat(...parts) {
+    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) {
+    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)));
+}
+function encodeKcc20EscrowPolicy(policy) {
+    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));
+}
+function decodeKcc20EscrowPolicy(bytes) {
+    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) => {
+        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) => ({ hash: hex(bytes.slice(offset, offset + 32)),
+        prefixLength: integer(offset + 32), suffixLength: integer(offset + 40) });
+    const policy = {
+        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;
+}
+function kcc20EscrowPolicyId(input) {
+    if (typeof input.priceScale !== "bigint" || input.priceScale <= 0n)
+        throw new Error("priceScale must be positive");
+    return hex((0, blake3_1.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.
+ */
+function kcc20CreatorFeeConsent(input) {
+    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((0, blake3_1.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((0, blake2b_1.blake2b)(encoder.encode(message), {
+        dkLen: 32, key: encoder.encode("PersonalMessageSigningHash"),
+    }));
+    return { commitment, message, personalMessageHash };
+}
+function outpoint(value) {
+    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. */
+function kcc20FeeClaimCommitment(input) {
+    const amounts = (0, escrow_fee_js_1.calculateKcc20FeeClaim)(input.receipts, input.party);
+    if (!(input.payoutScriptPublicKey instanceof Uint8Array) || input.payoutScriptPublicKey.length < 3)
+        throw new Error("serialized payout ScriptPublicKey is required");
+    let receiptHash = new Uint8Array(32);
+    for (const receipt of input.receipts)
+        receiptHash = (0, blake3_1.blake3)(concat(receiptHash, outpoint(receipt.outpoint)));
+    const first = input.receipts[0];
+    return hex((0, blake3_1.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), (0, blake3_1.blake3)(input.payoutScriptPublicKey))));
+}
+//# sourceMappingURL=escrow-policy.js.map

package/dist/cjs/escrow-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escrow-policy.js","sourceRoot":"","sources":["../../src/escrow-policy.ts"],"names":[],"mappings":"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"}

package/dist/cjs/index.d.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/dist/cjs/index.js

@@ -35,6 +35,8 @@ __exportStar(require("./paid-mint-amount.js"), exports);
 __exportStar(require("./token-amount.js"), exports);
 __exportStar(require("./token-operation.js"), exports);
 __exportStar(require("./trade-fee.js"), exports);
+__exportStar(require("./escrow-fee.js"), exports);
+__exportStar(require("./escrow-policy.js"), exports);
 __exportStar(require("./trading-operation.js"), exports);
 __exportStar(require("./protocol.js"), exports);
 __exportStar(require("./runtime.js"), exports);

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,iDAA+B;AAC/B,sDAAoC;AACpC,gEAA8C;AAC9C,8DAA4C;AAC5C,2CAAyB;AACzB,+CAA6B;AAC7B,wDAAsC;AACtC,sDAAoC;AACpC,8CAA4B;AAC5B,gDAA8B;AAC9B,8CAA4B;AAC5B,4DAA0C;AAC1C,2DAAyC;AACzC,mEAAiD;AACjD,8CAA4B;AAC5B,kDAAgC;AAChC,wDAAsC;AACtC,oDAAkC;AAClC,uDAAqC;AACrC,iDAA+B;AAC/B,yDAAuC;AACvC,gDAA8B;AAC9B,+CAA6B;AAC7B,iDAA+C;AAC/C,uDAAqC;AACrC,yDAAuC;AACvC,0DAAwC;AACxC,2DAAyC;AACzC,wEAAsD;AACtD,qDAAmC;AACnC,wDAAsC;AACtC,yDAAuC;AACvC,wDAAsC;AAEtC,uDAAqD;AACrD,gFAA8E;AAC9E,2DAAyC;AACzC,6DAA2C;AAE3C,2DAAyC;AAEzC,wDAAsC;AACtC,wDAAsC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,iDAA+B;AAC/B,sDAAoC;AACpC,gEAA8C;AAC9C,8DAA4C;AAC5C,2CAAyB;AACzB,+CAA6B;AAC7B,wDAAsC;AACtC,sDAAoC;AACpC,8CAA4B;AAC5B,gDAA8B;AAC9B,8CAA4B;AAC5B,4DAA0C;AAC1C,2DAAyC;AACzC,mEAAiD;AACjD,8CAA4B;AAC5B,kDAAgC;AAChC,wDAAsC;AACtC,oDAAkC;AAClC,uDAAqC;AACrC,iDAA+B;AAC/B,kDAAgC;AAChC,qDAAmC;AACnC,yDAAuC;AACvC,gDAA8B;AAC9B,+CAA6B;AAC7B,iDAA+C;AAC/C,uDAAqC;AACrC,yDAAuC;AACvC,0DAAwC;AACxC,2DAAyC;AACzC,wEAAsD;AACtD,qDAAmC;AACnC,wDAAsC;AACtC,yDAAuC;AACvC,wDAAsC;AAEtC,uDAAqD;AACrD,gFAA8E;AAC9E,2DAAyC;AACzC,6DAA2C;AAE3C,2DAAyC;AAEzC,wDAAsC;AACtC,wDAAsC"}

package/dist/escrow-fee.d.ts

@@ -0,0 +1,80 @@
+/** Fee arithmetic for new escrow markets only. Legacy trading is unchanged. */
+export declare const KCC20_ESCROW_POLICY_VERSION: 1;
+export declare const KCC20_ESCROW_PROTOCOL_BPS = 100;
+export declare const KCC20_ESCROW_MAX_CREATOR_BPS = 500;
+export declare const KCC20_ESCROW_MIN_FEE_SOMPI = 50000000n;
+export declare const KCC20_ESCROW_MAX_CLAIM_RECEIPTS = 5;
+export declare const KCC20_ESCROW_MAX_INT = 9223372036854775807n;
+export interface Kcc20EscrowFeeAmounts {
+    protocolFeeSompi: bigint;
+    creatorFeeSompi: bigint;
+    totalFeeSompi: bigint;
+}
+/** A waiver here is a quote assumption, never proof of FeeTicket eligibility. */
+export declare function calculateKcc20EscrowFees(input: {
+    grossSompi: bigint;
+    creatorFeeBps: number;
+    protocolWaived: boolean;
+}): Kcc20EscrowFeeAmounts;
+/** Trading-price components only; excludes network fees and storage deposits.
+ * One matched ask/bid is one fill. Call separately for independent fills. */
+export declare function quoteKcc20EscrowSettlement(input: {
+    grossSompi: bigint;
+    creatorFeeBps: number;
+    protocolWaived: boolean;
+    kind: "take-ask" | "fill-bid" | "cross-match";
+}): {
+    grossSompi: bigint;
+    buyerPaysSompi: bigint;
+    sellerReceivesSompi: bigint;
+    matcherPaysSompi: bigint;
+    requiresFeeOutput: boolean;
+    protocolFeeSompi: bigint;
+    creatorFeeSompi: bigint;
+    totalFeeSompi: bigint;
+};
+/** Arithmetic for one atomic trade group. Artifact and UTXO checks belong to
+ * the signed transaction builder; this quote does not authorize a FeeTicket. */
+export declare function quoteKcc20EscrowTradeGroup(input: {
+    kind: "take-ask" | "fill-bid" | "cross-match";
+    fillGrossSompi: readonly bigint[];
+    creatorFeeBps: number;
+    protocolWaived: boolean;
+}): {
+    feeVector: {
+        protocolFeeSompi: bigint;
+        creatorFeeSompi: bigint;
+    }[];
+    receiptValueSompi: bigint;
+    requiresFeeOutput: boolean;
+    grossSompi: bigint;
+    protocolFeeSompi: bigint;
+    creatorFeeSompi: bigint;
+    buyerPaysSompi: bigint;
+    sellerReceivesSompi: bigint;
+    matcherPaysSompi: bigint;
+};
+/** 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;
+}
+/** Computes a single claim's conservation amounts, without authorizing a spend. */
+export declare function calculateKcc20FeeClaim(receipts: readonly Kcc20FeeReceiptAmounts[], party: "protocol" | "creator"): {
+    claimSompi: bigint;
+    remainingProtocolSompi: bigint;
+    remainingCreatorSompi: bigint;
+    consumedSompi: bigint;
+    remainderSompi: bigint;
+};
+//# sourceMappingURL=escrow-fee.d.ts.map

package/dist/escrow-fee.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escrow-fee.d.ts","sourceRoot":"","sources":["../src/escrow-fee.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,eAAO,MAAM,2BAA2B,EAAG,CAAU,CAAC;AACtD,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAC7C,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAChD,eAAO,MAAM,0BAA0B,YAAc,CAAC;AACtD,eAAO,MAAM,+BAA+B,IAAI,CAAC;AACjD,eAAO,MAAM,oBAAoB,uBAA6B,CAAC;AAE/D,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACvB;AAoBD,iFAAiF;AACjF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;CACzB,GAAG,qBAAqB,CAUxB;AAED;6EAC6E;AAC7E,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,aAAa,CAAC;CAC/C;;;;;;sBA/CmB,MAAM;qBACP,MAAM;mBACR,MAAM;EA2DtB;AAED;gFACgF;AAChF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAChD,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,aAAa,CAAC;IAC9C,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;CACzB;;;;;;;;;;;;;EAiCA;AAED,qGAAqG;AACrG,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB;AAOD,mFAAmF;AACnF,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,EAC3C,KAAK,EAAE,UAAU,GAAG,SAAS;;;;;;EA6C9B"}