@kronsdk/kron-sdk 0.1.1

package/LICENSE

@@ -0,0 +1,32 @@
+MIT License
+
+Copyright (c) 2026 Shawn Pearce
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+NOTICE: The TypeScript transaction-builder code under src/native/*.ts and
+src/curve/*.ts was originally developed as part of the KRON project
+(https://kron.technology) and was relicensed under this MIT license for
+publication in this SDK by its copyright holder, Shawn Pearce, on
+2026-06-30. It remains proprietary in KRON's private application repository;
+this relicensing applies only to the copies published in this repository.
+This package does not include KRON's covenant source (.sil) files or
+compiler, which remain private.

package/README.md

@@ -0,0 +1,127 @@
+# kron-sdk
+
+**Build, sign, and submit transactions against [KRON](https://kron.technology)'s native-L1 Kaspa covenants
+— 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.1.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.
+
+## Why this exists
+
+KRON is **covenant-native** — there's no rollup, no off-chain ledger of record, no custodial API. Every
+balance is an on-chain UTXO whose script enforces its own rules; every state-changing action is a
+transaction **the user's own wallet signs**. That's great for trust, but it means "integrate with KRON"
+has historically meant embedding KRON's browser bundle. This package extracts the transaction builders for
+**trading against already-deployed KRON tokens** into a standalone, dependency-light package, so a wallet,
+a Telegram bot, or a backend can build those transactions directly — buy, sell, swap, transfer, add/remove
+liquidity, claim vesting.
+
+This package does **not** include a covenant compiler and doesn't build the deploy/genesis transactions
+that launch a *new* curve, pool, or token — see "What's in the box" below.
+
+## Install
+
+```bash
+npm install @kronsdk/kron-sdk
+```
+
+ESM only (`"type": "module"`) in v1 — see [Design notes](#design-notes) for why.
+
+## Quickstart — quote a curve buy (Node)
+
+```ts
+import * as kron from '@kronsdk/kron-sdk';
+import { loadKaspa } from '@kronsdk/kron-sdk/wasm';
+
+const k = await loadKaspa();
+const idx = new kron.client.IndexerClient('https://idx.kron.technology/v1/kcc20');
+
+// 1. Read live curve state
+const token = await idx.token('ghost');
+const cpState = {
+  realKas: BigInt(token.cpState.realKas), tokenReserve: BigInt(token.cpState.tokenReserve),
+  vKas: BigInt(token.cp?.curveParams?.vKas ?? 0), graduationKas: BigInt(token.cp?.curveParams?.graduationKas ?? 0),
+  creatorFeeBps: 25n, platformFeeBps: 100n,
+};
+
+// 2. Quote a buy
+const quote = kron.curve.quoteCpBuy(cpState, 10_000_000_000n); // 100 TKAS in
+if (!quote) throw new Error('quote failed — bad amount or curve state');
+console.log(`100 TKAS -> ${quote.tokenOut} tokens, fee ${quote.fee} sompi`);
+
+// 3. Build the covenant spend against the LIVE curve. `cpTemplate`/`tokenTemplate` need the target's
+//    already-compiled script bytes + state offset — read them from your indexer's UTXO data
+//    (redeemScriptHex etc.), this package doesn't compile them. curveUtxo/inventoryUtxo also come from
+//    the indexer. See docs/INTEGRATION.md for the full flow.
+// const spend = kron.curveCp.buildCpBuy(k, cpTemplate, tokenTemplate, curveUtxo, inventoryUtxo, ...);
+// const asm = kron.spend.assembleNativeTx(k, { spend, fundingEntries, changeAddress, networkFee });
+// const pskt = kron.spend.toPsktJson(asm);
+// const signed = await wallet.signPskt(pskt.txJsonString, pskt.signInputs); // user's wallet signs
+```
+
+See [`docs/INTEGRATION.md`](docs/INTEGRATION.md) for the full read/write API + worked recipes (wallet
+portfolio render, "Send" button, TG bot price command, pool swap).
+
+## What's in the box
+
+```
+kron-sdk
+├─ curve            constant-product curve math (BigInt, mirrors curve_cp.sil exactly)
+├─ curveCp           curve_cp builders against an EXISTING curve: buy / sell / graduate
+├─ poolCp / poolCpV3 amm_pool_cp_v3 builders: swap / addLiquidity / removeLiquidity / bindLp
+├─ kcc20              the KCC-20 token covenant: transfer / ownership modes / state encoding
+├─ vesting            claim / claimFinal against an EXISTING vesting lock
+├─ spend              tx assembly + the signPskt-style wallet-signing bridge
+├─ wallet             WalletAdapter interface + a generic reference implementation (see docs/WALLETS.md)
+├─ client             typed REST clients: indexer, registry, sequencer
+└─ /wasm              loadKaspa() — the only environment-specific (Node vs browser) export
+```
+
+Every builder here operates against an **already-deployed** covenant instance — it takes the target's
+current compiled script bytes (read from your indexer, e.g. a UTXO's `redeemScriptHex`) and splices in the
+new state. This package does not include the covenant `.sil` sources or a compiler, and doesn't build the
+genesis/deploy transactions that create a *new* curve, pool, or token — only KRON's own deploy tooling does
+that.
+
+Full guide: [`docs/INTEGRATION.md`](docs/INTEGRATION.md). Wallet-adapter contract:
+[`docs/WALLETS.md`](docs/WALLETS.md).
+
+## Verification
+
+This package's covenant builders are **ported, not rewritten**, from KRON's own production code
+(`web/src/native/*`), which is exercised by an offline VM-verifier suite in the private KRON repo (covenant
+transitions run against the real Kaspa txscript engine). `scripts/e2e-offline-flow.mjs` exercises the full
+builder chain here offline (quote math, state-splicing, tx assembly, and the wallet-signing bridge) against
+a synthetic template, and checks the one property that matters most for fund safety: signing touches
+**only** the funding input, never a covenant input.
+
+What this package does **not** independently verify: full VM-level execution of the covenant scripts (that
+requires the Kaspa `cli-debugger` + the private KRON repo's verifier suite, which also holds the covenant
+sources and compiler this package doesn't ship) and on-chain broadcast (no network access from a clean
+install). If you're integrating funds-critical logic, treat `scripts/e2e-offline-flow.mjs` as a smoke test,
+not a substitute for testing against TN10 yourself before going to production.
+
+```bash
+npm run build && node scripts/smoke-test-node-wasm.mjs   # WASM loads + basic SDK calls work in plain Node
+node scripts/e2e-offline-flow.mjs                          # offline builder-chain sanity check
+```
+
+## Design notes
+
+- **ESM-only in v1.** The vendored wasm-bindgen glue (`kaspa.js`) is ESM with a top-level `import.meta.url`
+  reference; a dual CJS build would need its own async-import indirection for marginal benefit given most
+  modern bot/backend frameworks are ESM-first. Open an issue if this blocks you.
+- **Namespaced exports**, not flat. `curve/cpCurve.ts` and `native/curveCpTx.ts` both define their own
+  `SCALE`; builder names like `buy`/`sell`/`transfer` are generic enough to collide with your own code. So:
+  `import * as kron from '@kronsdk/kron-sdk'` then `kron.curve.quoteCpBuy(...)`, `kron.curveCp.buildCpBuy(...)`.
+- **No covenant compiler.** Builders take a target's already-compiled script bytes (`{script, stateStart}`)
+  as input rather than compiling from source — read these from your indexer's live UTXO data. This package
+  can build transactions against existing KRON tokens; it can't compile or deploy a new curve/pool/token.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE). Vendored third-party component (the Kaspa WASM SDK) is ISC-licensed; see
+[`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md).