-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathbuilder-guide.html
More file actions
375 lines (362 loc) · 24.6 KB
/
Copy pathbuilder-guide.html
File metadata and controls
375 lines (362 loc) · 24.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Kaspa Builder Guide | Kaspa Explained</title>
<meta name="description" content="A builder guide for choosing the simplest Kaspa route: money movement, covenant spend rules, based apps, inline ZK, or later app programs.">
<meta name="robots" content="index,follow,max-snippet:-1,max-image-preview:large">
<link rel="canonical" href="https://kaspaexplained.com/builder-guide">
<link rel="icon" href="kaspa-favicon.svg?v=20260512-real-k" type="image/svg+xml">
<link rel="icon" href="favicon.svg?v=20260512-k4" type="image/svg+xml">
<link rel="icon" href="favicon.ico" sizes="any">
<link rel="icon" href="favicon.png" type="image/png">
<link rel="apple-touch-icon" href="apple-touch-icon.png">
<link rel="manifest" href="site.webmanifest">
<meta name="application-name" content="Kaspa Explained">
<meta name="apple-mobile-web-app-title" content="Kaspa Explained">
<meta name="theme-color" content="#09090b">
<meta property="og:title" content="Kaspa Builder Guide | Kaspa Explained">
<meta property="og:description" content="Choose between money movement, covenants, based apps, inline ZK, and later app programs on Kaspa.">
<meta property="og:type" content="article">
<meta property="og:url" content="https://kaspaexplained.com/builder-guide">
<meta property="og:image" content="https://kaspaexplained.com/og-kaspa-explained-20260514.png?v=20260514-logo-clearance">
<meta property="og:image:type" content="image/png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="Kaspa Explained - proof-of-work blockDAG guide">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Kaspa Builder Guide | Kaspa Explained">
<meta name="twitter:description" content="Choose the right Kaspa build route without confusing builder tooling with live protocol status.">
<meta name="twitter:image" content="https://kaspaexplained.com/og-kaspa-explained-20260514.png?v=20260514-logo-clearance">
<meta name="dateModified" content="2026-06-25">
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "TechArticle",
"headline": "Kaspa Builder Guide",
"url": "https://kaspaexplained.com/builder-guide",
"dateModified": "2026-06-25",
"description": "A builder guide for choosing the simplest Kaspa build route.",
"about": ["Kaspa", "Covenants", "Silverscript", "Based Apps", "Inline ZK", "vProgs"]
}
</script>
<link rel="stylesheet" href="styles.css?v=20260627-next-card-fix">
<script defer src="nav.js?v=20260606-anchor-clearance"></script>
</head>
<body>
<a class="skip-link" href="#top">Skip to content</a>
<header class="site-header">
<nav class="nav" aria-label="Primary">
<a class="brand" href="/" aria-label="Kaspa Explained home">
<span class="brand-mark" aria-hidden="true"></span>
Kaspa Explained
</a>
<button class="nav-menu-button" type="button" aria-expanded="false" aria-controls="primary-links">Menu</button>
<div id="primary-links" class="nav-links">
<a href="/what-is-kaspa">What is Kaspa</a>
<a href="/status">Live now</a>
<a href="/kaspa-claims-checker">Check claims</a>
<a href="/skeptical-case">Risks</a>
<a href="/build-on-kaspa">Build</a>
<a href="/sources">Sources</a>
</div>
<button class="theme-toggle" type="button" aria-label="Switch theme">Light</button>
<a class="nav-cta" href="/toccata-status">Toccata status</a>
</nav>
</header>
<main id="top" tabindex="-1" class="builder-page">
<section class="section">
<h1>Kaspa builder guide</h1>
<p class="lead">A Kaspa build starts with the user action: a payment, vault rule, asset rule, market, proof, or later app-to-app flow. The state model comes after that action is specific.</p>
<p class="fit-note"><strong>Default:</strong> start with the smallest working path. Mainnet status still comes from activation, releases, and working applications.</p>
<p class="fit-note">Need terminal commands first? Open <a href="/command-line">Kaspa Command Line From Zero</a>.</p>
<div class="builder-console" aria-label="Kaspa builder verification path">
<article>
<span>1 / Job</span>
<strong>Name the action</strong>
<p>Send, receive, lock, refund, issue, replay, prove, or settle.</p>
</article>
<article>
<span>2 / Path</span>
<strong>Pick the smallest path</strong>
<p>Payment path, app receipt, covenant rule, based app, proof, or later app program.</p>
</article>
<article>
<span>3 / Evidence</span>
<strong>Show what landed</strong>
<p>Accepted txid, app receipt, state output, replay row, source, or release record.</p>
</article>
<article>
<span>4 / Boundary</span>
<strong>Say what is missing</strong>
<p>Mainnet activation, wallet support, liquidity, audit, indexer, oracle, or production custody.</p>
</article>
</div>
</section>
<section class="section builder-workbench">
<h2>Build around verifiable evidence</h2>
<p>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.</p>
<div class="builder-ledger" aria-label="Builder evidence ledger">
<article>
<span>Good first example</span>
<strong>Payment or receipt</strong>
<p>A user sends tKAS or attaches app data, then the page links the accepted txid and explains what changed.</p>
</article>
<article>
<span>Good covenant example</span>
<strong>Rule that blocks a bad spend</strong>
<p>A cap, destination, required controller input, refund, or timeout is visible before the artifact details.</p>
</article>
<article>
<span>Weak example</span>
<strong>Mechanism without a user need</strong>
<p>Lead with the user problem before internal mechanism names.</p>
</article>
</div>
</section>
<section class="section">
<h2>Start with state and proofs</h2>
<div class="table-wrap">
<table class="reality-table">
<thead>
<tr>
<th>Question</th>
<th>Use this path</th>
<th>Simpler path</th>
</tr>
</thead>
<tbody>
<tr>
<td>Many users touch the same app state at the same time.</td>
<td>Start with based apps or vProgs-compatible runtime work.</td>
<td>Start with covenants and L1 state outputs.</td>
</tr>
<tr>
<td>The product splits into independent states.</td>
<td>Covenants can still work for each separate state.</td>
<td>Shared-state app architecture becomes more natural.</td>
</tr>
<tr>
<td>Each action needs its own proof, privacy check, or custom validity rule.</td>
<td>Consider inline ZK, but expect more proof and operations work.</td>
<td>Use covenants or based apps first.</td>
</tr>
<tr>
<td>The proof depends on another chain, an oracle, a price, or a real-world event.</td>
<td>Name the anchor first: source root, finality certificate, accumulated-work view, oracle, reporter set, or challenge process.</td>
<td>The proof can stay inside the app's own state rules.</td>
</tr>
<tr>
<td>The app needs synchronous composition with other independent apps.</td>
<td>That is the <a href="/kaspa-vprogs-explained">future full-vProgs direction</a>, especially if several app states must succeed or fail as one operation.</td>
<td>Build the narrow app first. Toccata-era apps can coordinate through L1 proofs and sequencing without claiming full atomic composition.</td>
</tr>
</tbody>
</table>
</div>
</section>
<section class="section">
<h2>Match app model to state model</h2>
<p>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.</p>
<p>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.</p>
<p>Inline ZK is for actions that need their own proof before settlement. <a href="/kaspa-vprogs-explained">Full vProgs</a> are the later app-to-app composition direction, where independent apps can read or call one another in one combined outcome.</p>
</section>
<section class="section">
<h2>Say what the example buys the user</h2>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p class="fit-note">For the public application framing, see <a href="/application-layer#tn12-covenant-tests">what TN12 covenant tests are teaching</a>. For the current testnet examples, open the <a href="https://parker2017code.github.io/tn12-covenant-vault-demo/experiments.html">TN12 experiment map</a>.</p>
</section>
<section class="section">
<h2>Map product ideas to a path</h2>
<p>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.</p>
<details class="source-more">
<summary>Open product-path table</summary>
<div class="table-wrap">
<table class="reality-table">
<thead>
<tr>
<th>Product shape</th>
<th>Likely starting path</th>
<th>Why</th>
</tr>
</thead>
<tbody>
<tr>
<td>Vault, treasury, inheritance, recovery, escrow</td>
<td>Covenants</td>
<td>The product is mostly about who can move funds and how stateful outputs evolve.</td>
</tr>
<tr>
<td>Native asset issuance or transfer policy</td>
<td>Covenants</td>
<td>The app logic is asset-native and can often stay close to L1 output rules.</td>
</tr>
<tr>
<td>Trading venue, game economy, shared balance app</td>
<td>Based app</td>
<td>Many users need to update the same app record without waiting for one UTXO path to move first.</td>
</tr>
<tr>
<td>Private action, custom validity check, proof-gated workflow</td>
<td>Inline ZK</td>
<td>The proof is part of every action, so verification becomes the product boundary.</td>
</tr>
<tr>
<td>Composable app network with calls across independent apps</td>
<td><a href="/kaspa-vprogs-explained">Full vProgs later</a></td>
<td>The need is app-to-app synchronous composition, which belongs to the longer architecture target.</td>
</tr>
</tbody>
</table>
</div>
</details>
</section>
<section class="section">
<h2>Builder tools</h2>
<p>Use <a href="https://kaspa.org/build">Kaspa.org Build</a> and the <a href="https://docs.kaspa.org/integrate/getting-started">official getting-started docs</a> for SDK and node entry points. Use <a href="/sources#code-tracking">Sources</a> for Toccata releases, KIPs, Silverscript, vProgs, ZK SDK, Python SDK, WASM docs, hosted APIs, indexers, and node infrastructure.</p>
<p>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.</p>
</section>
<section class="section">
<h2>Before prototyping</h2>
<ol class="learning-steps">
<li><strong>Pick network first.</strong> <span>Mainnet uses <code>kaspa:</code>. TN12 uses <code>kaspatest:</code>. Never reuse test keys for mainnet.</span></li>
<li><strong>Use the right node.</strong> <span>Testnet covenant work needs a branch or release that supports that testnet. Mainnet builders use the released mainnet node.</span></li>
<li><strong>Check sync and UTXO index.</strong> <span>Unsynced local nodes and missing indexes can return misleading balances.</span></li>
<li><strong>Separate UI policy from consensus rules.</strong> <span>A mockup, planner state, or wallet warning is not an enforced covenant.</span></li>
<li><strong>Record exact submit details.</strong> <span>Log SDK version, node version, network id, endpoint, encoding, tx version, and input budget fields.</span></li>
</ol>
</section>
<section class="section">
<h2>Prove the state change</h2>
<p>After submit, fetch accepted state and compare the exact result to the thing the app claims happened.</p>
<details class="source-more">
<summary>Open verification checklist</summary>
<div class="table-wrap">
<table class="reality-table">
<thead>
<tr>
<th>Builder habit</th>
<th>Consequence</th>
<th>Check</th>
</tr>
</thead>
<tbody>
<tr>
<td>Fetch accepted state after submit</td>
<td>Local construction does not prove accepted app state.</td>
<td>Record `is_accepted`, accepting block data, output script type, address, and amount.</td>
</tr>
<tr>
<td>Pin the submit surface</td>
<td>REST, JSON wRPC, Borsh wRPC, SDK versions, and testnet branches can expose different transaction shapes.</td>
<td>Log SDK version, node version, network id, endpoint, encoding, tx version, and input budget fields.</td>
</tr>
<tr>
<td>Compare with a known working spend</td>
<td>Witness order, signature preimage, redeem-script shape, and constructor keys are easier to check against a sibling transaction that already worked.</td>
<td>Diff the failing path against an accepted release, refund, or simple payment path before blaming protocol rules.</td>
</tr>
<tr>
<td>Label failed attempts narrowly</td>
<td>Tooling failures and consensus failures need different labels.</td>
<td>Keep the artifact, but mark it as bad config, stale tooling, submit mismatch, or confirmed consensus rejection.</td>
</tr>
</tbody>
</table>
</div>
</details>
<p class="fit-note">Testnet lesson: teach the verification habit without turning one prototype into a mainnet claim.</p>
</section>
<section class="section">
<h2>Say the stage first</h2>
<ol class="learning-steps">
<li><strong>Covenants:</strong> <span>nearer L1 state-output path for constrained asset and UTXO-state rules.</span></li>
<li><strong>Based apps:</strong> <span>app-specific state anchored to Kaspa ordering, commitments, proofs, settlement, or exits.</span></li>
<li><strong>Inline ZK:</strong> <span>specialized proof path for actions whose validity or privacy proof is the product boundary.</span></li>
<li><strong>External anchors:</strong> <span>ZK can check a statement about chosen inputs; builders must still define how source-chain roots, prices, events, or attestations become trusted inputs.</span></li>
<li><strong>Based-zk apps:</strong> <span>based apps that add proof-verified execution or bridge logic when deterministic replay is not enough.</span></li>
<li><strong>Full vProgs:</strong> <span>future app-to-app atomic composition direction, beyond standalone based-app construction.</span></li>
<li><strong>Transaction payloads:</strong> <span>live L1 transaction data for receipts and app context. Native smart-contract activation needs separate protocol evidence.</span></li>
</ol>
<p class="fit-note">Use the positive stage first. Add caveats only where a reader might confuse builder work with live mainnet functionality.</p>
</section>
<section class="next-step section" aria-label="Suggested next step">
<h2>Build from current status</h2>
<p>Choose the model, then verify current implementation state before writing docs or product claims.</p>
<div class="actions">
<a class="button primary" href="/status">Open status</a>
<a class="button" href="/application-layer">App ideas</a>
</div>
</section>
<section class="section">
<h2>Builder references</h2>
<ol class="source-list">
<li><a href="https://progdoc.izio.fr/overview.html">Izio's Kaspa programmability overview</a> for the builder decision tree: covenants, based apps, inline ZK, and future full vProgs.</li>
<li><a href="https://progdoc.izio.fr/state-programs.html">Izio on Covenants</a> for sequential protected-output state, covenant IDs, and the current Silverscript builder reference.</li>
<li><a href="https://progdoc.izio.fr/app-vprogs.html">Izio on Based Apps</a> for shared-state app architecture and Rust app logic in a managed environment.</li>
<li><a href="https://progdoc.izio.fr/verified-actions.html">Izio on Inline ZK</a> for per-action proofs and proof-driven settlement.</li>
<li><a href="https://progdoc.izio.fr/full-vprogs.html">Izio on Full vProgs</a> for future app-to-app synchronous composition.</li>
<li><a href="https://github.com/kaspanet/rusty-kaspa/releases/tag/tn10-toc3">Rusty Kaspa tn10-toc3 pre-release</a>, <a href="https://github.com/kaspanet/rusty-kaspa/releases/tag/tn10-toc2">tn10-toc2</a>, and <a href="https://api-tn10.kaspa.org/info/blockdag">Testnet-10 REST status</a> for the May 2026 Testnet-10 Toccata activation and hardening path.</li>
<li><a href="https://github.com/kaspanet/rusty-kaspa/tree/tn12">rusty-kaspa TN12 branch</a>, <a href="https://github.com/kaspanet/silverscript">Silverscript</a>, and <a href="https://faucet-tn12.kaspanet.io/">TN12 faucet</a> for testnet covenant prototyping context. These are testnet builder tools. Mainnet activation needs separate mainnet evidence.</li>
<li><a href="https://github.com/kaspanet/rusty-kaspa/pull/953">Rusty Kaspa ZK SDK PR #953</a> for the merged <code>R0ScriptBuilder</code> helper around RISC Zero proof scripts. This is builder tooling progress. Mature mainnet ZK apps need separate product evidence.</li>
<li><a href="https://github.com/kaspanet/kips/pull/41">KIP-24</a> for the open transaction-v1 fields and hashing PR, and <a href="https://github.com/kaspanet/kips/pull/37">KIP-22</a> for the open P2MR quantum-resistance ScriptPublicKey proposal. Open KIP PRs are design/proposal evidence until merged and activated.</li>
<li><a href="https://kaspa.org/build">Kaspa.org Build</a> 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.</li>
<li><a href="https://docs.kas.fyi/">Kaspa Developer Platform docs</a> for hosted address history, transaction acceptance, block-range, and node RPC proxy APIs. Hosted infrastructure does not set protocol status.</li>
<li><a href="https://docs.kaspa.org/">Kaspa docs</a>, especially <a href="https://docs.kaspa.org/integrate/getting-started">Getting started</a>, <a href="https://docs.kaspa.org/programmability">Programmability</a>, <a href="https://docs.kaspa.org/integrate/transaction-payload">Transaction payload</a>, <a href="https://docs.kaspa.org/integrate/accepted-transactions">Accepted transactions</a>, and <a href="https://docs.kaspa.org/integrate/kaspa-node">Kaspa node</a>, for current builder workflow guidance.</li>
<li><a href="https://kaspa.aspectron.org/docs/classes/RpcClient.html">Aspectron RpcClient docs</a>, <a href="https://kaspa.aspectron.org/docs/functions/signTransaction.html">signTransaction docs</a>, and <a href="https://kaspa.aspectron.org/docs/interfaces/ISubmitTransactionRequest.html">submit-transaction request docs</a> for the JavaScript SDK request shape used by current builder examples.</li>
<li><a href="https://github.com/InKasWeRust/KasSigner">KasSigner</a> and <a href="https://kassigner.org/">KasSee</a> 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.</li>
<li><a href="/status">Kaspa Explained status</a> and <a href="/sources">source hierarchy</a> for live/targeted/roadmap/research boundaries.</li>
</ol>
</section>
<!-- related-links:start -->
<section class="section site-related" aria-labelledby="related-links-title">
<p class="eyebrow">Keep reading</p>
<h2 id="related-links-title">Next pages</h2>
<div class="site-related-grid">
<a href="/reality-check"><span>Previous</span><strong>Test the pitch before the narrative</strong><p>A Kaspa product-reality checklist and pitch scanner for testing crypto app claims against users, liquidity, wallet flows, evidence, and...</p></a>
<a href="/build-this-now"><span>Next</span><strong>What can you build on Kaspa now?</strong><p>Kaspa builder recipes: read DAG data, watch accepted transactions, track UTXOs, generate receipts, verify a txid, and replay TN12 evidence.</p></a>
<a href="/status"><span>Status</span><strong>Kaspa current status</strong><p>A compact status page for Kaspa: what is live, what is targeted, what is roadmap, what remains research, and which common claims need context.</p></a>
</div>
</section>
<!-- related-links:end -->
</main>
<footer class="footer">
<div class="footer-grid">
<p><strong>Independent Kaspa explainer.</strong> Claims are labeled live, targeted, roadmap, research, unsupported, or wrong. Not investment advice.</p>
<nav class="footer-nav-groups" aria-label="Footer">
<div class="footer-link-group" aria-label="Learn">
<span>Learn</span>
<a href="/start-here">Start here</a>
<a href="/what-is-kaspa">Kaspa 101</a>
<a href="/overview">90-second overview</a>
<a href="/glossary">Glossary</a>
</div>
<div class="footer-link-group" aria-label="Verify">
<span>Verify</span>
<a href="/status">Status</a>
<a href="/kaspa-claims-checker">Claims checker</a>
<a href="/toccata-status">Toccata status</a>
<a href="/skeptical-case">Skeptical case</a>
<a href="/sources">Sources</a>
</div>
<div class="footer-link-group" aria-label="Build">
<span>Build</span>
<a href="/build-on-kaspa">Build on Kaspa</a>
<a href="/builder-guide">Builder guide</a>
<a href="/kaspa-app-ideas">App ideas</a>
</div>
<div class="footer-link-group" aria-label="Site">
<span>Site</span>
<a href="/search">Search</a>
<a href="/about">About</a>
<a href="/about#corrections">Corrections</a>
</div>
</nav>
</div>
</footer>
</body>
</html>