@kronsdk/kron-sdk 0.4.0 → 0.6.0

package/README.md

@@ -4,10 +4,18 @@
 — 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.6.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.6.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`. 0.5.0 fixed `assembleNativeTx` (v1 txs +
+> compute budgets) and the kcc20 builders; 0.6.0 finishes the job for the curve, pool/LP, and vesting
+> builders (buy/sell/graduate, swap, add/removeLiquidity, bindLp, claim) — they now attach the required
+> `CovOutput.binding` automatically. See the [CHANGELOG](CHANGELOG.md) for the migration notes if you
+> assembled transactions by hand instead of via `spend.assembleNativeTx`.
 
 ## Why this exists
 
@@ -34,11 +42,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.6.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.6.0 is a required upgrade for anyone building curve/pool/LP/vesting
+transactions** — 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;
@@ -736,14 +814,23 @@ type VestUtxo = {
  * Partial claim: release `release` (0 < release < remaining) to the creator's presence, re-lock the rest under
  * V. inputs [vesting(0), lockedToken(1)]; outputs [vesting cont(0), relock(1, A/V-owned), recipient(2, A/creator)].
  * The flow must set tx.lockTime = current DAA score (consensus blocks the tx until then; the covenant reads it).
+ *
+ * Pass `opts.tokenCovid` (the vested token's covenant id, hex — `covenantId` from the indexer) so the relock +
+ * recipient outputs carry the KIP-20 covenant binding the chain requires; without it the assembled tx fails
+ * on-chain. The vesting-continuation output is always bound to `vestingCovid` (already a required param).
  */
 declare function buildVestingClaim(k: K, vestTpl: VestingTemplate, tokenTpl: Kcc20Template, vestingUtxo: VestUtxo, lockedToken: VestUtxo, vestingCovid: Uint8Array, creatorPubkey: Uint8Array, claimed: bigint, release: bigint, opts?: {
     tokenDust?: bigint;
+    tokenCovid?: string;
 }): CovenantSpend;
 /** Final claim: once fully vested, pay ALL remaining to the creator and continue V with claimed=total (husk).
- *  inputs [vesting(0), lockedToken(1)]; outputs [vesting cont(0), recipient(1, A/creator)]. */
+ *  inputs [vesting(0), lockedToken(1)]; outputs [vesting cont(0), recipient(1, A/creator)].
+ *
+ *  Pass `opts.tokenCovid` (the vested token's covenant id, hex) so the recipient output carries the KIP-20
+ *  covenant binding the chain requires; without it the assembled tx fails on-chain. */
 declare function buildVestingClaimFinal(k: K, vestTpl: VestingTemplate, tokenTpl: Kcc20Template, vestingUtxo: VestUtxo, lockedToken: VestUtxo, vestingCovid: Uint8Array, creatorPubkey: Uint8Array, claimed: bigint, opts?: {
     tokenDust?: bigint;
+    tokenCovid?: string;
 }): CovenantSpend;
 
 declare const vestingTx_VEST_SELECTOR: typeof VEST_SELECTOR;