@kaspacom/kcc20-tx-builder 0.8.0-fee.1 → 0.8.0-fee.3

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.8.0-fee.3
+
+- Build wallet-signable fee-account genesis and one-time market binding PSKTs from the pinned escrow artifact.
+- Keep the account's full KAS principal and lineage during binding; check current node UTXOs, signed fees and mass.
+- Return a creation hint for the first bind, since the account state is not visible from an unspent P2SH genesis output.
+- Keep fee-market trading, claims, rotation and new-market creation disabled in this prerelease.
+
+## 0.8.0-fee.2
+
+- Verify fee receipts and fee accounts against the pinned escrow artifact and fresh node UTXOs before claim construction.
+- Plan independent protocol or creator claims while preserving the other share and matching the signed consensus commitment.
+- Keep signing, complete transaction mass checks, and market creation disabled in this prerelease.
+
 ## 0.8.0-fee.1
 
 - Package the pinned fee v1 contract artifacts and fixed policy manifest for integration work.

package/RELEASING.md

@@ -15,7 +15,8 @@ Prerelease versions use the `next` tag in both registries; stable versions use
 ## Publishing setup
 
 After a successful `main` CI run, `.github/workflows/publish.yml` compares the
-package version with the first parent of the merged commit. A changed version
+package version with the first parent of the merged commit and checks whether
+the current version is visible on npmjs. A changed or unpublished version
 triggers one job that packs the package once, publishes that tarball to npmjs
 and GitHub Packages, verifies both registries, then creates the matching tag
 and GitHub Release. A manual workflow dispatch retries a partial upload only
@@ -94,9 +95,9 @@ consumer deployment. Record any unverified operation families explicitly.
 
 ## Fee integration prerelease
 
-Version `0.8.0-fee.1` adds pinned fee artifacts to the 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.
+Version `0.8.0-fee.3` adds fee-account creation and binding PSKTs for DEV
+integration. Run the existing snapshot and example tests against the pinned
+WASM before publishing it under `next`. This prerelease does not build
+fee-market trades, claims or authority rotation. Funded fee-market journeys and
+signed settlement construction remain required before enabling markets or
+promoting a stable fee release.

package/dist/cjs/engine.js

@@ -10,6 +10,7 @@ const token_profiles_generated_js_1 = require("./token-profiles.generated.js");
 const sale_common_js_1 = require("./sale-common.js");
 const abi_js_1 = require("./abi.js");
 const operations_js_1 = require("./operations.js");
+const escrow_account_setup_js_1 = require("./escrow-account-setup.js");
 const snapshot_operation_js_1 = require("./snapshot-operation.js");
 const protocol_js_1 = require("./protocol.js");
 const deploy_receipt_js_1 = require("./deploy-receipt.js");
@@ -335,6 +336,8 @@ function createKcc20PsktBuilderEngine(options) {
         "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,
@@ -372,6 +375,255 @@ function createKcc20PsktBuilderEngine(options) {
         }
         return builder(input);
     }
+    async function buildFeeAccountCreatePskt(input) {
+        const request = input.request || {};
+        const params = request.params || {};
+        const tokenId = (0, sale_common_js_1.requireHex32)(params.tokenId, "fee account token id");
+        const owner = (0, sale_common_js_1.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);
+        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 = (0, escrow_account_setup_js_1.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 = (0, sale_common_js_1.selectFundingEntry)(walletUtxos.entries, principalSompi + priorityFee + 10000n, [], params.fundingOutpoint);
+            const fundingAmount = (0, sale_common_js_1.utxoAmountSompi)(fundingEntry);
+            const change = fundingAmount - principalSompi - priorityFee;
+            if (change <= 10000n)
+                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: sale_common_js_1.SUBNETWORK_ID_NATIVE,
+                gas: 0n,
+                payload: "",
+            });
+            (0, sale_common_js_1.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((0, sale_common_js_1.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 (0, sale_common_js_1.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 = (0, sale_common_js_1.requireHex32)(params.tokenId, "fee account token id");
+        const accountId = (0, sale_common_js_1.requireHex32)(params.accountId, "fee account id");
+        const marketId = (0, sale_common_js_1.requireHex32)(params.marketId, "fee account market id");
+        const policyId = (0, sale_common_js_1.requireHex32)(params.policyId, "fee account policy id");
+        const owner = (0, sale_common_js_1.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);
+        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 = (0, sale_common_js_1.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 : (0, sale_common_js_1.bytesToHex)(scriptBytes);
+            const plan = (0, escrow_account_setup_js_1.planKcc20FeeAccountBinding)({
+                artifact,
+                indexed,
+                live: {
+                    outpoint: { transactionId: txid, index: vout },
+                    amountSompi: (0, sale_common_js_1.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 = (0, sale_common_js_1.selectFundingEntry)(walletUtxos.entries, priorityFee + 10000n, [], params.fundingOutpoint);
+            const fundingAmount = (0, sale_common_js_1.utxoAmountSompi)(fundingEntry);
+            if (fundingAmount <= priorityFee + 10000n)
+                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: sale_common_js_1.SUBNETWORK_ID_NATIVE,
+                gas: 0n,
+                payload: "",
+            });
+            (0, sale_common_js_1.setVersionOneInputMassFields)(unsignedTx, computeBudget);
+            unsignedTx.inputs[1].computeBudget = 30;
+            const scripts = [{
+                    inputIndex: 0,
+                    scriptHex: (0, sale_common_js_1.bytesToHex)(plan.currentRedeemScript),
+                    signType: 1,
+                    signatureScript: {
+                        mode: "ordered-args",
+                        args: [
+                            dataTemplateArg((0, sale_common_js_1.hexToBytes)(marketId)),
+                            dataTemplateArg((0, sale_common_js_1.hexToBytes)(policyId)),
+                            { type: "signature" },
+                            i64TemplateArg(0),
+                            dataTemplateArg((0, abi_js_1.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((0, sale_common_js_1.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 (0, sale_common_js_1.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 || {};