Skip to content

Commit 0ac77d0

Browse files
Toccata book - second iteration (#53)
* docs: restrict lane terminology in Toccata guide * fix index page links * refine transaction v1 hash and covenant notes * explain and walkthrough silverscript covenant lowering * separate state naming and covenant authorization challenges * iterator note
1 parent c3fb0fd commit 0ac77d0

5 files changed

Lines changed: 109 additions & 67 deletions

File tree

‎content/docs/toccata/agent-brief.mdx‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ For based-app work:
4040
- `OpZkPrecompile` uses Groth16 tag `0x20` and RISC Zero Succinct tag `0x21`.
4141
- User-lane based-app operations are ordinary v1 L1 transactions with payload and lane id.
4242
- A user-lane subnetwork ID is `[namespace: 4 bytes, 0x00 * 16]`; `[x, 0x00 * 19]` forms are reserved system IDs except native and coinbase.
43-
- KIP-21 lanes let app proofs focus on lane activity instead of total DAG activity.
43+
- KIP-21 lanes let app proofs focus on lane activity instead of total DAG activity. Do not use the word "lane" to describe parallel UTXOs.
4444
- Silverscript, Argent, and vprogs APIs may move. Check the repo before writing production code.
4545

4646
## Prompt for covenant work
@@ -88,22 +88,22 @@ Before coding, identify:
8888

8989
## Common failure modes
9090

91-
| Agent move | Correction |
92-
| ----------------------------------------------------- | --------------------------------------------------------- |
93-
| Treats covenants like account contracts | Model them as UTXO state transitions |
94-
| Assumes covenant ID enforces app rules | Consensus controls entrance; script controls transition |
95-
| Checks inputs but not successor outputs | A covenant must validate the next output |
96-
| Signs or hashes `compute_budget` in the wrong context | V1 txid and v1 sighash exclude it; `tx::hash` includes it |
97-
| Uses v0 txid logic for v1 | V1 txid is BLAKE3 payload/rest |
98-
| Makes every based-app user op a covenant spend | User ops are L1 payload transactions on a lane |
99-
| Reaches for based apps too early | L1 covenants can scale when state splits into lanes |
100-
| Forces covenants onto shared mutable app state | Based apps exist for that architecture |
91+
| Agent move | Correction |
92+
| ----------------------------------------------------- | ------------------------------------------------------------ |
93+
| Treats covenants like account contracts | Model them as UTXO state transitions |
94+
| Assumes covenant ID enforces app rules | Consensus controls entrance; script controls transition |
95+
| Checks inputs but not successor outputs | A covenant must validate the next output |
96+
| Signs or hashes `compute_budget` in the wrong context | V1 txid and v1 sighash exclude it; `tx::hash` includes it |
97+
| Uses v0 txid logic for v1 | V1 txid is BLAKE3 payload/rest |
98+
| Makes every based-app user op a covenant spend | User ops are L1 payload transactions on a lane |
99+
| Reaches for based apps too early | L1 covenants can scale when state splits into parallel UTXOs |
100+
| Forces covenants onto shared mutable app state | Based apps exist for that architecture |
101101

102102
## Preflight questions
103103

104104
Ask the agent to answer these before implementation:
105105

106-
- Is the app state one UTXO, many UTXO lanes, or one off-chain state root?
106+
- Is the app state one UTXO, many parallel UTXOs, or one off-chain state root?
107107
- What must be impossible: unauthorized entrance, invalid transition, stale update, double spend, or invalid exit?
108108
- Which part is enforced by consensus, which by script, and which by off-chain tooling?
109109
- What does an indexer need to reconstruct live state?

‎content/docs/toccata/covenant-state.mdx‎

Lines changed: 54 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,11 @@ contract Counter(int init_count, int max_step) {
2222
}
2323
```
2424

25+
Declaration structure:
26+
27+
- `init_count` and `max_step` are constructor arguments. They are compile-time values for this contract instance: once the script instance is built, they are constants baked into the redeem script.
28+
- `count` is a state field. Its current value is encoded in the redeem-script preimage, and a new value means a new P2SH commitment.
29+
2530
The interesting part is where `count` lives.
2631

2732
It is not an account variable. It is not a node-side object. It is data inside the redeem-script preimage of the current UTXO.
@@ -74,6 +79,46 @@ That is the covenant loop:
7479

7580
The fourth step is the part older script systems struggle with. A covenant has to build or inspect enough bytes to know what the next output means. Toccata's byte and hash tools, including `OpCat`, `OpSubstr`, `OpBlake2b`, `OpBlake3`, and output introspection, are what make this pattern practical.
7681

82+
## What the macro expands into
83+
84+
Silverscript covenant declarations are designed to hide the repetitive part. The compiler lowers the `Counter` transition above into an ordinary entrypoint plus a policy function. The generated helper names are shown here in readable form:
85+
86+
```js
87+
contract Counter(int init_count, int max_step) {
88+
int count = init_count;
89+
90+
function covenant_policy_increment(State prev_state, int step) : (State) {
91+
require(step > 0);
92+
require(step <= max_step);
93+
return({ count: prev_state.count + step });
94+
}
95+
96+
entrypoint function increment(int step) {
97+
int auth_out_count = OpAuthOutputCount(this.activeInputIndex);
98+
99+
State prev_state = { count: count };
100+
(State cov_new_state) = covenant_policy_increment(prev_state, step);
101+
require(auth_out_count == 1);
102+
103+
int cov_out_idx = OpAuthOutputIdx(this.activeInputIndex, 0);
104+
validateOutputState(cov_out_idx, cov_new_state);
105+
}
106+
}
107+
```
108+
109+
The wrapper does the transaction work around the policy:
110+
111+
- `count` is the current state value pushed by the redeem-script preimage;
112+
- `covenant_policy_increment` is the user-written transition body, moved into a helper;
113+
- `entrypoint function increment(int step)` is the generated spend entrypoint selected by the transaction;
114+
- `OpAuthOutputCount` and `OpAuthOutputIdx` select the output authorized by this input;
115+
- `require(auth_out_count == 1)` enforces the singleton transition;
116+
- `validateOutputState(cov_out_idx, cov_new_state)` checks the successor output.
117+
118+
That last call uses a reflection-like awareness of the current script. The spent script uses its own revealed bytes as the template for the successor. The compiler knows the layout of the contract currently being spent. It emits code that takes the current redeem script preimage, replaces the encoded state fields with `cov_new_state`, rebuilds the expected P2SH script public key, and compares it to the authorized output.
119+
120+
So the output is not merely "some covenant output with the same id." It must commit to this same contract template, with the state fields changed exactly as the transition computed.
121+
77122
## Why the hash keeps changing
78123

79124
The P2SH hash commits to both contract and state. That supports state validation, but it creates a naming problem.
@@ -90,11 +135,11 @@ flowchart LR
90135
S1 -->|"valid spend"| S2
91136
```
92137

93-
If the script hash is the covenant's only identity, the covenant changes its name every time its state changes.
138+
That changing P2SH commitment is useful: it is how the current state is committed. But it is a poor stable name for the application instance. Wallets, explorers, indexers, and other contracts need a handle that survives state transitions.
94139

95-
Bitcoin-style designs can work around this with parent or grandparent preimages. The idea is to make fake successors unspendable by requiring the next spender to prove a relationship to the previous transaction. That works, but it is heavy: recursive preimages become part of the protocol, witness data grows, and the chain still does not know that a family of changing script hashes is one covenant lineage.
140+
There is a second, separate issue. A transaction must not be able to mint a new UTXO that merely claims to be part of an existing covenant family. Script-only covenant designs often handle this by carrying parent or grandparent transaction data and proving the relationship inside the script. That can make forged successors unspendable later, but it does not give consensus a native rule for rejecting the forged covenant-labeled output at creation time.
96141

97-
Toccata makes lineage explicit.
142+
KIP-20 gives Toccata that native rule.
98143

99144
## Covenant IDs
100145

@@ -109,7 +154,7 @@ CovenantBinding {
109154

110155
An output may declare that it belongs to a covenant. When it becomes a UTXO, the UTXO entry carries the same `covenant_id`.
111156

112-
Consensus enforces the entrance rule:
157+
Consensus enforces covenant membership at output creation:
113158

114159
- a continuation output may carry covenant id `id` only if its `authorizing_input` spends a UTXO that already carries `id`;
115160
- a genesis output may carry `id` only if the id is derived from the authorizing outpoint and the authorized initial outputs.
@@ -159,6 +204,8 @@ Toccata exposes both views.
159204
| outputs belonging to covenant `id` | `OpCovOutputCount(id)`, `OpCovOutputIdx(id, k)` |
160205
| binding data on output `o` | `OpOutputCovenantId(o)`, `OpOutputAuthorizingInput(o)` |
161206

207+
Each count/index pair acts like an iterator over the relevant subset: first ask how many entries exist, then ask for the `k`-th input or output index.
208+
162209
This supports transactions like:
163210

164211
```mermaid
@@ -202,7 +249,7 @@ One input creates one successor.
202249
State_n -> State_n_plus_1
203250
```
204251

205-
This is the counter, vault, or single-lane state machine pattern. It is simple, but it is sequential.
252+
This is the counter, vault, or single-UTXO state machine pattern. It is simple, but it is sequential.
206253

207254
### Fanout
208255

@@ -212,7 +259,7 @@ One input creates many successors.
212259
State -> State_A + State_B + State_C
213260
```
214261

215-
This is how a covenant can split into independent lanes: mint tickets, create positions, open games, allocate shards, or distribute token state.
262+
This is how a covenant can split into parallel lineages: mint tickets, create positions, open games, allocate shards, or distribute token state.
216263

217264
### Merge or many-to-many
218265

@@ -291,7 +338,7 @@ An explorer can show balances and UTXOs with less context. A covenant-aware wall
291338

292339
## What to build next
293340

294-
If your app is one lane or many independent lanes, continue with [Silverscript](./silverscript).
341+
If your app is one live UTXO or many independent UTXO lineages, continue with [Silverscript](./silverscript).
295342

296343
If your app is a family of roles that route between templates, read [Argent](./argent).
297344

‎content/docs/toccata/decision-guide.mdx‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Complexity is not the axis. Shared state is.
1010
Ask the state-layout question first:
1111

1212
```text
13-
Can the app be expressed as many live UTXO state lanes,
13+
Can the app be expressed as many parallel live UTXOs,
1414
or does it need many users mutating one shared state object?
1515
```
1616

@@ -24,9 +24,9 @@ flowchart TD
2424
classDef zk fill:#f7f1ff,stroke:#8b68ca,color:#1d162b
2525
classDef warn fill:#fff7e8,stroke:#c58b2a,color:#1f1b12
2626
27-
A{"Can state split into<br/>many UTXO lanes?"}
27+
A{"Can state split into<br/>parallel UTXOs?"}
2828
A -->|"yes"| C["L1 covenant family"]:::cov
29-
A -->|"mostly, with coordination"| M["multi-contract / multi-lane covenants"]:::cov
29+
A -->|"mostly, with coordination"| M["multi-contract / parallel covenants"]:::cov
3030
A -->|"no, one shared app state dominates"| B["based app"]:::zk
3131
3232
C --> P{"private or heavy<br/>local check?"}
@@ -51,17 +51,17 @@ With Toccata, L1 covenants can:
5151
- keep stable lineage through covenant IDs;
5252
- inspect transaction inputs and outputs;
5353
- validate same-template and foreign-template successor states;
54-
- split into many UTXO lanes;
54+
- split into many parallel UTXOs;
5555
- merge through leader/delegate transitions;
5656
- use inline ZK for private or expensive local predicates.
5757

58-
Kaspa's 10 BPS target changes this calculation. If an app can partition its state, the DAG gives those lanes room to move. A covenant family that would bottleneck on a slower chain may be practical here.
58+
Kaspa's 10 BPS target changes this calculation. If an app can partition its state, the DAG gives those tracks room to move. A covenant family that would bottleneck on a slower chain may be practical here.
5959

6060
Start with covenants when:
6161

6262
| If the app needs | Covenant design |
6363
| ----------------------------------------------------- | ------------------------------------------------ |
64-
| one state lane | singleton covenant |
64+
| one live state UTXO | singleton covenant |
6565
| many independent positions, tickets, vaults, or games | fanout covenant family |
6666
| token-like conservation across inputs/outputs | shared covenant id with leader/delegate |
6767
| roles and routes | multi-contract Silverscript, Argent-style design |
@@ -151,7 +151,7 @@ Avoid it when the app really wants many operations batched into one state transi
151151
Pick the smallest model that carries the real invariant.
152152

153153
1. Use one covenant when the state is naturally sequential.
154-
2. Use a covenant family when state can split into lanes.
154+
2. Use a covenant family when state can split into parallel UTXOs.
155155
3. Use multi-contract covenants when roles and routes dominate the design.
156156
4. Add inline ZK when a transition needs proof verification.
157157
5. Move to a based app when shared state and app-scale execution dominate.

‎content/docs/toccata/index.mdx‎

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ Toccata adds the pieces needed for that check.
6262
| ZK precompiles | direct verification of Groth16 and RISC Zero Succinct proofs inside script |
6363
| Seqcommit lanes | app-specific L1 activity commitments for based apps, without proving the whole DAG |
6464

65-
The result is still UTXO-native. Toccata does not turn Kaspa into an account-chain smart contract system. Instead it makes UTXOs able to carry state, split into lanes, merge when necessary, and prove the next step.
65+
The result is still UTXO-native. Toccata does not turn Kaspa into an account-chain smart contract system. Instead it makes UTXOs able to carry state, split into parallel lineages, merge when necessary, and prove the next step.
6666

6767
## Two roads
6868

@@ -95,11 +95,11 @@ flowchart TB
9595

9696
Use L1 covenants when the state transition is small enough, public enough, and local enough to run directly in script.
9797

98-
This road is more expressive than it first looks. A single global state UTXO is sequential, but Kaspa's high-frequency DAG makes many covenant families viable when state is split into independent lanes. A token system, market, game league, vault set, or routing family can have many live UTXOs advancing in parallel, with occasional merge or leader/delegate transitions when shared coordination is needed.
98+
A single state UTXO is sequential. That does not make every covenant app sequential. When state can be partitioned into positions, games, vaults, tickets, orders, shards, or similar app objects, each object can live on its own UTXO track: the current covenant UTXO plus the successor UTXOs that continue it. Kaspa's high-frequency DAG gives those UTXOs room to advance in parallel, while the covenant family can still merge lineages or coordinate them through leader/delegate transitions.
9999

100100
Silverscript is the intended authoring surface for L1 covenant apps. Argent is best understood as the next layer up: actor-style, multi-contract source that can lower into Silverscript the way `async` lowers into a more mechanical runtime representation.
101101

102-
Start with [Covenant State](./covenant-state).
102+
Start with [Covenant State](/toccata/covenant-state).
103103

104104
### Road 2: Based ZK apps
105105

@@ -125,7 +125,7 @@ sequenceDiagram
125125

126126
KIP-21 is what makes this practical. Without partitioned sequencing commitments, every app would need to prove not only which transactions targeted it, but also which transactions did not. With lanes, the proof can focus on the app's own L1 activity.
127127

128-
Start with [Based Apps](./based-apps).
128+
Start with [Based Apps](/toccata/based-apps).
129129

130130
## Transaction v1 is the shared floor
131131

@@ -159,9 +159,7 @@ flowchart LR
159159
S --> SR["signs covered outputs,<br/>not compute budget"]
160160
```
161161

162-
That separation affects wallets, indexers, relayers, ZK guests, and anyone debugging why two hashes that "should be the same" are not.
163-
164-
Continue with [Transaction V1](./transaction-v1).
162+
Continue with [Transaction V1](/toccata/transaction-v1).
165163

166164
## How to read this book
167165

@@ -200,9 +198,9 @@ The book is arranged as a reading sequence rather than a protocol spec.
200198
/>
201199
</Cards>
202200

203-
If you are using coding agents, read [Agent Brief](./agent-brief) early and attach it to implementation tasks. It tells an agent which mental model not to miss: validate the next output, respect covenant IDs, do not invent account-state assumptions, and check the exact repo behavior before making protocol claims.
201+
If you are using coding agents, read [Agent Brief](/toccata/agent-brief) early and attach it to implementation tasks. It tells an agent which mental model not to miss: validate the next output, respect covenant IDs, do not invent account-state assumptions, and check the exact repo behavior before making protocol claims.
204202

205-
If you are making an architecture call, read [Decision Guide](./decision-guide) after the first three chapters. The core decision is usually about shared state: whether the app can be split into many UTXO lanes, whether it needs occasional coordinated transitions, or whether it really wants an off-chain state machine with proof-based settlement.
203+
If you are making an architecture call, read [Decision Guide](/toccata/decision-guide) after the first three chapters. The core decision is usually about shared state: whether the app can be split into many parallel UTXOs, whether it needs occasional coordinated transitions, or whether it really wants an off-chain state machine with proof-based settlement.
206204

207205
## Status notes
208206

0 commit comments

Comments
 (0)