You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 0ac77d0
Browse filesBrowse the repository at this point in the historyBrowse files
* 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
Copy file name to clipboardExpand all lines: content/docs/toccata/covenant-state.mdx
+54-7Lines changed: 54 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,6 +22,11 @@ contract Counter(int init_count, int max_step) {
22
22
}
23
23
```
24
24
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
+
25
30
The interesting part is where `count` lives.
26
31
27
32
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:
74
79
75
80
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.
76
81
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:
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
+
77
122
## Why the hash keeps changing
78
123
79
124
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
90
135
S1 -->|"valid spend"| S2
91
136
```
92
137
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.
94
139
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.
96
141
97
-
Toccata makes lineage explicit.
142
+
KIP-20 gives Toccata that native rule.
98
143
99
144
## Covenant IDs
100
145
@@ -109,7 +154,7 @@ CovenantBinding {
109
154
110
155
An output may declare that it belongs to a covenant. When it becomes a UTXO, the UTXO entry carries the same `covenant_id`.
111
156
112
-
Consensus enforces the entrance rule:
157
+
Consensus enforces covenant membership at output creation:
113
158
114
159
- a continuation output may carry covenant id `id` only if its `authorizing_input` spends a UTXO that already carries `id`;
115
160
- 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.
159
204
| outputs belonging to covenant `id`|`OpCovOutputCount(id)`, `OpCovOutputIdx(id, k)`|
160
205
| binding data on output `o`|`OpOutputCovenantId(o)`, `OpOutputAuthorizingInput(o)`|
161
206
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
+
162
209
This supports transactions like:
163
210
164
211
```mermaid
@@ -202,7 +249,7 @@ One input creates one successor.
202
249
State_n -> State_n_plus_1
203
250
```
204
251
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.
206
253
207
254
### Fanout
208
255
@@ -212,7 +259,7 @@ One input creates many successors.
212
259
State -> State_A + State_B + State_C
213
260
```
214
261
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.
216
263
217
264
### Merge or many-to-many
218
265
@@ -291,7 +338,7 @@ An explorer can show balances and UTXOs with less context. A covenant-aware wall
291
338
292
339
## What to build next
293
340
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).
295
342
296
343
If your app is a family of roles that route between templates, read [Argent](./argent).
A -->|"mostly, with coordination"| M["multi-contract / multi-lane covenants"]:::cov
29
+
A -->|"mostly, with coordination"| M["multi-contract / parallel covenants"]:::cov
30
30
A -->|"no, one shared app state dominates"| B["based app"]:::zk
31
31
32
32
C --> P{"private or heavy<br/>local check?"}
@@ -51,17 +51,17 @@ With Toccata, L1 covenants can:
51
51
- keep stable lineage through covenant IDs;
52
52
- inspect transaction inputs and outputs;
53
53
- validate same-template and foreign-template successor states;
54
-
- split into many UTXO lanes;
54
+
- split into many parallel UTXOs;
55
55
- merge through leader/delegate transitions;
56
56
- use inline ZK for private or expensive local predicates.
57
57
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.
Copy file name to clipboardExpand all lines: content/docs/toccata/index.mdx
+7-9Lines changed: 7 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -62,7 +62,7 @@ Toccata adds the pieces needed for that check.
62
62
| ZK precompiles | direct verification of Groth16 and RISC Zero Succinct proofs inside script |
63
63
| Seqcommit lanes | app-specific L1 activity commitments for based apps, without proving the whole DAG |
64
64
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.
66
66
67
67
## Two roads
68
68
@@ -95,11 +95,11 @@ flowchart TB
95
95
96
96
Use L1 covenants when the state transition is small enough, public enough, and local enough to run directly in script.
97
97
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.
99
99
100
100
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.
101
101
102
-
Start with [Covenant State](./covenant-state).
102
+
Start with [Covenant State](/toccata/covenant-state).
103
103
104
104
### Road 2: Based ZK apps
105
105
@@ -125,7 +125,7 @@ sequenceDiagram
125
125
126
126
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.
127
127
128
-
Start with [Based Apps](./based-apps).
128
+
Start with [Based Apps](/toccata/based-apps).
129
129
130
130
## Transaction v1 is the shared floor
131
131
@@ -159,9 +159,7 @@ flowchart LR
159
159
S --> SR["signs covered outputs,<br/>not compute budget"]
160
160
```
161
161
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).
165
163
166
164
## How to read this book
167
165
@@ -200,9 +198,9 @@ The book is arranged as a reading sequence rather than a protocol spec.
200
198
/>
201
199
</Cards>
202
200
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.
204
202
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.
0 commit comments