@kronsdk/kron-sdk 0.4.0 → 0.5.0

package/README.md

@@ -4,10 +4,16 @@
 — a bonding-curve launchpad + AMM DEX — from any JS/TS environment.** Browser or Node. No custody, ever:
 this package only *builds* transactions; a wallet (yours, or your user's) signs them.
 
-> **Status: v0.2.1, testnet (TN10).** Read paths and the covenant builders are proven byte-identical to
+> **Status: v0.5.0, testnet (TN10).** Read paths and the covenant builders are proven byte-identical to
 > KRON's own production code (see "Verification" below). Wallet signing is a documented interface plus a
 > generic reference implementation — see [`docs/WALLETS.md`](docs/WALLETS.md) for the contract and how to
 > adapt it to a specific wallet's injected provider.
+>
+> **⚠️ Upgrade from < 0.5.0.** Every earlier release built **version-0** transactions, which cannot carry
+> the covenant bindings Kaspa's covenant layer (KIP-20) requires on output — every assembled spend was
+> rejected on-chain with `script ran, but verification failed`. Fixed in 0.5.0: `assembleNativeTx` now
+> builds v1 transactions with bindings + compute budgets attached. See the [CHANGELOG](CHANGELOG.md) for
+> the migration note if you assembled transactions by hand instead of via `spend.assembleNativeTx`.
 
 ## Why this exists
 
@@ -34,11 +40,12 @@ ESM only (`"type": "module"`) in v1 — see [Design notes](#design-notes) for wh
 
 ```bash
 npm install @kronsdk/kron-sdk@latest      # newest
-npm install @kronsdk/kron-sdk@0.2.0       # or pin an exact version for reproducible builds
+npm install @kronsdk/kron-sdk@0.5.0       # or pin an exact version for reproducible builds
 ```
 
-The package follows semver. The token-list client (`client.RegistryClient.tokenlist()`) and on-chain
-verifier (`verify.verifyTokenListEntry`) landed in **0.2.0** — see [Discover & verify tokens](#discover--verify-tokens-token-list).
+The package follows semver. **0.5.0 is a required upgrade for anyone using `spend.assembleNativeTx`** — see
+the warning above. The token-list client (`client.RegistryClient.tokenlist()`) and on-chain verifier
+(`verify.verifyTokenListEntry`) landed in **0.2.0** — see [Discover & verify tokens](#discover--verify-tokens-token-list).
 
 ## Quickstart — quote a curve buy (Node)
 

package/dist/index.d.ts

@@ -140,6 +140,21 @@ declare namespace genesis {
 
 type K$5 = Kaspa;
 type Spk$4 = any;
+/** Covenant txs are KIP-20 v1 transactions (covenant outputs require tx.version >= 1). */
+declare const TX_VERSION = 1;
+/** Per-input compute budget (v1): a P2PK funding input ≈ one sig op. */
+declare const FUNDING_COMPUTE = 10;
+/** Per-input compute budget (v1): a kcc20 `transfer` input (token balance / inventory / seller piece). */
+declare const TOKEN_COMPUTE = 500;
+/** Per-input compute budget (v1): a curve_cp / amm_pool_cp input (the large redeem scripts). */
+declare const COVENANT_COMPUTE = 2000;
+/** Covenant output min value (KIP-9 storage mass) — the conventional token-UTXO dust, 0.5 KAS. */
+declare const COVENANT_DUST = 50000000n;
+/** A covenant output's KIP-20 lineage: which covenant id it continues and which input authorizes it. */
+type CovBinding = {
+    covid: string;
+    authorizingInput: number;
+};
 /** A covenant UTXO being spent, already carrying its signature script (no wallet signature needed). */
 type CovInput = {
     transactionId: string;
@@ -152,16 +167,19 @@ type CovInput = {
     redeem: Uint8Array;
     /** what this input is, for assembly/debugging: 'curve' | 'minterBranch' | 'burn' | 'pool' | 'poolToken'. */
     role: string;
+    /** v1 compute budget override; defaults by role (curve/pool → COVENANT_COMPUTE, else TOKEN_COMPUTE). */
+    computeBudget?: number;
 };
-/** A covenant-required output (value + scriptPublicKey). */
+/** A covenant-required output (value + scriptPublicKey [+ covenant binding]). */
 type CovOutput = {
     value: bigint;
     scriptPublicKey: Spk$4;
     role: string;
+    binding?: CovBinding;
 };
 /** A complete covenant action: the inputs it spends + the outputs it must create + computed economics. */
 type CovenantSpend = {
-    kind: 'init' | 'initVested' | 'buy' | 'sell' | 'graduate' | 'swapKasForToken' | 'swapTokenForKas' | 'addLiquidity' | 'removeLiquidity' | 'bindLp' | 'claim' | 'claimFinal';
+    kind: 'init' | 'initVested' | 'buy' | 'sell' | 'transfer' | 'graduate' | 'swapKasForToken' | 'swapTokenForKas' | 'addLiquidity' | 'removeLiquidity' | 'bindLp' | 'claim' | 'claimFinal';
     inputs: CovInput[];
     outputs: CovOutput[];
     economics: Record<string, bigint>;
@@ -183,10 +201,12 @@ type AssembledNativeTx = {
     change: bigint;
 };
 /**
- * Assemble a complete tx: the spend's covenant inputs (pre-scripted) + the trader's funding inputs + a
- * change output. `networkFee` is caller-provided (derive from the node; KIP-9 storage mass depends on
- * output values, so the node confirms the exact fee/change at broadcast). Covenant inputs carry sigOpCount
- * 0 (no checkSig on the accept path used here); funding inputs are signed via signFundingInputs.
+ * Assemble a complete v1 covenant tx: the spend's covenant inputs (pre-scripted) + the trader's funding
+ * inputs + a change output. Covenant outputs whose `binding` is set carry the KIP-20 `CovenantBinding`
+ * (REQUIRED for any output the covenant validates — see the module header). `networkFee` is
+ * caller-provided; size it with `estimateNativeFee` (v1 fees must cover the per-input compute budget, so a
+ * flat legacy fee is usually too low). Covenant inputs default to a role-based compute budget; funding
+ * inputs are signed via signFundingInputs (or the signPskt bridge).
  */
 declare function assembleNativeTx(k: K$5, opts: {
     spend: CovenantSpend;
@@ -194,6 +214,14 @@ declare function assembleNativeTx(k: K$5, opts: {
     changeAddress: string;
     networkFee: bigint;
 }): AssembledNativeTx;
+/**
+ * Size `networkFee` for an assembled v1 tx: byte/storage mass (via the WASM mass calculator, with
+ * placeholder signatures on the funding inputs so byte mass is realistic) + the per-input compute budget
+ * the calculator omits (grams = budget × 100), at `feeRateSompiPerGram` (use the node's feerate estimate;
+ * min-relay on TN10 has been ~100 sompi/gram), with a 1.5× over-cover and a 10_000-sompi floor. Assemble
+ * with a guess (e.g. 10_000n), call this, then re-assemble with the returned fee.
+ */
+declare function estimateNativeFee(k: K$5, networkId: string, asm: AssembledNativeTx, feeRateSompiPerGram: number): bigint;
 /** Sign the trader's funding inputs (P2PK) in place; covenant inputs are left untouched (pre-scripted). */
 declare function signFundingInputs(k: K$5, tx: any, privKey: any, fundingInputIndexes: number[]): any;
 /**
@@ -221,16 +249,23 @@ declare function signPsktWithKey(k: K$5, txJsonString: string, signInputs: {
 }[], privKey: any): string;
 
 type spend_AssembledNativeTx = AssembledNativeTx;
+declare const spend_COVENANT_COMPUTE: typeof COVENANT_COMPUTE;
+declare const spend_COVENANT_DUST: typeof COVENANT_DUST;
+type spend_CovBinding = CovBinding;
 type spend_CovInput = CovInput;
 type spend_CovOutput = CovOutput;
 type spend_CovenantSpend = CovenantSpend;
+declare const spend_FUNDING_COMPUTE: typeof FUNDING_COMPUTE;
 type spend_FundingEntry = FundingEntry;
+declare const spend_TOKEN_COMPUTE: typeof TOKEN_COMPUTE;
+declare const spend_TX_VERSION: typeof TX_VERSION;
 declare const spend_assembleNativeTx: typeof assembleNativeTx;
+declare const spend_estimateNativeFee: typeof estimateNativeFee;
 declare const spend_signFundingInputs: typeof signFundingInputs;
 declare const spend_signPsktWithKey: typeof signPsktWithKey;
 declare const spend_toPsktJson: typeof toPsktJson;
 declare namespace spend {
-  export { type spend_AssembledNativeTx as AssembledNativeTx, type spend_CovInput as CovInput, type spend_CovOutput as CovOutput, type spend_CovenantSpend as CovenantSpend, type spend_FundingEntry as FundingEntry, spend_assembleNativeTx as assembleNativeTx, spend_signFundingInputs as signFundingInputs, spend_signPsktWithKey as signPsktWithKey, spend_toPsktJson as toPsktJson };
+  export { type spend_AssembledNativeTx as AssembledNativeTx, spend_COVENANT_COMPUTE as COVENANT_COMPUTE, spend_COVENANT_DUST as COVENANT_DUST, type spend_CovBinding as CovBinding, type spend_CovInput as CovInput, type spend_CovOutput as CovOutput, type spend_CovenantSpend as CovenantSpend, spend_FUNDING_COMPUTE as FUNDING_COMPUTE, type spend_FundingEntry as FundingEntry, spend_TOKEN_COMPUTE as TOKEN_COMPUTE, spend_TX_VERSION as TX_VERSION, spend_assembleNativeTx as assembleNativeTx, spend_estimateNativeFee as estimateNativeFee, spend_signFundingInputs as signFundingInputs, spend_signPsktWithKey as signPsktWithKey, spend_toPsktJson as toPsktJson };
 }
 
 type K$4 = Kaspa;
@@ -259,6 +294,23 @@ type Kcc20Template = {
 };
 /** Produce the kcc20 redeem script for `state` by splicing the 46-byte region. Byte-identical to silverc. */
 declare function materializeKcc20Script(tpl: Kcc20Template, state: Kcc20State): Uint8Array;
+/**
+ * Recover the `{ script, stateStart }` template AND the current balance state from a live token UTXO's
+ * redeem script (your indexer's `redeemScriptHex`). Scans for the 46-byte state region's push layout
+ * (`0x20 <owner:32> 0x01 <type:1> 0x08 <amount:8> 0x01 <isMinter:1>` with type ≤ 0x03, isMinter ≤ 1) and
+ * requires it to match at exactly ONE offset. This is the supported way to build the template for
+ * `materializeKcc20Script` — splice the SAME script the chain holds; never re-compile.
+ * `maxIns`/`maxOuts` are compiled constants not recoverable from the bytes — pass the token's deploy
+ * params if you know them (KRON deploys use 4/4, the default) — they are informational only (the splice
+ * uses just `script` + `stateStart`).
+ */
+declare function decodeKcc20Redeem(redeem: Uint8Array, opts?: {
+    maxIns?: number;
+    maxOuts?: number;
+}): {
+    template: Kcc20Template;
+    state: Kcc20State;
+};
 /** Token P2SH scriptPublicKey for a redeem script. */
 declare const kcc20Spk: (k: K$4, redeem: Uint8Array) => Spk$3;
 /** Token P2SH scriptPublicKey for a balance state (materialize → P2SH). */
@@ -288,13 +340,33 @@ declare function pushKcc20States(b: SigScriptBuilder, states: Kcc20State[]): voi
  * carrying that covenant id). `sigs` are 65-byte Schnorr sigs (empty for covenant-id-only ownership).
  */
 declare function transferSigScript(k: K$4, redeem: Uint8Array, newStates: Kcc20State[], witnesses: number[], sigs?: Uint8Array[]): string;
+/**
+ * Send `sendAmount` from one or more presence-owned token UTXOs (same owner) to `recipientPubkey32`, with
+ * the remainder returned to the sender — the wallet "Send" button. A plain conserving `transfer`: inputs
+ * are authorized by ONE co-present P2PK input at tx index `presenceWitnessIdx` (assemble the covenant
+ * inputs first, then the sender's funding inputs: with N token inputs, `presenceWitnessIdx = N`).
+ *
+ * `tokenCovid` (the token's covenant id, hex — `covenantId` from the indexer's token info) is REQUIRED:
+ * every covenant output must carry the KIP-20 `CovenantBinding` or the chain rejects the spend with
+ * "script ran, but verification failed". Outputs: [recipient, change] (change omitted when exact).
+ */
+declare function buildKcc20Send(k: K$4, tpl: Kcc20Template, senderTokens: {
+    transactionId: string;
+    index: number;
+    value: bigint;
+    state: Kcc20State;
+}[], recipientPubkey32: Uint8Array, sendAmount: bigint, presenceWitnessIdx: number, tokenCovid: string, opts?: {
+    tokenDust?: bigint;
+}): CovenantSpend;
 
 declare const kcc20Tx_IDENTIFIER: typeof IDENTIFIER;
 type kcc20Tx_IdentifierType = IdentifierType;
 type kcc20Tx_Kcc20State = Kcc20State;
 type kcc20Tx_Kcc20Template = Kcc20Template;
 declare const kcc20Tx_addressPresenceOwned: typeof addressPresenceOwned;
+declare const kcc20Tx_buildKcc20Send: typeof buildKcc20Send;
 declare const kcc20Tx_covenantIdOwned: typeof covenantIdOwned;
+declare const kcc20Tx_decodeKcc20Redeem: typeof decodeKcc20Redeem;
 declare const kcc20Tx_kcc20Address: typeof kcc20Address;
 declare const kcc20Tx_kcc20Spk: typeof kcc20Spk;
 declare const kcc20Tx_kcc20SpkForState: typeof kcc20SpkForState;
@@ -305,7 +377,7 @@ declare const kcc20Tx_pushKcc20States: typeof pushKcc20States;
 declare const kcc20Tx_scriptHashOwned: typeof scriptHashOwned;
 declare const kcc20Tx_transferSigScript: typeof transferSigScript;
 declare namespace kcc20Tx {
-  export { kcc20Tx_IDENTIFIER as IDENTIFIER, type kcc20Tx_IdentifierType as IdentifierType, type kcc20Tx_Kcc20State as Kcc20State, type kcc20Tx_Kcc20Template as Kcc20Template, kcc20Tx_addressPresenceOwned as addressPresenceOwned, kcc20Tx_covenantIdOwned as covenantIdOwned, kcc20Tx_kcc20Address as kcc20Address, kcc20Tx_kcc20Spk as kcc20Spk, kcc20Tx_kcc20SpkForState as kcc20SpkForState, kcc20Tx_materializeKcc20Script as materializeKcc20Script, kcc20Tx_pubkeyOwned as pubkeyOwned, kcc20Tx_pushKcc20StateScalar as pushKcc20StateScalar, kcc20Tx_pushKcc20States as pushKcc20States, kcc20Tx_scriptHashOwned as scriptHashOwned, kcc20Tx_transferSigScript as transferSigScript };
+  export { kcc20Tx_IDENTIFIER as IDENTIFIER, type kcc20Tx_IdentifierType as IdentifierType, type kcc20Tx_Kcc20State as Kcc20State, type kcc20Tx_Kcc20Template as Kcc20Template, kcc20Tx_addressPresenceOwned as addressPresenceOwned, kcc20Tx_buildKcc20Send as buildKcc20Send, kcc20Tx_covenantIdOwned as covenantIdOwned, kcc20Tx_decodeKcc20Redeem as decodeKcc20Redeem, kcc20Tx_kcc20Address as kcc20Address, kcc20Tx_kcc20Spk as kcc20Spk, kcc20Tx_kcc20SpkForState as kcc20SpkForState, kcc20Tx_materializeKcc20Script as materializeKcc20Script, kcc20Tx_pubkeyOwned as pubkeyOwned, kcc20Tx_pushKcc20StateScalar as pushKcc20StateScalar, kcc20Tx_pushKcc20States as pushKcc20States, kcc20Tx_scriptHashOwned as scriptHashOwned, kcc20Tx_transferSigScript as transferSigScript };
 }
 
 type K$3 = Kaspa;
@@ -598,6 +670,8 @@ declare function buildCpGraduate(k: K$2, tpl: CpTemplate, tokenTpl: Kcc20Templat
  * a plain conserving kcc20 transfer authorized by a co-present P2PK input at `presenceWitnessIdx`. Lets a
  * holder sell an ARBITRARY amount on covenants that require full-UTXO sells (curve/pool): split, then sell the
  * `sellAmount` piece. No curve/pool involved — just the token covenant.
+ * Pass `opts.tokenCovid` (the token's covenant id, hex — `covenantId` from the indexer) so both outputs carry
+ * the KIP-20 covenant binding the chain requires; without it the assembled tx fails on-chain.
  */
 declare function buildSplitToken(k: K$2, tokenTpl: Kcc20Template, sellerToken: {
     transactionId: string;
@@ -606,11 +680,14 @@ declare function buildSplitToken(k: K$2, tokenTpl: Kcc20Template, sellerToken: {
     state: Kcc20State;
 }, sellAmount: bigint, presenceWitnessIdx: number, opts?: {
     tokenDust?: bigint;
+    tokenCovid?: string;
 }): CovenantSpend;
 /**
  * Consolidate several presence-owned token UTXOs (same owner) into ONE — a conserving kcc20 transfer (N covid-A
  * inputs → 1 output) authorized by a single co-present P2PK input at `presenceWitnessIdx`. Lets a holder merge
  * many small buys into one piece so a later sell needs just one (or two) inputs. No curve/pool involved.
+ * Pass `opts.tokenCovid` (the token's covenant id, hex) so the merged output carries the KIP-20 covenant
+ * binding the chain requires; without it the assembled tx fails on-chain.
  */
 declare function buildConsolidate(k: K$2, tokenTpl: Kcc20Template, tokens: {
     transactionId: string;
@@ -619,6 +696,7 @@ declare function buildConsolidate(k: K$2, tokenTpl: Kcc20Template, tokens: {
     state: Kcc20State;
 }[], presenceWitnessIdx: number, opts?: {
     tokenDust?: bigint;
+    tokenCovid?: string;
 }): CovenantSpend;
 
 type curveCpTx_CpCurveState = CpCurveState;

package/dist/index.js

@@ -163,12 +163,24 @@ var ZERO_COVID = "00".repeat(32);
 // src/native/spend.ts
 var spend_exports = {};
 __export(spend_exports, {
+  COVENANT_COMPUTE: () => COVENANT_COMPUTE,
+  COVENANT_DUST: () => COVENANT_DUST,
+  FUNDING_COMPUTE: () => FUNDING_COMPUTE,
+  TOKEN_COMPUTE: () => TOKEN_COMPUTE,
+  TX_VERSION: () => TX_VERSION,
   assembleNativeTx: () => assembleNativeTx,
+  estimateNativeFee: () => estimateNativeFee,
   signFundingInputs: () => signFundingInputs,
   signPsktWithKey: () => signPsktWithKey,
   toPsktJson: () => toPsktJson
 });
+var TX_VERSION = 1;
+var FUNDING_COMPUTE = 10;
+var TOKEN_COMPUTE = 500;
+var COVENANT_COMPUTE = 2e3;
+var COVENANT_DUST = 50000000n;
 var SUBNET_ZERO = "0000000000000000000000000000000000000000";
+var budgetForRole = (role) => role === "curve" || role === "pool" ? COVENANT_COMPUTE : TOKEN_COMPUTE;
 function assembleNativeTx(k, opts) {
   const { spend, fundingEntries, changeAddress, networkFee } = opts;
   const kk = k;
@@ -178,6 +190,7 @@ function assembleNativeTx(k, opts) {
       signatureScript: ci.signatureScript,
       sequence: 0n,
       sigOpCount: 0,
+      computeBudget: ci.computeBudget ?? budgetForRole(ci.role),
       utxo: {
         outpoint: { transactionId: ci.transactionId, index: ci.index },
         amount: ci.value,
@@ -188,7 +201,7 @@ function assembleNativeTx(k, opts) {
     })
   );
   const fundingInputs = fundingEntries.map(
-    (e) => new kk.TransactionInput({ previousOutpoint: e.outpoint, signatureScript: "", sequence: 0n, sigOpCount: 1, utxo: e })
+    (e) => new kk.TransactionInput({ previousOutpoint: e.outpoint, signatureScript: "", sequence: 0n, sigOpCount: 0, computeBudget: FUNDING_COMPUTE, utxo: e })
   );
   const covInValue = spend.inputs.reduce((s, ci) => s + ci.value, 0n);
   const fundingTotal = fundingEntries.reduce((s, e) => s + BigInt(e.amount), 0n);
@@ -196,10 +209,12 @@ function assembleNativeTx(k, opts) {
   const covenantOut = spend.outputs.reduce((s, o) => s + o.value, 0n);
   const change = totalIn - covenantOut - networkFee;
   if (change < 0n) throw new Error(`insufficient funding: need ${covenantOut + networkFee} sompi, have ${totalIn}`);
-  const outputs = spend.outputs.map((o) => new kk.TransactionOutput(o.value, o.scriptPublicKey));
+  const outputs = spend.outputs.map(
+    (o) => o.binding ? new kk.TransactionOutput(o.value, o.scriptPublicKey, new kk.CovenantBinding(o.binding.authorizingInput, new kk.Hash(o.binding.covid))) : new kk.TransactionOutput(o.value, o.scriptPublicKey)
+  );
   outputs.push(new kk.TransactionOutput(change, kk.payToAddressScript(changeAddress)));
   const transaction = new kk.Transaction({
-    version: 0,
+    version: TX_VERSION,
     inputs: [...covInputs, ...fundingInputs],
     outputs,
     lockTime: 0n,
@@ -215,6 +230,27 @@ function assembleNativeTx(k, opts) {
     change
   };
 }
+function estimateNativeFee(k, networkId, asm, feeRateSompiPerGram) {
+  const kk = k;
+  const tx = asm.transaction;
+  const ins = tx.inputs;
+  const saved = asm.fundingInputIndexes.map((i) => ins[i].signatureScript);
+  for (const i of asm.fundingInputIndexes) ins[i].signatureScript = "00".repeat(66);
+  tx.inputs = ins;
+  let byteMass = 2000n;
+  try {
+    byteMass = BigInt(kk.calculateTransactionMass(networkId, tx));
+  } catch {
+  }
+  const ins2 = tx.inputs;
+  asm.fundingInputIndexes.forEach((i, j) => ins2[i].signatureScript = saved[j]);
+  tx.inputs = ins2;
+  let computeGrams = 0n;
+  for (const inp of tx.inputs) computeGrams += BigInt(inp.computeBudget || 0) * 100n;
+  const rate = BigInt(Math.max(Math.ceil(feeRateSompiPerGram), 1));
+  const fee = (byteMass + computeGrams) * rate * 3n / 2n;
+  return fee > 10000n ? fee : 10000n;
+}
 function signFundingInputs(k, tx, privKey, fundingInputIndexes) {
   const inputs = tx.inputs;
   for (const idx of fundingInputIndexes) {
@@ -247,7 +283,9 @@ var kcc20Tx_exports = {};
 __export(kcc20Tx_exports, {
   IDENTIFIER: () => IDENTIFIER,
   addressPresenceOwned: () => addressPresenceOwned,
+  buildKcc20Send: () => buildKcc20Send,
   covenantIdOwned: () => covenantIdOwned,
+  decodeKcc20Redeem: () => decodeKcc20Redeem,
   kcc20Address: () => kcc20Address,
   kcc20Spk: () => kcc20Spk,
   kcc20SpkForState: () => kcc20SpkForState,
@@ -259,6 +297,7 @@ __export(kcc20Tx_exports, {
   transferSigScript: () => transferSigScript
 });
 var IDENTIFIER = { PUBKEY: 0, SCRIPT_HASH: 1, COVENANT_ID: 2, ADDRESS: 3 };
+var STATE_LEN = 46;
 function materializeKcc20Script(tpl, state) {
   const s = tpl.stateStart;
   const t = tpl.script;
@@ -278,6 +317,25 @@ function materializeKcc20Script(tpl, state) {
   out[s + 45] = state.isMinter ? 1 : 0;
   return out;
 }
+function decodeKcc20Redeem(redeem, opts = {}) {
+  const hits = [];
+  for (let s2 = 0; s2 + STATE_LEN <= redeem.length; s2++) {
+    if (redeem[s2] === 32 && redeem[s2 + 33] === 1 && redeem[s2 + 34] <= 3 && redeem[s2 + 35] === 8 && redeem[s2 + 44] === 1 && redeem[s2 + 45] <= 1) hits.push(s2);
+  }
+  if (hits.length !== 1) throw new Error(`could not locate the kcc20 state region in the redeem script (${hits.length} candidate offsets) \u2014 is this a kcc20 token UTXO?`);
+  const s = hits[0];
+  let amount = 0n;
+  for (let i = 7; i >= 0; i--) amount = amount << 8n | BigInt(redeem[s + 36 + i]);
+  return {
+    template: { script: redeem.slice(), stateStart: s, maxIns: opts.maxIns ?? 4, maxOuts: opts.maxOuts ?? 4 },
+    state: {
+      ownerIdentifier: redeem.slice(s + 1, s + 33),
+      identifierType: redeem[s + 34],
+      amount,
+      isMinter: redeem[s + 45] === 1
+    }
+  };
+}
 var kcc20Spk = (k, redeem) => k.payToScriptHashScript(redeem);
 var kcc20SpkForState = (k, tpl, state) => kcc20Spk(k, materializeKcc20Script(tpl, state));
 function kcc20Address(k, tpl, state, network) {
@@ -327,6 +385,30 @@ function transferSigScript(k, redeem, newStates, witnesses, sigs = []) {
   b.redeem(redeem);
   return b.drain();
 }
+function buildKcc20Send(k, tpl, senderTokens, recipientPubkey32, sendAmount, presenceWitnessIdx, tokenCovid, opts = {}) {
+  if (senderTokens.length < 1) throw new Error("send requires at least one token UTXO");
+  if (!tokenCovid) throw new Error("send requires the token covenant id (indexer token info `covenantId`) for the output bindings");
+  const total = senderTokens.reduce((s, t) => s + t.state.amount, 0n);
+  const change = total - sendAmount;
+  if (sendAmount < 1n || change < 0n) throw new Error(`send requires 1 <= sendAmount <= ${total} (the selected UTXOs' total)`);
+  const dust = opts.tokenDust ?? 50000000n;
+  const owner = senderTokens[0].state.ownerIdentifier;
+  const recipientOut = addressPresenceOwned(recipientPubkey32, sendAmount);
+  const newStates = change >= 1n ? [recipientOut, addressPresenceOwned(owner, change)] : [recipientOut];
+  const witnesses = senderTokens.map(() => presenceWitnessIdx);
+  const inputs = senderTokens.map((t) => {
+    const r = materializeKcc20Script(tpl, t.state);
+    return { transactionId: t.transactionId, index: t.index, value: t.value, scriptPublicKey: kcc20Spk(k, r), signatureScript: transferSigScript(k, r, newStates, witnesses), redeem: r, role: "token" };
+  });
+  const binding = { covid: tokenCovid, authorizingInput: 0 };
+  const outputs = newStates.map((st, i) => ({
+    value: dust,
+    scriptPublicKey: kcc20Spk(k, materializeKcc20Script(tpl, st)),
+    role: i === 0 ? "send" : "change",
+    binding
+  }));
+  return { kind: "transfer", inputs, outputs, economics: { sendAmount, change }, covids: { tokenCovid } };
+}
 
 // src/native/curveCpTx.ts
 var curveCpTx_exports = {};
@@ -756,14 +838,15 @@ function buildSplitToken(k, tokenTpl, sellerToken, sellAmount, presenceWitnessId
   const out1 = addressPresenceOwned(owner, sellAmount);
   const out2 = addressPresenceOwned(owner, change);
   const redeem = materializeKcc20Script(tokenTpl, sellerToken.state);
+  const binding = opts.tokenCovid ? { covid: opts.tokenCovid, authorizingInput: 0 } : void 0;
   const inputs = [
     { transactionId: sellerToken.transactionId, index: sellerToken.index, value: sellerToken.value, scriptPublicKey: kcc20Spk(k, redeem), signatureScript: transferSigScript(k, redeem, [out1, out2], [presenceWitnessIdx]), redeem, role: "sellerToken" }
   ];
   const outputs = [
-    { value: dust, scriptPublicKey: kcc20Spk(k, materializeKcc20Script(tokenTpl, out1)), role: "split" },
-    { value: dust, scriptPublicKey: kcc20Spk(k, materializeKcc20Script(tokenTpl, out2)), role: "change" }
+    { value: dust, scriptPublicKey: kcc20Spk(k, materializeKcc20Script(tokenTpl, out1)), role: "split", binding },
+    { value: dust, scriptPublicKey: kcc20Spk(k, materializeKcc20Script(tokenTpl, out2)), role: "change", binding }
   ];
-  return { kind: "sell", inputs, outputs, economics: { sellAmount, change }, covids: { tokenCovid: hexOf2(owner) } };
+  return { kind: "sell", inputs, outputs, economics: { sellAmount, change }, covids: opts.tokenCovid ? { tokenCovid: opts.tokenCovid } : {} };
 }
 function buildConsolidate(k, tokenTpl, tokens, presenceWitnessIdx, opts = {}) {
   if (tokens.length < 2) throw new Error("consolidate needs at least 2 UTXOs");
@@ -777,10 +860,11 @@ function buildConsolidate(k, tokenTpl, tokens, presenceWitnessIdx, opts = {}) {
     const r = materializeKcc20Script(tokenTpl, t.state);
     return { transactionId: t.transactionId, index: t.index, value: t.value, scriptPublicKey: kcc20Spk(k, r), signatureScript: transferSigScript(k, r, newStates, witnesses), redeem: r, role: "token" };
   });
+  const binding = opts.tokenCovid ? { covid: opts.tokenCovid, authorizingInput: 0 } : void 0;
   const outputs = [
-    { value: dust, scriptPublicKey: kcc20Spk(k, materializeKcc20Script(tokenTpl, merged)), role: "merged" }
+    { value: dust, scriptPublicKey: kcc20Spk(k, materializeKcc20Script(tokenTpl, merged)), role: "merged", binding }
   ];
-  return { kind: "sell", inputs, outputs, economics: { total }, covids: { tokenCovid: hexOf2(owner) } };
+  return { kind: "sell", inputs, outputs, economics: { total }, covids: opts.tokenCovid ? { tokenCovid: opts.tokenCovid } : {} };
 }
 var hexOf2 = (u8) => Array.from(u8, (b) => b.toString(16).padStart(2, "0")).join("");