-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathbuilder-guide.html
More file actions
313 lines (302 loc) · 21.9 KB
/
Copy pathbuilder-guide.html
File metadata and controls
313 lines (302 loc) · 21.9 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
<!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="#000000">
<meta property="og:title" content="Kaspa Builder Guide | Kaspa Explained">
<meta property="og: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 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="A builder guide for choosing the simplest Kaspa route: money movement, covenant spend rules, based apps, inline ZK, or later app programs.">
<meta name="twitter:image" content="https://kaspaexplained.com/og-kaspa-explained-20260514.png?v=20260514-logo-clearance">
<meta name="dateModified" content="2026-07-25">
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "TechArticle",
"headline": "Kaspa Builder Guide",
"url": "https://kaspaexplained.com/builder-guide",
"dateModified": "2026-07-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=20260725-rows-j">
<script defer src="nav.js?v=20260708-dark-default"></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">Name the user action first, then pick the architecture: a payment, a vault rule, an asset rule, a market, a proof. Ask about state once that action is specific.</p>
<p class="fit-note"><strong>Default:</strong> start with the smallest working path. Mainnet status comes from activation, releases, and working applications.</p>
<p class="fit-note">Need terminal commands first? Open <a href="/command-line">how to verify a Kaspa transaction yourself</a>, which covers node, CLI, wRPC, and hosted-API commands.</p>
<div class="builder-console grid-cards" 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: name one verb.</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: pick the cheapest one that still does the job.</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: something a stranger can check without asking you.</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: name the actual, specific gap.</p>
</article>
</div>
</section>
<section class="section builder-workbench">
<h2>Build around verifiable evidence</h2>
<p>A repeatable Kaspa example does four things in order: names the user action, submits or inspects a transaction, replays the result, and labels the evidence class before anyone builds a bigger claim on top of it.</p>
<div class="builder-ledger grid-cards" 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; the page links the accepted txid and states exactly what changed.</p>
</article>
<article>
<span>Good covenant example</span>
<strong>Rule that blocks a bad spend</strong>
<p>Put the cap, destination, required controller input, refund, or timeout in front of the reader before the artifact details.</p>
</article>
<article>
<span>Weak example</span>
<strong>Mechanism without a user need</strong>
<p>If the demo names the internal mechanism before the user problem, that's the tell.</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 instead.</td>
</tr>
<tr>
<td>The product splits into independent states.</td>
<td>Covenants still work, one per separate state.</td>
<td>Shared-state app architecture fits better here.</td>
</tr>
<tr>
<td>Each action needs its own proof, privacy check, or custom validity rule.</td>
<td>Inline ZK is the fit, but it costs more proof and operations work than the alternatives.</td>
<td>Covenants or based apps handle this more cheaply.</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, before writing any proof code.</td>
<td>The proof stays inside the app's own state rules, no external anchor needed.</td>
</tr>
<tr>
<td>The app needs synchronous composition with other independent apps.</td>
<td>That's the <a href="/kaspa-vprogs-explained">future full-vProgs direction</a>, especially once several app states must succeed or fail as one operation.</td>
<td>Build the narrow app first. Toccata apps coordinate through L1 proofs and sequencing. Atomic composition across separate covenant apps is possible, as Argent's Inter-Covenant Communication shows, but only in unaudited offline demos so far.</td>
</tr>
</tbody>
</table>
</div>
</section>
<section class="section prose-section">
<h2>Match app model to state model</h2>
<p>Covenants are live on mainnet: they handle constrained spend rules such as 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. That constraint is the entire mechanism.</p>
<p>Based apps carry richer app state anchored to Kaspa ordering: balances, orders, packs, risk rows, task states, market state. Start with deterministic replay over accepted transactions. Add ZK once proof-verified execution, privacy, or trust-minimized bridge logic becomes the actual product boundary.</p>
<p>Inline ZK covers 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 read or call one another in one combined outcome. Transaction payloads already carry live L1 data for receipts and app context; native smart-contract activation is a separate claim with its own evidence.</p>
</section>
<section class="section prose-section">
<h2>Say what the example buys the user</h2>
<p>Attach a user job to every artifact: a budget that can't be drained at once, an asset that only moves under a controller rule, a game turn that can't get stuck forever, a payout that can be replayed, a group payment that refunds if the condition fails.</p>
<p>Show artifacts in this order: 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's still missing before this becomes a real product claim. The claim is strongest when the reader can see both the accepted path and the rejected path side by side.</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 prose-section">
<h2>Builder tools</h2>
<p>SDK and node entry points live at <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>. Toccata releases, KIPs, Silverscript, vProgs, ZK SDK, Python SDK, WASM docs, hosted APIs, indexers, and node infrastructure are tracked in <a href="/sources#code-tracking">Sources</a>.</p>
<p>Hosted APIs work fine for prototypes and dashboards. Products that sign transactions, track balances, handle custody, or promise uptime need a node, an indexer, a provider-redundancy plan, usually all three.</p>
</section>
<section class="section">
<h2>Before prototyping</h2>
<ol class="learning-steps grid-cards">
<li><strong>Pick network first.</strong> <span>Mainnet uses <code>kaspa:</code>. TN12 uses <code>kaspatest:</code>. Reusing test keys for mainnet is how funds get lost.</span></li>
<li><strong>Use the right node.</strong> <span>Testnet covenant work needs a branch or release built for that testnet. Mainnet builders run the released mainnet node.</span></li>
<li><strong>Check sync and UTXO index.</strong> <span>An unsynced local node or a missing index returns a balance that looks real and isn't.</span></li>
<li><strong>Separate UI policy from consensus rules.</strong> <span>A mockup, planner state, or wallet warning is not an enforced covenant. The chain doesn't know the UI exists.</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 every time.</span></li>
</ol>
</section>
<section class="section">
<h2>Prove the state change</h2>
<p>After submit, fetch accepted state and diff it against what the app claims happened. If they match, say so. If they don't, that's the bug report.</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 proves you built a transaction. It doesn't prove the network accepted it.</td>
<td>Record <code>is_accepted</code>, 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 each hand back a different transaction shape for the same request.</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 far easier to debug against a sibling transaction that already worked than in isolation.</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>A tooling failure and a consensus failure look identical from the outside. They need different labels or the next builder repeats your mistake.</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: the verification habit transfers to mainnet work. The prototype's status stays testnet-only until mainnet evidence says otherwise.</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">Application layer</a>
</div>
</section>
<section class="section">
<h2>Builder references</h2>
<ol class="source-list grid-cards">
<li><a href="https://progdoc.izio.fr/overview.html">Izio's Kaspa programmability overview</a> lays out the builder decision tree: covenants, based apps, inline ZK, future full vProgs.</li>
<li><a href="https://progdoc.izio.fr/state-programs.html">Izio on Covenants</a> covers 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> covers 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> covers per-action proofs and proof-driven settlement.</li>
<li><a href="https://progdoc.izio.fr/full-vprogs.html">Izio on Full vProgs</a> covers the future app-to-app synchronous composition direction.</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> document 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> cover testnet covenant prototyping. These are testnet builder tools, separate from mainnet activation evidence.</li>
<li><a href="https://github.com/kaspanet/rusty-kaspa/pull/953">Rusty Kaspa ZK SDK PR #953</a> merged the <code>R0ScriptBuilder</code> helper around RISC Zero proof scripts. That is tooling progress; mature mainnet ZK apps still need their own evidence.</li>
<li><a href="https://github.com/kaspanet/kips/pull/41">KIP-24</a> is the open transaction-v1 fields and hashing PR; <a href="https://github.com/kaspanet/kips/pull/37">KIP-22</a> is the open P2MR quantum-resistance ScriptPublicKey proposal. Both stay design/proposal evidence until merged and activated.</li>
<li><a href="https://kaspa.org/build">Kaspa.org Build</a> indexes current developer resources: Rusty Kaspa, WASM SDK, public node access, REST API, Docker, DB dumps, testnet, KIPs, Silverscript, vProgs, community infra, R&D links.</li>
<li><a href="https://docs.kas.fyi/">Kaspa Developer Platform docs</a> cover hosted address history, transaction acceptance, block-range, and node RPC proxy APIs. Hosted infrastructure doesn't set protocol status. That's a separate question.</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>, cover current builder workflow.</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> define the JavaScript SDK request shape used in current builder examples.</li>
<li><a href="https://github.com/InKasWeRust/KasSigner">KasSigner</a> and <a href="https://kassigner.org/">KasSee</a> are experimental external-signer and watch-only wallet references. They document wallet UX and signing-boundary research; shipped protocol status needs separate evidence.</li>
<li><a href="/status">Kaspa Explained status</a> and <a href="/sources">source hierarchy</a> hold the 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>Paste a Kaspa pitch and test it against users, liquidity, wallet flows, and evidence before you repeat the claim.</p></a>
<a href="/command-line"><span>Next</span><strong>How to verify a Kaspa transaction yourself</strong><p>How to verify a Kaspa transaction yourself: use explorers, second sources, wallets, hosted APIs, nodes, RPC, and accepted-transaction...</p></a>
<a href="/status"><span>Status</span><strong>Kaspa current status</strong><p>What is live, targeted, roadmap, and research on Kaspa right now, checked against mainnet, releases, and KIPs.</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>