Skip to content

Commit 24a0a0e

Browse files
dannywillemsdannywillems
committed
Website: introduce zkApps page
1 parent eede27f commit 24a0a0e

File tree

2 files changed

+245
-0
lines changed

2 files changed

+245
-0
lines changed

‎website/docs/developers/zkapps.md‎

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
---
2+
sidebar_position: 6
3+
title: zkApps and zkApp Commands
4+
description:
5+
Understanding zkApps and zkApp commands in the Mina protocol implementation
6+
slug: /developers/zkapps
7+
---
8+
9+
# zkApps and zkApp Commands
10+
11+
## Overview
12+
13+
zkApps (zero-knowledge applications) are programmable smart contracts on the
14+
Mina blockchain that leverage zero-knowledge proofs for private, verifiable
15+
computation. A **zkApp command** is the transaction type used to interact with
16+
zkApps, containing account updates that can be authorized by signatures or
17+
zero-knowledge proofs.
18+
19+
This document provides an entry point for developers joining the team to
20+
understand how zkApps are implemented in the Rust codebase.
21+
22+
## What is a zkApp?
23+
24+
A zkApp is a smart contract on Mina that:
25+
26+
- Stores state in on-chain accounts (8 field elements of app state)
27+
- Executes logic verified by zero-knowledge proofs
28+
- Can interact with multiple accounts atomically
29+
- Supports custom permissions and verification keys
30+
31+
Unlike traditional smart contracts that execute on-chain, zkApp logic executes
32+
off-chain and produces a zero-knowledge proof that the computation was performed
33+
correctly. Only the proof is verified on-chain, keeping the blockchain
34+
lightweight.
35+
36+
## What is a zkApp Command?
37+
38+
A **zkApp command** (`ZkAppCommand`) is a transaction type that applies updates
39+
to multiple accounts atomically. It consists of:
40+
41+
### Structure
42+
43+
<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic.rs#L3588-L3592 -->
44+
45+
```rust reference title="ledger/src/scan_state/transaction_logic.rs"
46+
https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic.rs#L3588-L3592
47+
```
48+
49+
### Components
50+
51+
#### 1. Fee Payer
52+
53+
The account that pays for the transaction. It must be authorized with a
54+
signature and its nonce must increase.
55+
56+
#### 2. Account Updates
57+
58+
A forest (list of trees) of account updates, where each `AccountUpdate`:
59+
60+
- Specifies an account to modify (identified by public key and token)
61+
- Declares preconditions that must be satisfied
62+
- Specifies state changes (balance, app state, permissions, etc.)
63+
- Provides authorization (signature, proof, or none)
64+
- Can make nested calls to other accounts
65+
66+
**Key type:**
67+
68+
<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic.rs#L2758-L2761 -->
69+
70+
```rust reference title="ledger/src/scan_state/transaction_logic.rs"
71+
https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic.rs#L2758-L2761
72+
```
73+
74+
#### 3. Memo
75+
76+
Optional data field (up to 32 bytes) for auxiliary information.
77+
78+
## Authorization Methods
79+
80+
<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic.rs#L2645-L2659 -->
81+
82+
```rust reference
83+
https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic.rs#L2645-L2659
84+
```
85+
86+
## Transaction Commitments and Signing
87+
88+
zkApp commands use transaction commitments for signing:
89+
90+
1. **Partial commitment** - Hash of account updates (for account update
91+
signatures)
92+
2. **Full commitment** - Includes memo and fee payer (for fee payer signature)
93+
94+
Account updates can specify whether to use the full commitment via the
95+
`use_full_commitment` flag.
96+
97+
### Commitment Computation
98+
99+
<!-- CODE_REFERENCE: ledger/src/generators/zkapp_command_builder.rs#L11-L22 -->
100+
101+
```rust reference title="ledger/src/generators/zkapp_command_builder.rs"
102+
https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/generators/zkapp_command_builder.rs#L11-L22
103+
```
104+
105+
### Signing Implementation
106+
107+
The signing logic replaces dummy authorizations with valid signatures/proofs:
108+
109+
<!-- CODE_REFERENCE: ledger/src/generators/zkapp_command_builder.rs#L28-L44 -->
110+
111+
```rust reference title="ledger/src/generators/zkapp_command_builder.rs"
112+
https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/generators/zkapp_command_builder.rs#L28-L44
113+
```
114+
115+
<!-- prettier-ignore-start -->
116+
:::note
117+
118+
The actual cryptographic signature generation is currently a TODO in the
119+
codebase (returns `Signature::dummy()`).
120+
121+
:::
122+
<!-- prettier-ignore-end -->
123+
124+
## Application Logic
125+
126+
The core zkApp business logic is implemented in:
127+
128+
- **[`ledger/src/zkapps/zkapp_logic.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/zkapps/zkapp_logic.rs)** -
129+
Main application logic for processing zkApp commands
130+
- **[`ledger/src/zkapps/non_snark.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/zkapps/non_snark.rs)** -
131+
Non-SNARK verification paths
132+
- **[`ledger/src/zkapps/snark.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/zkapps/snark.rs)** -
133+
SNARK-based verification
134+
- **[`ledger/src/zkapps/checks.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/zkapps/checks.rs)** -
135+
Precondition and permission checks
136+
137+
## Processing Pipeline
138+
139+
When a zkApp command is applied to the ledger:
140+
141+
1. **Validation** - Check transaction is well-formed and within cost limits
142+
2. **Fee payer verification** - Verify fee payer signature and sufficient
143+
balance
144+
3. **Account update processing** - For each account update:
145+
- Verify authorization (signature or proof)
146+
- Check preconditions (account state, protocol state)
147+
- Check permissions
148+
- Apply state changes atomically
149+
4. **Failure handling** - If any step fails, the entire command fails (except
150+
fee is still deducted)
151+
152+
**Key entry point:**
153+
[`ledger/src/scan_state/transaction_logic.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic.rs)
154+
(search for `apply_zkapp_command`)
155+
156+
## Cost and Weight Limits
157+
158+
zkApp commands have cost limits to prevent resource exhaustion:
159+
160+
<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic.rs#L3668-L3684 -->
161+
162+
```rust reference title="ledger/src/scan_state/transaction_logic.rs"
163+
https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic.rs#L3668-L3684
164+
```
165+
166+
The cost considers:
167+
168+
- Number of proof verifications
169+
- Number of signature verifications
170+
- Whether signatures verify single or paired account updates
171+
172+
## Testing and Generators
173+
174+
For testing, the codebase includes zkApp command generators:
175+
176+
- **[`ledger/src/generators/zkapp_command.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/generators/zkapp_command.rs)** -
177+
Generates random zkApp commands for testing
178+
- **[`ledger/src/generators/zkapp_command_builder.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/generators/zkapp_command_builder.rs)** -
179+
Utility functions for building and signing zkApp commands
180+
181+
## Key Files Reference
182+
183+
### Core Types
184+
185+
- [`ledger/src/scan_state/transaction_logic.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic.rs) -
186+
`ZkAppCommand`, `AccountUpdate`, `Control`, `FeePayer`
187+
188+
### Business Logic
189+
190+
- [`ledger/src/zkapps/zkapp_logic.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/zkapps/zkapp_logic.rs) -
191+
Main zkApp processing logic
192+
- [`ledger/src/zkapps/checks.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/zkapps/checks.rs) -
193+
Precondition and permission validation
194+
- [`ledger/src/zkapps/snark.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/zkapps/snark.rs) -
195+
SNARK verification implementation
196+
- [`ledger/src/zkapps/non_snark.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/zkapps/non_snark.rs) -
197+
Non-SNARK paths
198+
199+
### Signing and Building
200+
201+
- [`ledger/src/generators/zkapp_command_builder.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/generators/zkapp_command_builder.rs) -
202+
Transaction signing and authorization
203+
204+
### Proofs
205+
206+
- [`ledger/src/proofs/zkapp.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/proofs/zkapp.rs) -
207+
zkApp proof verification
208+
209+
## Transaction Failures
210+
211+
<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic.rs#L59-L154 -->
212+
213+
```rust reference title="ledger/src/scan_state/transaction_logic.rs"
214+
https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic.rs#L59-L154
215+
```
216+
217+
## Comparison to Other Transaction Types
218+
219+
Mina has three transaction types:
220+
221+
1. **[Signed Commands](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic.rs#L849)** -
222+
Simple payments and delegation changes, authorized by signature
223+
2. **[zkApp Commands](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic.rs#L3588)** -
224+
Complex multi-account updates with proof or signature authorization
225+
3. **[Coinbase](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic.rs#L500)** -
226+
Block rewards (internal, not user-submitted)
227+
228+
zkApp commands are more powerful but have higher complexity and cost limits.
229+
230+
## Getting Started
231+
232+
To start working with zkApps in the codebase:
233+
234+
1. Read the core types in
235+
[`ledger/src/scan_state/transaction_logic.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic.rs)
236+
(search for `ZkAppCommand`)
237+
2. Explore the application logic in
238+
[`ledger/src/zkapps/zkapp_logic.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/zkapps/zkapp_logic.rs)
239+
3. Review test generators in
240+
[`ledger/src/generators/`](https://github.com/o1-labs/mina-rust/tree/develop/ledger/src/generators)
241+
4. Study how zkApp commands flow through the transaction pool and staged ledger
242+
243+
For questions, consult the inline documentation in the source files or refer to
244+
the OCaml implementation for semantic clarity.

‎website/sidebars.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,7 @@ const sidebars: SidebarsConfig = {
8383
'developers/architecture',
8484
'developers/circuits',
8585
'developers/ledger-crate',
86+
'developers/zkapps',
8687
],
8788
},
8889
{

0 commit comments

Comments
 (0)