Kaspa builder guide

Do not start with architecture. Start with the user action: a payment, vault rule, asset rule, market, proof, or later app-to-app flow. State comes after the action is specific.

Default: start with the smallest working path. Mainnet status still comes from activation, releases, and working applications.

Need terminal commands first? Open Kaspa Command Line From Zero.

1 / Job Name the action

Send, receive, lock, refund, issue, replay, prove, or settle.

2 / Path Pick the smallest path

Payment path, app receipt, covenant rule, based app, proof, or later app program.

3 / Evidence Show what landed

Accepted txid, app receipt, state output, replay row, source, or release record.

4 / Boundary Say what is missing

Mainnet activation, wallet support, liquidity, audit, indexer, oracle, or production custody.

Build around verifiable evidence

A repeatable Kaspa example starts with the user action, submits or inspects a transaction, replays the result, and labels the evidence class before making a bigger claim.

Good first example Payment or receipt

A user sends tKAS or attaches app data, then the page links the accepted txid and explains what changed.

Good covenant example Rule that blocks a bad spend

A cap, destination, required controller input, refund, or timeout is visible before the artifact details.

Weak example Mechanism without a user need

Lead with the user problem before internal mechanism names.

Start with state and proofs

Question	Use this path	Simpler path
Many users touch the same app state at the same time.	Start with based apps or vProgs-compatible runtime work.	Start with covenants and L1 state outputs.
The product splits into independent states.	Covenants can still work for each separate state.	Shared-state app architecture becomes more natural.
Each action needs its own proof, privacy check, or custom validity rule.	Consider inline ZK, but expect more proof and operations work.	Use covenants or based apps first.
The proof depends on another chain, an oracle, a price, or a real-world event.	Name the anchor first: source root, finality certificate, accumulated-work view, oracle, reporter set, or challenge process.	The proof can stay inside the app's own state rules.
The app needs synchronous composition with other independent apps.	That is the future full-vProgs direction, especially if several app states must succeed or fail as one operation.	Build the narrow app first. Toccata-era apps can coordinate through L1 proofs and sequencing without claiming full atomic composition.

Match app model to state model

Covenants are for constrained spend rules: vaults, treasury controls, escrow-like flows, unlock conditions, issuance policy, and small UTXO state machines. One protected state advances one valid step at a time.

Based apps are for richer app state anchored to Kaspa ordering: balances, orders, packs, risk rows, task states, or market state. They can start with deterministic replay over accepted transactions and add ZK only when proof-verified execution, privacy, or trust-minimized bridge logic becomes the product boundary.

Inline ZK is for actions that need their own proof before settlement. Full vProgs are the later app-to-app composition direction, where independent apps can read or call one another in one combined outcome.

Say what the example buys the user

A builder example needs the user job after the artifact: a budget that cannot be drained at once, an asset that moves only under a controller rule, a game turn that cannot get stuck forever, a payout that can be replayed, or a group payment that refunds if the condition fails.

Use this order before showing artifacts: what landed on TN12, what the reader can click or repeat, what the repo replayed from accepted rows, which rule is script-enforced versus replay-derived or wallet policy, and what remains missing before a real product claim.

Then keep the boundary honest. If the rule is script-enforced, name the script path. If it is wallet policy, planner state, replay-derived state, or testnet-only evidence, say that. The claim is strongest when the reader can see both the accepted path and the rejected path.

Use the same template for every covenant example: user need, spend rule, accepted path, rejected path, wallet review field, and remaining blocker. Say "budget that cannot drain at once," "step-by-step workflow," or "asset that needs its controller" before naming the mechanism.

For the public application framing, see what TN12 covenant tests are teaching. For the current testnet examples, open the TN12 experiment map.

Map product ideas to a path

Pick the smallest path that matches the product. Most first builds are a wallet/payment path, a covenant-shaped rule, or a narrow based app.

Open product-path table

Product shape	Likely starting path	Why
Vault, treasury, inheritance, recovery, escrow	Covenants	The product is mostly about who can move funds and how stateful outputs evolve.
Native asset issuance or transfer policy	Covenants	The app logic is asset-native and can often stay close to L1 output rules.
Trading venue, game economy, shared balance app	Based app	Many users need to update the same app record without waiting for one UTXO path to move first.
Private action, custom validity check, proof-gated workflow	Inline ZK	The proof is part of every action, so verification becomes the product boundary.
Composable app network with calls across independent apps	Full vProgs later	The need is app-to-app synchronous composition, which belongs to the longer architecture target.

Builder tools

Use Kaspa.org Build and the official getting-started docs for SDK and node entry points. Use Sources for Toccata releases, KIPs, Silverscript, vProgs, ZK SDK, Python SDK, WASM docs, hosted APIs, indexers, and node infrastructure.

