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

package/src/engine.ts

@@ -77,6 +77,7 @@ import {
   ownerAuthorizationWitness,
 } from "./abi.js";
 import { KCC20_BUILDER_KEYS } from "./operations.js";
+import { buildKcc20InitialFeeAccount, planKcc20FeeAccountBinding } from "./escrow-account-setup.js";
 import { createKcc20SnapshotPsktBuilder } from "./snapshot-operation.js";
 import { splitKcc20MintSupply } from "./protocol.js";
 import { buildKcc20DeployIntentOutputs } from "./deploy-receipt.js";
@@ -553,6 +554,8 @@ export function createKcc20PsktBuilderEngine(
     "fee-ticket.create-from-utility-burn": buildFeeTicketCreatePskt,
     "fee-ticket.burn": buildFeeTicketBurnPskt,
     "fee-ticket.transfer": buildFeeTicketTransferPskt,
+    "kcc20fee.create-account": buildFeeAccountCreatePskt,
+    "kcc20fee.bind-account": buildFeeAccountBindPskt,
     "kcc20wrapper.deploy-market": buildWrapperMarketDeployPskt,
     "kcc20wrapper.wrap": buildWrapperWrapPskt,
     "kcc20wrapper.unwrap": buildWrapperUnwrapPskt,
@@ -606,6 +609,298 @@ export function createKcc20PsktBuilderEngine(
     return builder(input);
   }
 
+  async function buildFeeAccountCreatePskt(input) {
+    const request = input.request || {};
+    const params = request.params || {};
+    const tokenId = requireHex32(params.tokenId, "fee account token id");
+    const owner = requireHex32(request.owner?.kcc20Owner, "fee account owner");
+    const principalSompi = parseU64(params.principalSompi, "fee account principal");
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
+    const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
+    assertFeeAccountSchnorrWalletOwner(walletAddress, owner);
+    const priorityFee = parseU64(
+      env.KCC20_FEE_ACCOUNT_PRIORITY_FEE_SOMPI || DEFAULT_PRIORITY_FEE.toString(),
+      "priorityFee",
+    );
+    const artifactKey = "KCC20FeeEscrowV1.placeholder.json";
+    const supplied = options.artifacts?.[artifactKey] ?? await options.artifactProvider?.(artifactKey);
+    const artifact = supplied?.artifact ?? supplied;
+    if (!artifact) throw new Error("missing pinned fee escrow artifact");
+    const initial = buildKcc20InitialFeeAccount({
+      artifact, tokenId, ownerSchnorrPublicKey: owner, principalSompi,
+    });
+    const kw = kaspaWasm;
+    const { Encoding, GenesisCovenantGroup, RpcClient, Transaction,
+      TransactionOutput, covenantId, payToAddressScript, payToScriptHashScript } = kw;
+    const rpc = new RpcClient({
+      url: env.KASPA_WRPC_URL || DEFAULT_WRPC_URL,
+      encoding: Encoding.Borsh,
+      networkId: network,
+    });
+    await rpc.connect();
+    try {
+      const walletUtxos = await getUtxosByAddresses(rpc, [walletAddress]);
+      const fundingEntry = selectFundingEntry(
+        walletUtxos.entries,
+        principalSompi + priorityFee + 10_000n,
+        [],
+        params.fundingOutpoint,
+      );
+      const fundingAmount = utxoAmountSompi(fundingEntry);
+      const change = fundingAmount - principalSompi - priorityFee;
+      if (change <= 10_000n) throw new Error("fee account creation funding change is too small");
+      const transaction = new Transaction({
+        version: 1,
+        lockTime: 0n,
+        inputs: [{ previousOutpoint: fundingEntry.outpoint, utxo: fundingEntry,
+          sequence: 0n, sigOpCount: 0, computeBudget: 30 }],
+        outputs: [
+          new TransactionOutput(principalSompi, payToScriptHashScript(initial.redeemScript)),
+          new TransactionOutput(change, payToAddressScript(walletAddress)),
+        ],
+        subnetworkId: SUBNETWORK_ID_NATIVE,
+        gas: 0n,
+        payload: "",
+      });
+      setVersionOneInputMassFields(transaction, 30);
+      transaction.populateGenesisCovenants([new GenesisCovenantGroup(0, [0])]);
+      transaction.finalize();
+      const accountId = transaction.outputs[0]?.covenant?.covenantId?.toString();
+      if (!accountId) throw new Error("fee account genesis covenant id is missing");
+      const expectedId = covenantId(fundingEntry.outpoint, [
+        { index: 0, output: transaction.outputs[0] },
+      ]).toString();
+      if (accountId !== expectedId) throw new Error("fee account genesis covenant id mismatch");
+      const feeResult = transactionWithPredictedSignedFeeChange(
+        kw, transaction, 1, network, "fee account creation", candidate => {
+          const predicted = cloneTransactionForMassPreflight(kw, candidate, "fee account creation");
+          predicted.inputs[0].signatureScript = encodeP2pkSignatureScript(bytesToHex(dummySignatureBytes()));
+          return predicted;
+        },
+      );
+      const nonContextualMass = calculateToccataV1NonContextualMass(
+        feeResult.predictedTransaction, "fee account creation",
+      ).transactionMass;
+      const storageMass = calculateToccataStorageMass(
+        feeResult.predictedTransaction, "fee account creation",
+      );
+      if (nonContextualMass > CONSOLIDATION_TARGET_TRANSACTION_MASS ||
+          storageMass > CONSOLIDATION_TARGET_TRANSACTION_MASS) {
+        throw kcc20PsktBuilderError(
+          "fee account creation exceeds the signed transaction mass target",
+          "TRANSACTION_MASS_EXCEEDED",
+          { nonContextualMass, storageMass, targetMass: CONSOLIDATION_TARGET_TRANSACTION_MASS },
+        );
+      }
+      const finalAccountId = covenantId(fundingEntry.outpoint, [
+        { index: 0, output: feeResult.transaction.outputs[0] },
+      ]).toString();
+      if (finalAccountId !== accountId) throw new Error("fee account genesis id changed after fee calculation");
+      const psktTransactionJson = feeResult.transaction.serializeToSafeJSON();
+      if (typeof psktTransactionJson !== "string") throw new Error("fee account creation PSKT serialization failed");
+      return {
+        schema: OUTPUT_SCHEMA,
+        psktTransactionJson,
+        signInputs: [{ index: 0, sighashType: 1 }],
+        scripts: [],
+        submitTransactionSupported: true,
+        metadata: {
+          builderKey: "kcc20fee.create-account",
+          operation: "create-fee-account",
+          action: "genesis",
+          contract: "KCC20FeeEscrowV1",
+          network, walletAddress, tokenId, owner, accountId,
+          accountPrincipalSompi: principalSompi.toString(),
+          // Attach the broadcast txid to this hint before binding. The first
+          // spend reveals the script; until then the indexer sees only P2SH.
+          accountGenesisHint: {
+            vout: 0,
+            address: kw.addressFromScriptPublicKey(
+              payToScriptHashScript(initial.redeemScript), network,
+            ).toString(),
+            covenantIdHex: accountId,
+            scriptHashHex: initial.scriptHash,
+            amountSompiExact: principalSompi.toString(),
+            state: { ...initial.state, roleName: "account" },
+          },
+        },
+      };
+    } finally {
+      await rpc.disconnect();
+    }
+  }
+
+  async function buildFeeAccountBindPskt(input) {
+    const request = input.request || {};
+    const params = request.params || {};
+    // A genesis output has no revealed script yet. The caller keeps the
+    // creation hint, adds its accepted txid, then we check the live UTXO.
+    const indexed = params.accountGenesisHint
+      ? { ...params.accountGenesisHint, status: "active", spentByTxidHex: null }
+      : params.activeAccountUtxo;
+    if (!indexed || !indexed.address) throw new Error("active unbound fee account UTXO and address are required");
+    const tokenId = requireHex32(params.tokenId, "fee account token id");
+    const accountId = requireHex32(params.accountId, "fee account id");
+    const marketId = requireHex32(params.marketId, "fee account market id");
+    const policyId = requireHex32(params.policyId, "fee account policy id");
+    const owner = requireHex32(request.owner?.kcc20Owner, "fee account owner");
+    if (String(indexed.state?.owner || "").toLowerCase() !== owner) {
+      throw new Error("fee account owner does not match connected wallet");
+    }
+    const network = request.network || env.KASPA_NETWORK || "testnet-10";
+    const walletAddress = requireKaspaAddress(request.owner?.walletAddress);
+    assertFeeAccountSchnorrWalletOwner(walletAddress, owner);
+    const accountAddress = requireKaspaAddress(indexed.address);
+    const priorityFee = parseU64(
+      env.KCC20_FEE_ACCOUNT_PRIORITY_FEE_SOMPI || DEFAULT_PRIORITY_FEE.toString(),
+      "priorityFee",
+    );
+    const computeBudget = parsePositiveNumber(
+      env.KCC20_FEE_ACCOUNT_COMPUTE_BUDGET || 500,
+      "computeBudget",
+    );
+    const artifactKey = "KCC20FeeEscrowV1.placeholder.json";
+    const supplied = options.artifacts?.[artifactKey] ?? await options.artifactProvider?.(artifactKey);
+    const artifact = supplied?.artifact ?? supplied;
+    if (!artifact) throw new Error("missing pinned fee escrow artifact");
+
+    const kw = kaspaWasm;
+    const { CovenantBinding, Encoding, Hash, RpcClient, Transaction,
+      TransactionOutput, payToAddressScript, payToScriptHashScript } = kw;
+    const rpc = new RpcClient({
+      url: env.KASPA_WRPC_URL || DEFAULT_WRPC_URL,
+      encoding: Encoding.Borsh,
+      networkId: network,
+    });
+    await rpc.connect();
+    try {
+      const [accountUtxos, walletUtxos] = await Promise.all([
+        getUtxosByAddresses(rpc, [accountAddress]),
+        getUtxosByAddresses(rpc, [walletAddress]),
+      ]);
+      const txid = requireHex32(indexed.txidHex, "fee account txid");
+      const vout = parseVout(indexed.vout, "fee account vout");
+      const accountEntry = findUtxoEntry(accountUtxos.entries, txid, vout);
+      if (!accountEntry) throw new Error("unbound fee account UTXO is spent or unavailable");
+      requireMatchingCovenantId(accountEntry, accountId, "unbound fee account");
+      const spk = accountEntry.scriptPublicKey ??
+        accountEntry.entry?.scriptPublicKey ?? accountEntry.utxoEntry?.scriptPublicKey;
+      const scriptBytes = spk?.script;
+      if (!spk || !scriptBytes) throw new Error("unbound fee account has no script public key");
+      const scriptHex = typeof scriptBytes === "string" ? scriptBytes : bytesToHex(scriptBytes);
+      const plan = planKcc20FeeAccountBinding({
+        artifact,
+        indexed,
+        live: {
+          outpoint: { transactionId: txid, index: vout },
+          amountSompi: utxoAmountSompi(accountEntry),
+          covenantIdHex: accountId,
+          scriptPublicKey: { version: Number(spk.version), scriptHex },
+        },
+        tokenId, accountId, marketId, policyId,
+      });
+      assertScriptAddress(kw, plan.currentRedeemScript, accountAddress, network, "unbound fee account address");
+      const fundingEntry = selectFundingEntry(
+        walletUtxos.entries,
+        priorityFee + 10_000n,
+        [accountEntry.outpoint],
+        params.fundingOutpoint,
+      );
+      const fundingAmount = utxoAmountSompi(fundingEntry);
+      if (fundingAmount <= priorityFee + 10_000n) throw new Error("fee account binding funding change is too small");
+      const unsignedTx = new Transaction({
+        version: 1,
+        lockTime: 0n,
+        inputs: [
+          { previousOutpoint: accountEntry.outpoint, utxo: accountEntry,
+            sequence: 0n, sigOpCount: 0, computeBudget },
+          { previousOutpoint: fundingEntry.outpoint, utxo: fundingEntry,
+            sequence: 0n, sigOpCount: 0, computeBudget: 30 },
+        ],
+        outputs: [
+          new TransactionOutput(
+            plan.successorAmountSompi,
+            payToScriptHashScript(plan.successorRedeemScript),
+            new CovenantBinding(0, new Hash(accountId)),
+          ),
+          new TransactionOutput(
+            fundingAmount - priorityFee,
+            payToAddressScript(walletAddress),
+          ),
+        ],
+        subnetworkId: SUBNETWORK_ID_NATIVE,
+        gas: 0n,
+        payload: "",
+      });
+      setVersionOneInputMassFields(unsignedTx, computeBudget);
+      unsignedTx.inputs[1].computeBudget = 30;
+      assertUniqueTransactionInputOutpoints(unsignedTx, "fee account binding");
+      const scripts = [{
+        inputIndex: 0,
+        scriptHex: bytesToHex(plan.currentRedeemScript),
+        signType: 1,
+        signatureScript: {
+          mode: "ordered-args",
+          args: [
+            dataTemplateArg(hexToBytes(marketId)),
+            dataTemplateArg(hexToBytes(policyId)),
+            { type: "signature" },
+            i64TemplateArg(0),
+            dataTemplateArg(dispatchTagFor(artifact, "bindMarket")),
+          ],
+        },
+      }];
+      const feeResult = transactionWithPredictedSignedFeeChange(
+        kw, unsignedTx, 1, network, "fee account binding", candidate => {
+          const serialized = candidate.serializeToSafeJSON();
+          if (typeof serialized !== "string") throw new Error("fee account mass preflight serialization failed");
+          const predictedJson = transactionJsonWithScriptHints(kw, JSON.parse(serialized), scripts);
+          predictedJson.inputs[1].signatureScript = encodeP2pkSignatureScript(
+            bytesToHex(dummySignatureBytes()),
+          );
+          return typeof kw.Transaction.deserializeFromSafeJSON === "function"
+            ? kw.Transaction.deserializeFromSafeJSON(JSON.stringify(predictedJson))
+            : kw.Transaction.deserializeFromJSON(JSON.stringify(predictedJson));
+        },
+      );
+      const nonContextualMass = calculateToccataV1NonContextualMass(
+        feeResult.predictedTransaction, "fee account binding",
+      ).transactionMass;
+      const storageMass = calculateToccataStorageMass(
+        feeResult.predictedTransaction, "fee account binding",
+      );
+      if (nonContextualMass > CONSOLIDATION_TARGET_TRANSACTION_MASS ||
+          storageMass > CONSOLIDATION_TARGET_TRANSACTION_MASS) {
+        throw kcc20PsktBuilderError(
+          "fee account binding exceeds the signed transaction mass target",
+          "TRANSACTION_MASS_EXCEEDED",
+          { nonContextualMass, storageMass, targetMass: CONSOLIDATION_TARGET_TRANSACTION_MASS },
+        );
+      }
+      const transaction = feeResult.transaction;
+      const psktTransactionJson = transaction.serializeToSafeJSON();
+      if (typeof psktTransactionJson !== "string") throw new Error("fee account binding PSKT serialization failed");
+      return {
+        schema: OUTPUT_SCHEMA,
+        psktTransactionJson,
+        signInputs: [{ index: 1, sighashType: 1 }],
+        scripts,
+        submitTransactionSupported: true,
+        metadata: {
+          builderKey: "kcc20fee.bind-account",
+          operation: "bind-fee-account",
+          action: "bindMarket",
+          contract: "KCC20FeeEscrowV1",
+          network, walletAddress, tokenId, accountId, marketId, policyId,
+          accountInput: `${txid}:${vout}`,
+          accountPrincipalSompi: plan.successorAmountSompi.toString(),
+        },
+      };
+    } finally {
+      await rpc.disconnect();
+    }
+  }
+
   async function buildFeeTicketRootUpdatePskt(input) {
     const request = input.request || {};
     const params = request.params || {};
@@ -13453,6 +13748,17 @@ export function createKcc20PsktBuilderEngine(
     return address;
   }
 
+  function assertFeeAccountSchnorrWalletOwner(walletAddress, owner) {
+    const script = String(kaspaWasm.payToAddressScript(walletAddress).script)
+      .toLowerCase();
+    const publicKey = /^20([0-9a-f]{64})ac$/.exec(script)?.[1];
+    if (!publicKey || publicKey !== owner) {
+      throw new Error(
+        "fee account owner must match the connected Schnorr wallet address",
+      );
+    }
+  }
+
   return {
     build: buildInProcessPskt,
     buildInProcessPskt,

package/src/escrow-account-setup.ts

@@ -0,0 +1,124 @@
+import { normalizeSilverScriptArtifact, templateParts } from "./abi.js";
+import { KCC20_ESCROW_MAX_INT } from "./escrow-fee.js";
+import type { Kcc20FeeAccountState } from "./escrow-claim-plan.js";
+import {
+  buildKcc20FeeEscrowScript,
+  verifyKcc20UnboundFeeAccountForBinding,
+  type Kcc20IndexedFeeReceipt,
+  type Kcc20LiveFeeReceiptUtxo,
+} from "./escrow-receipt.js";
+
+const ZERO = "00".repeat(32);
+const SECP256K1_FIELD = (1n << 256n) - (1n << 32n) - 977n;
+
+function hex32(value: string, label: string): string {
+  if (typeof value !== "string" || !/^[0-9a-f]{64}$/i.test(value)) {
+    throw new Error(`${label} must be 32-byte hex`);
+  }
+  return value.toLowerCase();
+}
+
+function principal(value: bigint): bigint {
+  if (typeof value !== "bigint" || value <= 0n || value > KCC20_ESCROW_MAX_INT) {
+    throw new Error("fee account principal must be a positive contract-range bigint");
+  }
+  return value;
+}
+
+function modPow(base: bigint, exponent: bigint): bigint {
+  let result = 1n;
+  let factor = base % SECP256K1_FIELD;
+  for (let remaining = exponent; remaining > 0n; remaining >>= 1n) {
+    if (remaining & 1n) result = (result * factor) % SECP256K1_FIELD;
+    factor = (factor * factor) % SECP256K1_FIELD;
+  }
+  return result;
+}
+
+/** BIP340 keys encode an x-coordinate that must lift to a secp256k1 point. */
+function requireSchnorrXOnlyPublicKey(value: string): string {
+  const key = hex32(value, "owner Schnorr public key");
+  const x = BigInt(`0x${key}`);
+  if (x >= SECP256K1_FIELD) throw new Error("owner Schnorr public key is not a curve point");
+  const square = (x * x % SECP256K1_FIELD * x + 7n) % SECP256K1_FIELD;
+  const y = modPow(square, (SECP256K1_FIELD + 1n) / 4n);
+  if (y * y % SECP256K1_FIELD !== square) {
+    throw new Error("owner Schnorr public key is not a curve point");
+  }
+  return key;
+}
+
+/**
+ * Construct the initial account output. Its covenant lineage is assigned by
+ * the transaction; the market can bind that lineage only after it is known.
+ * This function does not select funding, sign, or estimate transaction mass.
+ */
+export function buildKcc20InitialFeeAccount(input: {
+  artifact: unknown;
+  tokenId: string;
+  ownerSchnorrPublicKey: string;
+  principalSompi: bigint;
+}) {
+  const token = hex32(input.tokenId, "token");
+  const owner = requireSchnorrXOnlyPublicKey(input.ownerSchnorrPublicKey);
+  if (token === ZERO || owner === ZERO) throw new Error("fee account token and owner must be nonzero");
+  const amountSompi = principal(input.principalSompi);
+  const template = templateParts(normalizeSilverScriptArtifact(input.artifact));
+  const state: Kcc20FeeAccountState = {
+    role: "1", token, market: ZERO, policy: ZERO,
+    protocol_account: ZERO, creator_account: ZERO,
+    protocol_amount: "0", creator_amount: "0", owner,
+    owner_scheme: 0, guard_template: ZERO, guard_prefix: "0", guard_suffix: "0",
+    action_hash: ZERO,
+    self_template: toHex(template.hash),
+    self_prefix: String(template.prefixLength), self_suffix: String(template.suffixLength),
+  };
+  return { state, amountSompi, ...buildKcc20FeeEscrowScript(input.artifact, state as unknown as Record<string, unknown>) };
+}
+
+function toHex(bytes: Uint8Array): string {
+  return Array.from(bytes, byte => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Verify the current unbound account output and plan the exact continuation.
+ * The owner signs bindMarket once; later claims use the account's authority.
+ */
+export function planKcc20FeeAccountBinding(input: {
+  artifact: unknown;
+  indexed: Kcc20IndexedFeeReceipt;
+  live: Kcc20LiveFeeReceiptUtxo;
+  tokenId: string;
+  accountId: string;
+  marketId: string;
+  policyId: string;
+}) {
+  const market = hex32(input.marketId, "market");
+  const policy = hex32(input.policyId, "policy");
+  if (market === ZERO || policy === ZERO) throw new Error("fee account binding requires a market and policy");
+  const verified = verifyKcc20UnboundFeeAccountForBinding({
+    artifact: input.artifact,
+    indexed: input.indexed,
+    live: input.live,
+    expected: { tokenId: input.tokenId, accountId: input.accountId },
+  });
+  const successorState: Kcc20FeeAccountState = {
+    ...verified.account.state,
+    market, policy,
+  };
+  const successor = buildKcc20FeeEscrowScript(
+    input.artifact,
+    successorState as unknown as Record<string, unknown>,
+  );
+  return {
+    entrypoint: "bindMarket" as const,
+    account: verified.account,
+    currentRedeemScript: verified.redeemScript,
+    successorState,
+    successorRedeemScript: successor.redeemScript,
+    successorScriptPublicKey: successor.scriptPublicKey,
+    successorAmountSompi: verified.account.principalSompi,
+    requiresOwnerSchnorrSignature: true as const,
+    requiresSeparateNetworkFunding: true as const,
+  };
+}

package/src/escrow-receipt.ts

@@ -87,6 +87,39 @@ function encodeState(state: Record<string, unknown>): Uint8Array {
   return Uint8Array.from(encoded);
 }
 
+/** Render an escrow state using only the packaged, pinned v1 program. */
+export function buildKcc20FeeEscrowScript(artifactInput: unknown, state: Record<string, unknown>) {
+  const artifactHash = Array.from(sha256(new TextEncoder().encode(JSON.stringify(artifactInput))),
+    byte => byte.toString(16).padStart(2, "0")).join("");
+  if (artifactHash !== ARTIFACT_CANONICAL_SHA256) throw new Error("fee escrow artifact metadata mismatch");
+  const artifact = normalizeSilverScriptArtifact(artifactInput);
+  assertKcc20ArtifactScriptHash(ARTIFACT_KEY, artifact);
+  if (artifact.contract_name !== "KCC20FeeEscrowV1" ||
+      artifact.state_layout?.start !== STATE_START || artifact.state_layout?.len !== STATE_LENGTH) {
+    throw new Error("unsupported fee escrow artifact layout");
+  }
+  const base = Uint8Array.from(artifact.script);
+  const prefix = base.slice(0, STATE_START);
+  const suffix = base.slice(STATE_START + STATE_LENGTH);
+  const hash = Array.from(templateHash(prefix, suffix), byte => byte.toString(16).padStart(2, "0")).join("");
+  if (hex32(state.self_template, "self_template") !== hash ||
+      natural(state.self_prefix, "self_prefix") !== BigInt(prefix.length) ||
+      natural(state.self_suffix, "self_suffix") !== BigInt(suffix.length)) {
+    throw new Error("fee escrow self-template mismatch");
+  }
+  const redeemScript = new Uint8Array(prefix.length + STATE_LENGTH + suffix.length);
+  redeemScript.set(prefix);
+  redeemScript.set(encodeState(state), prefix.length);
+  redeemScript.set(suffix, prefix.length + STATE_LENGTH);
+  const scriptHash = Array.from(blake2b(redeemScript, { dkLen: 32 }), byte => byte.toString(16).padStart(2, "0")).join("");
+  return {
+    redeemScript,
+    scriptHash,
+    scriptPublicKey: { version: 0 as const, scriptHex: `aa20${scriptHash}87` },
+    escrowTemplate: { hash, prefixLength: prefix.length, suffixLength: suffix.length },
+  };
+}
+
 /**
  * Check a receipt hint against the pinned program and a fresh node UTXO.
  * The caller must fetch `live` from a qualified canonical node, authenticate
@@ -189,6 +222,30 @@ export function verifyKcc20FeeAccountForClaim(input: {
   expected: { tokenId: string; marketId: string; policyId: string; accountId: string };
 }): { account: Kcc20FeeClaimAccount; redeemScript: Uint8Array;
       escrowTemplate: { hash: string; prefixLength: number; suffixLength: number } } {
+  return verifyFeeAccount(input, false);
+}
+
+/** Verify an unbound account before its one-time market binding. */
+export function verifyKcc20UnboundFeeAccountForBinding(input: {
+  artifact: unknown;
+  indexed: Kcc20IndexedFeeReceipt;
+  live: Kcc20LiveFeeReceiptUtxo;
+  expected: { tokenId: string; accountId: string };
+}): { account: Kcc20FeeClaimAccount; redeemScript: Uint8Array;
+      escrowTemplate: { hash: string; prefixLength: number; suffixLength: number } } {
+  return verifyFeeAccount({
+    ...input,
+    expected: { ...input.expected, marketId: ZERO, policyId: ZERO },
+  }, true);
+}
+
+function verifyFeeAccount(input: {
+  artifact: unknown;
+  indexed: Kcc20IndexedFeeReceipt;
+  live: Kcc20LiveFeeReceiptUtxo;
+  expected: { tokenId: string; marketId: string; policyId: string; accountId: string };
+}, requireUnbound: boolean): { account: Kcc20FeeClaimAccount; redeemScript: Uint8Array;
+      escrowTemplate: { hash: string; prefixLength: number; suffixLength: number } } {
   const artifactHash = Array.from(sha256(new TextEncoder().encode(JSON.stringify(input.artifact))),
     byte => byte.toString(16).padStart(2, "0")).join("");
   if (artifactHash !== ARTIFACT_CANONICAL_SHA256) throw new Error("fee account artifact metadata mismatch");
@@ -207,7 +264,10 @@ export function verifyKcc20FeeAccountForClaim(input: {
   const marketId = hex32(input.expected.marketId, "expected market");
   const policyId = hex32(input.expected.policyId, "expected policy");
   const accountId = hex32(input.expected.accountId, "expected account");
-  if ([tokenId, marketId, policyId, accountId].includes(ZERO)) throw new Error("invalid fee account identity");
+  if (tokenId === ZERO || accountId === ZERO ||
+      (requireUnbound ? (marketId !== ZERO || policyId !== ZERO) : (marketId === ZERO || policyId === ZERO))) {
+    throw new Error("invalid fee account identity");
+  }
   for (const [name, expected] of [["token", tokenId], ["market", marketId], ["policy", policyId]] as const) {
     if (hex32(state[name], name) !== expected) throw new Error(`fee account ${name} mismatch`);
   }
@@ -231,6 +291,9 @@ export function verifyKcc20FeeAccountForClaim(input: {
     throw new Error("invalid fee account guard state");
   }
   hex32(state.action_hash, "action_hash");
+  if (requireUnbound && (scheme !== 0 || state.action_hash !== ZERO)) {
+    throw new Error("unbound fee account must have its initial owner and action state");
+  }
   const selfHash = Array.from(templateHash(prefix, suffix), byte => byte.toString(16).padStart(2, "0")).join("");
   if (hex32(state.self_template, "self_template") !== selfHash ||
       natural(state.self_prefix, "self_prefix") !== BigInt(prefix.length) ||

package/src/index.ts

@@ -23,6 +23,7 @@ export * from "./escrow-policy.js";
 export * from "./escrow-group.js";
 export * from "./escrow-receipt.js";
 export * from "./escrow-claim-plan.js";
+export * from "./escrow-account-setup.js";
 export * from "./trading-operation.js";
 export * from "./protocol.js";
 export * from "./runtime.js";

package/src/operations.ts

@@ -22,6 +22,8 @@ export const KCC20_BUILDER_KEYS = [
   "fee-ticket.create-from-utility-burn",
   "fee-ticket.burn",
   "fee-ticket.transfer",
+  "kcc20fee.create-account",
+  "kcc20fee.bind-account",
   "kcc20-snapshot.deploy-bootstrap",
   "kcc20-snapshot.deploy-controller",
   "kcc20-snapshot.start",