Skip to content

Commit 27f4f90

Browse files
dannywillemsdannywillems
committed
Add coinbase transaction documentation
Add comprehensive documentation for coinbase transactions covering structure, application logic, reward distribution, fee transfers, account creation, and testing. CHANGELOG: add entry for patch 1553
1 parent ad84b13 commit 27f4f90

File tree

3 files changed

+200
-0
lines changed

3 files changed

+200
-0
lines changed

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1919
test only packages that are tested in CI, avoiding untested packages with
2020
failing tests
2121
([#1573](https://github.com/o1-labs/mina-rust/pull/1573))
22+
- **Website**: add coinbase transaction documentation covering transaction
23+
structure, application logic, reward distribution, fee transfers, account
24+
creation, and comprehensive testing
25+
([#1553](https://github.com/o1-labs/mina-rust/pull/1553))
2226
- **CI**: Add validation workflows for block producer nodes infrastructure,
2327
including connectivity and API capability testing similar to plain nodes
2428
([#1571](https://github.com/o1-labs/mina-rust/pull/1571))

‎website/docs/developers/transactions/coinbase.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
---
2+
sidebar_position: 4
3+
title: Coinbase rewards
4+
description: Understanding coinbase reward transactions in the Mina protocol
5+
slug: /developers/transactions/coinbase
6+
---
7+
8+
# Coinbase rewards
9+
10+
## Overview
11+
12+
Coinbase transactions are protocol-generated rewards issued to block producers
13+
for successfully producing a block. They represent new MINA tokens entering
14+
circulation as compensation for maintaining the network.
15+
16+
A coinbase consists of:
17+
18+
- **Receiver**: The block producer receiving the reward
19+
- **Amount**: The coinbase reward amount (720 MINA by default)
20+
- **Fee transfer**: Optional fee transfer to SNARK worker
21+
22+
## Transaction structure
23+
24+
Coinbase transactions have a simple structure with an optional fee transfer:
25+
26+
<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic/mod.rs#L438-L442 -->
27+
28+
```rust reference title="ledger/src/scan_state/transaction_logic/mod.rs"
29+
https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/mod.rs#L438-L442
30+
```
31+
32+
<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic/mod.rs#L416-L419 -->
33+
34+
```rust reference title="ledger/src/scan_state/transaction_logic/mod.rs"
35+
https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/mod.rs#L416-L419
36+
```
37+
38+
### Creating coinbase
39+
40+
Coinbase transactions are constructed with validation logic:
41+
42+
<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic/mod.rs#L452-L476 -->
43+
44+
```rust reference title="ledger/src/scan_state/transaction_logic/mod.rs"
45+
https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/mod.rs#L452-L476
46+
```
47+
48+
## Transaction application
49+
50+
### First pass
51+
52+
During the first pass
53+
([`apply_coinbase`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/transaction_partially_applied.rs#L454)),
54+
the coinbase:
55+
56+
1. **Applies coinbase reward**
57+
- Adds coinbase amount to receiver's balance
58+
- Creates receiver account if it doesn't exist
59+
- Deducts account creation fee if creating account
60+
61+
2. **Applies fee transfer (if present)**
62+
- Adds fee to fee transfer receiver's balance
63+
- Deducts fee from coinbase receiver's reward
64+
- Creates fee transfer receiver account if needed
65+
66+
### No fee payment
67+
68+
Like fee transfers, coinbase transactions do not pay fees:
69+
70+
- No nonce increment
71+
- No fee payer
72+
- No signature required
73+
- Cannot be submitted by users
74+
75+
## Coinbase amount
76+
77+
The coinbase amount is configured in
78+
[`ConstraintConstants`](https://github.com/o1-labs/mina-rust/blob/develop/core/src/constants.rs#L39-L42)
79+
(`core/src/constants.rs`), which includes the base `coinbase_amount` and the
80+
`supercharged_coinbase_factor` for rewards when SNARK work is included. The
81+
specific values are defined in the network configurations:
82+
[devnet](https://github.com/o1-labs/mina-rust/blob/develop/core/src/network.rs#L145-L146)
83+
sets `coinbase_amount` to 720,000,000,000 nanomina (720 MINA) and
84+
`supercharged_coinbase_factor` to 1, while
85+
[mainnet](https://github.com/o1-labs/mina-rust/blob/develop/core/src/network.rs#L223-L224)
86+
uses the same values.
87+
88+
### Supercharged coinbase
89+
90+
Supercharged rewards were designed to provide double block rewards (factor of 2)
91+
to block producers staking with unlocked tokens during the early mainnet period
92+
following the 2021 launch. This mechanism incentivized participation and orderly
93+
markets after mainnet launch.
94+
95+
**Historical values**:
96+
97+
- Original mainnet: 2 (double rewards for unlocked tokens)
98+
- Berkeley hardfork (June 2024): 1 (supercharged rewards removed via
99+
[MIP1](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0001-remove-supercharged-rewards.md))
100+
101+
The removal was decided by community vote on January 1, 2023, as proposed by
102+
community member Gareth Davies. This change ensures uniform rewards for all
103+
tokens and reduces inflation, promoting a sustainable economic model.
104+
105+
**References**:
106+
107+
- [Berkeley Upgrade](https://minaprotocol.com/blog/minas-berkeley-upgrade-what-to-expect)
108+
- [Supercharged Rewards Removal](https://minaprotocol.com/blog/update-on-minas-supercharged-rewards-schedule)
109+
- [Original Proposal](https://github.com/MinaProtocol/mina/issues/5753)
110+
111+
## Fee transfer interaction
112+
113+
### Splitting the reward
114+
115+
When a coinbase includes a fee transfer, the reward is split
116+
([implementation](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/transaction_partially_applied.rs#L496-L498)):
117+
118+
- **Coinbase receiver**: Gets `coinbase_amount - fee_transfer_amount`
119+
- **Fee transfer receiver**: Gets `fee_transfer_amount`
120+
121+
This mechanism allows block producers to share rewards with SNARK workers.
122+
123+
### Same receiver
124+
125+
If the fee transfer receiver equals the coinbase receiver, the fee transfer is
126+
removed
127+
([`Coinbase::create`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/mod.rs#L452)):
128+
129+
<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic/mod.rs#L464-L472 -->
130+
131+
```rust reference title="ledger/src/scan_state/transaction_logic/mod.rs"
132+
https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/mod.rs#L464-L472
133+
```
134+
135+
## Account creation
136+
137+
If receiver accounts don't exist, they are created automatically:
138+
139+
### Coinbase receiver creation
140+
141+
When creating a new coinbase receiver account, the account creation fee is
142+
deducted from the reward:
143+
144+
<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic/transaction_partially_applied.rs#L559-L561 -->
145+
146+
```rust reference title="ledger/src/scan_state/transaction_logic/transaction_partially_applied.rs"
147+
https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/transaction_partially_applied.rs#L559-L561
148+
```
149+
150+
The
151+
[`sub_account_creation_fee`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/transaction_partially_applied.rs#L653)
152+
function handles the fee deduction logic.
153+
154+
### Fee transfer receiver creation
155+
156+
The fee transfer receiver follows standard account creation rules, and the fee
157+
transfer must be sufficient to cover the account creation fee.
158+
159+
## Testing
160+
161+
Comprehensive tests are available in
162+
[`ledger/tests/test_transaction_logic_first_pass_coinbase.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_coinbase.rs):
163+
164+
- [`test_apply_coinbase_without_fee_transfer`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_coinbase.rs#L76) -
165+
Basic coinbase reward
166+
- [`test_apply_coinbase_with_fee_transfer`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_coinbase.rs#L135) -
167+
Coinbase with SNARK work payment to existing account
168+
- [`test_apply_coinbase_with_fee_transfer_creates_account`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_coinbase.rs#L242) -
169+
Fee transfer creating new account
170+
- [`test_apply_coinbase_with_fee_transfer_to_same_account`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_coinbase.rs#L353) -
171+
Same receiver optimization
172+
- [`test_apply_coinbase_creates_account`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_coinbase.rs#L428) -
173+
Coinbase creating new account
174+
175+
## Related files
176+
177+
- [`ledger/src/scan_state/transaction_logic/mod.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/mod.rs) -
178+
Coinbase type definitions
179+
- [`ledger/src/scan_state/transaction_logic/transaction_partially_applied.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/transaction_partially_applied.rs) -
180+
Coinbase application logic
181+
- [`ledger/tests/test_transaction_logic_first_pass_coinbase.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_coinbase.rs) -
182+
Coinbase tests

‎website/sidebars.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,20 @@ const sidebars: SidebarsConfig = {
8585
'developers/ledger-crate',
8686
],
8787
},
88+
{
89+
type: 'category',
90+
label: 'Transactions',
91+
items: [
92+
'developers/transactions',
93+
{
94+
type: 'category',
95+
label: 'Transaction types',
96+
items: [
97+
'developers/transactions/coinbase',
98+
],
99+
},
100+
],
101+
},
88102
{
89103
type: 'category',
90104
label: 'APIs and Data',

0 commit comments

Comments
 (0)