Hosted APIs are fine for prototypes and dashboards. Products that sign transactions, track balances, handle custody, or promise uptime need a node, indexer, provider-redundancy plan, or all three.

Before prototyping

Pick network first. Mainnet uses kaspa:. TN12 uses kaspatest:. Never reuse test keys for mainnet.
Use the right node. Testnet covenant work needs a branch or release that supports that testnet. Mainnet builders use the released mainnet node.
Check sync and UTXO index. Unsynced local nodes and missing indexes can return misleading balances.
Separate UI policy from consensus rules. A mockup, planner state, or wallet warning is not an enforced covenant.
Record exact submit details. Log SDK version, node version, network id, endpoint, encoding, tx version, and input budget fields.

Prove the state change

After submit, fetch accepted state and compare the exact result to the thing the app claims happened.

Open verification checklist

Builder habit	Consequence	Check
Fetch accepted state after submit	Local construction does not prove accepted app state.	Record `is_accepted`, accepting block data, output script type, address, and amount.
Pin the submit surface	REST, JSON wRPC, Borsh wRPC, SDK versions, and testnet branches can expose different transaction shapes.	Log SDK version, node version, network id, endpoint, encoding, tx version, and input budget fields.
Compare with a known working spend	Witness order, signature preimage, redeem-script shape, and constructor keys are easier to check against a sibling transaction that already worked.	Diff the failing path against an accepted release, refund, or simple payment path before blaming protocol rules.
Label failed attempts narrowly	Tooling failures and consensus failures need different labels.	Keep the artifact, but mark it as bad config, stale tooling, submit mismatch, or confirmed consensus rejection.

Testnet lesson: teach the verification habit without turning one prototype into a mainnet claim.

Say the stage first

Covenants: nearer L1 state-output path for constrained asset and UTXO-state rules.
Based apps: app-specific state anchored to Kaspa ordering, commitments, proofs, settlement, or exits.
Inline ZK: specialized proof path for actions whose validity or privacy proof is the product boundary.
External anchors: ZK can check a statement about chosen inputs; builders must still define how source-chain roots, prices, events, or attestations become trusted inputs.
Based-zk apps: based apps that add proof-verified execution or bridge logic when deterministic replay is not enough.
Full vProgs: future app-to-app atomic composition direction, beyond standalone based-app construction.
Transaction payloads: live L1 transaction data for receipts and app context. Native smart-contract activation needs separate protocol evidence.

Use the positive stage first. Add caveats only where a reader might confuse builder work with live mainnet functionality.

Builder references

Izio's Kaspa programmability overview for the builder decision tree: covenants, based apps, inline ZK, and future full vProgs.
Izio on Covenants for sequential protected-output state, covenant IDs, and the current Silverscript builder reference.
Izio on Based Apps for shared-state app architecture and Rust app logic in a managed environment.
Izio on Inline ZK for per-action proofs and proof-driven settlement.
Izio on Full vProgs for future app-to-app synchronous composition.
Rusty Kaspa tn10-toc3 pre-release, tn10-toc2, and Testnet-10 REST status for the May 2026 Testnet-10 Toccata activation and hardening path.
rusty-kaspa TN12 branch, Silverscript, and TN12 faucet for testnet covenant prototyping context. These are testnet builder tools. Mainnet activation needs separate mainnet evidence.
Rusty Kaspa ZK SDK PR #953 for the merged R0ScriptBuilder helper around RISC Zero proof scripts. This is builder tooling progress. Mature mainnet ZK apps need separate product evidence.
KIP-24 for the open transaction-v1 fields and hashing PR, and KIP-22 for the open P2MR quantum-resistance ScriptPublicKey proposal. Open KIP PRs are design/proposal evidence until merged and activated.
Kaspa.org Build for the current developer resource index: Rusty Kaspa, WASM SDK, public node access, REST API, Docker, DB dumps, testnet, KIPs, Silverscript, vProgs, community infra, and R&D links.
Kaspa Developer Platform docs for hosted address history, transaction acceptance, block-range, and node RPC proxy APIs. Hosted infrastructure does not set protocol status.
Kaspa docs, especially Getting started, Programmability, Transaction payload, Accepted transactions, and Kaspa node, for current builder workflow guidance.
Aspectron RpcClient docs, signTransaction docs, and submit-transaction request docs for the JavaScript SDK request shape used by current builder examples.
KasSigner and KasSee for experimental external-signer and watch-only wallet references. They are wallet UX and signing-boundary research references. Shipped protocol status needs release and activation evidence.
Kaspa Explained status and source hierarchy for live/targeted/roadmap/research boundaries.

Keep reading