Skip to content

KASPA_PROGRAMMABILITY_KERNEL.md

Latest commit

 

History

History
150 lines (114 loc) · 5.2 KB

KASPA_PROGRAMMABILITY_KERNEL.md

File metadata and controls

150 lines (114 loc) · 5.2 KB
Raw

Kaspa Programmability Kernel

Prepared: 2026-06-04.

KaspaScript is growing from a compiler into a Kaspa-native programmability kernel. The kernel treats contracts as UTXO state machines: a contract consumes stateful outputs, validates a transition, and creates successor outputs that preserve lineage.

This is smart-contract-like, but it is not an Ethereum-style global account runtime. The kernel is designed around Kaspa's BlockDAG and Toccata-era building blocks.

Kernel Contract Model

A kernel contract package contains:

  • contract state fields
  • transition definitions
  • source evidence and target network posture
  • wallet previews
  • covenant lineage indexer schema
  • capability profile
  • fee-policy math
  • readiness report

The first crate is kaspascript-kernel.

use kaspascript_kernel::{dagsafe_vault_blueprint, ToccataFeePolicy};

let package = dagsafe_vault_blueprint().package()?;
let release_preview = package
    .wallet_previews
    .iter()
    .find(|preview| preview.transition == "release_after_unlock");

let minimum_fee = ToccataFeePolicy::default()
    .minimum_standard_fee(1_000, 400)?;

CLI package command:

$ kaspascript kernel package tests/contracts/escrow.ks \
    --target verified-tn12 \
    --compute-grams 1000 \
    --tx-bytes 400
tests/contracts/escrow.kernel.json

The output JSON includes:

  • compiled artifact summary
  • bytecode hex and ASM
  • schema version and source snapshots
  • wallet previews
  • capability profile with execution model, feature support, transition profiles, wallet requirements, indexer requirements, and policy limits
  • covenant lineage indexer schema
  • readiness report with verified, preview, or blocked level
  • Toccata fee estimate and explicit fee assumptions

See KERNEL_PACKAGE_SCHEMA.md for the current emitted JSON shape.

Why This Is A Kernel

The compiler answers: "Can this source become deterministic Kaspa txscript?"

The kernel answers: "Can a builder safely ship this Kaspa app shape?"

That second question needs more than bytecode:

  • Wallets must show state transitions instead of ordinary payment copy.
  • SDKs and agents need a compact capability profile before they automate around a contract package.
  • Indexers must track covenant IDs, genesis outputs, continuations, authorizing inputs, accepted DAA context, and reorg state.
  • Fee estimation must follow Toccata policy instead of stale fixed-fee assumptions.
  • Mainnet claims must remain locked until final activation evidence is pinned.

First Flagship Blueprint

DAGSafeVault is the first kernel blueprint.

State:

  • owner
  • recovery_key
  • unlock_daa
  • covenant_id
  • policy_hash

Transitions:

  • deposit: creates a successor covenant output.
  • release_after_unlock: consumes the vault and creates an owner output.
  • emergency_recover: changes control through a recovery path.

The package emits wallet previews and a covenant lineage schema before any production bytecode lowering is claimed.

Evidence Posture

The bundled kernel evidence is pinned to the June 17, 2026 source audit:

  • v2.0.1 is the current mainnet Toccata maintenance release published on June 15, 2026. It is usable as the upgrade version for pre-Toccata 1.x nodes and includes seq-commit lane-proof RPC and covenant-binding refinements.
  • v2.0.0 is the baseline Toccata release published on June 5, 2026. Its release notes schedule activation at DAA score 474,165,565, roughly June 30, 2026 at 16:15 UTC, so KaspaScript treats both release tags as mainnet pre-activation evidence until activation is independently verified.
  • v1.3.0-toc.5 is mainnet pre-activation evidence only. It does not activate Toccata on mainnet.
  • PR #1000 is merged Toccata implementation evidence.
  • tn10-toc3 is TN10 ZK hardening activation evidence.
  • KIP-17, KIP-20, and KIP-21 merged files indicate TN10 activation status for the relevant covenant and sequencing surfaces.

Mainnet blueprints remain blocked until activation itself, crate compatibility, wallet/indexer support posture, and fee/mass behavior are pinned.

The tagged v2.0.1 Toccata guide is now the fee-policy source used by ToccataFeePolicy; see TOCCATA_V2_INTEGRATION.md.

The SDK now carries fixture-only Toccata facade types for transaction version 1, storage_mass, compute_commit, covenant bindings, user-lane targets, and seq-commit lane-proof request/response payloads. These are intentionally not Rusty Kaspa transactions yet; they are compatibility fixtures that make the next crate-integration step reviewable.

Next Kernel Upgrades

  1. Add Toccata git-tag compatibility fixtures to validate Kaspa crate APIs against the SDK facade types.
  2. Add wallet-preview golden tests for each production contract pattern.
  3. Add indexer fixtures for covenant genesis, continuation, reorg, and wrong-network cases.
  4. Add constraint extraction for signature, timelock, value, and script-binding checks inside the capability profile.
  5. Feed real node/RPC fee estimates into the package when available.
  6. Add a non-default Rusty Kaspa v2.0.1 compatibility feature for live SDK transaction-builder work.

See PROJECT_STATUS.md for the completion roadmap.