From 892922a5776863d232be0f366c07f523c0bc5bf9 Mon Sep 17 00:00:00 2001 From: Danny Willems Date: Fri, 31 Oct 2025 22:23:26 +0800 Subject: [PATCH 1/3] 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 --- CHANGELOG.md | 4 + .../docs/developers/transactions/coinbase.md | 182 ++++++++++++++++++ website/sidebars.ts | 14 ++ 3 files changed, 200 insertions(+) create mode 100644 website/docs/developers/transactions/coinbase.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 0d320426e..4efbab727 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 test only packages that are tested in CI, avoiding untested packages with failing tests ([#1573](https://github.com/o1-labs/mina-rust/pull/1573)) +- **Website**: add coinbase transaction documentation covering transaction + structure, application logic, reward distribution, fee transfers, account + creation, and comprehensive testing + ([#1553](https://github.com/o1-labs/mina-rust/pull/1553)) - **CI**: Add validation workflows for block producer nodes infrastructure, including connectivity and API capability testing similar to plain nodes ([#1571](https://github.com/o1-labs/mina-rust/pull/1571)) diff --git a/website/docs/developers/transactions/coinbase.md b/website/docs/developers/transactions/coinbase.md new file mode 100644 index 000000000..7fe4b8f30 --- /dev/null +++ b/website/docs/developers/transactions/coinbase.md @@ -0,0 +1,182 @@ +--- +sidebar_position: 4 +title: Coinbase rewards +description: Understanding coinbase reward transactions in the Mina protocol +slug: /developers/transactions/coinbase +--- + +# Coinbase rewards + +## Overview + +Coinbase transactions are protocol-generated rewards issued to block producers +for successfully producing a block. They represent new MINA tokens entering +circulation as compensation for maintaining the network. + +A coinbase consists of: + +- **Receiver**: The block producer receiving the reward +- **Amount**: The coinbase reward amount (720 MINA by default) +- **Fee transfer**: Optional fee transfer to SNARK worker + +## Transaction structure + +Coinbase transactions have a simple structure with an optional fee transfer: + + + +```rust reference title="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#L438-L442 +``` + + + +```rust reference title="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#L416-L419 +``` + +### Creating coinbase + +Coinbase transactions are constructed with validation logic: + + + +```rust reference title="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#L452-L476 +``` + +## Transaction application + +### First pass + +During the first pass +([`apply_coinbase`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/transaction_partially_applied.rs#L454)), +the coinbase: + +1. **Applies coinbase reward** + - Adds coinbase amount to receiver's balance + - Creates receiver account if it doesn't exist + - Deducts account creation fee if creating account + +2. **Applies fee transfer (if present)** + - Adds fee to fee transfer receiver's balance + - Deducts fee from coinbase receiver's reward + - Creates fee transfer receiver account if needed + +### No fee payment + +Like fee transfers, coinbase transactions do not pay fees: + +- No nonce increment +- No fee payer +- No signature required +- Cannot be submitted by users + +## Coinbase amount + +The coinbase amount is configured in +[`ConstraintConstants`](https://github.com/o1-labs/mina-rust/blob/develop/core/src/constants.rs#L39-L42) +(`core/src/constants.rs`), which includes the base `coinbase_amount` and the +`supercharged_coinbase_factor` for rewards when SNARK work is included. The +specific values are defined in the network configurations: +[devnet](https://github.com/o1-labs/mina-rust/blob/develop/core/src/network.rs#L145-L146) +sets `coinbase_amount` to 720,000,000,000 nanomina (720 MINA) and +`supercharged_coinbase_factor` to 1, while +[mainnet](https://github.com/o1-labs/mina-rust/blob/develop/core/src/network.rs#L223-L224) +uses the same values. + +### Supercharged coinbase + +Supercharged rewards were designed to provide double block rewards (factor of 2) +to block producers staking with unlocked tokens during the early mainnet period +following the 2021 launch. This mechanism incentivized participation and orderly +markets after mainnet launch. + +**Historical values**: + +- Original mainnet: 2 (double rewards for unlocked tokens) +- Berkeley hardfork (June 2024): 1 (supercharged rewards removed via + [MIP1](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0001-remove-supercharged-rewards.md)) + +The removal was decided by community vote on January 1, 2023, as proposed by +community member Gareth Davies. This change ensures uniform rewards for all +tokens and reduces inflation, promoting a sustainable economic model. + +**References**: + +- [Berkeley Upgrade](https://minaprotocol.com/blog/minas-berkeley-upgrade-what-to-expect) +- [Supercharged Rewards Removal](https://minaprotocol.com/blog/update-on-minas-supercharged-rewards-schedule) +- [Original Proposal](https://github.com/MinaProtocol/mina/issues/5753) + +## Fee transfer interaction + +### Splitting the reward + +When a coinbase includes a fee transfer, the reward is split +([implementation](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/transaction_partially_applied.rs#L496-L498)): + +- **Coinbase receiver**: Gets `coinbase_amount - fee_transfer_amount` +- **Fee transfer receiver**: Gets `fee_transfer_amount` + +This mechanism allows block producers to share rewards with SNARK workers. + +### Same receiver + +If the fee transfer receiver equals the coinbase receiver, the fee transfer is +removed +([`Coinbase::create`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/mod.rs#L452)): + + + +```rust reference title="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#L464-L472 +``` + +## Account creation + +If receiver accounts don't exist, they are created automatically: + +### Coinbase receiver creation + +When creating a new coinbase receiver account, the account creation fee is +deducted from the reward: + + + +```rust reference title="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#L559-L561 +``` + +The +[`sub_account_creation_fee`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/transaction_partially_applied.rs#L653) +function handles the fee deduction logic. + +### Fee transfer receiver creation + +The fee transfer receiver follows standard account creation rules, and the fee +transfer must be sufficient to cover the account creation fee. + +## Testing + +Comprehensive tests are available in +[`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): + +- [`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) - + Basic coinbase reward +- [`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) - + Coinbase with SNARK work payment to existing account +- [`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) - + Fee transfer creating new account +- [`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) - + Same receiver optimization +- [`test_apply_coinbase_creates_account`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_coinbase.rs#L428) - + Coinbase creating new account + +## Related files + +- [`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) - + Coinbase type definitions +- [`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) - + Coinbase application logic +- [`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) - + Coinbase tests diff --git a/website/sidebars.ts b/website/sidebars.ts index 5afc4a34d..85891ab79 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -86,6 +86,20 @@ const sidebars: SidebarsConfig = { 'developers/ledger-crate', ], }, + { + type: 'category', + label: 'Transactions', + items: [ + 'developers/transactions', + { + type: 'category', + label: 'Transaction types', + items: [ + 'developers/transactions/coinbase', + ], + }, + ], + }, { type: 'category', label: 'APIs and Data', From 1aa335bb9c13c9307c24ed41ae39cb661fabbb23 Mon Sep 17 00:00:00 2001 From: Danny Willems Date: Fri, 31 Oct 2025 22:24:15 +0800 Subject: [PATCH 2/3] CHANGELOG: add entry for patch 1582 --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4efbab727..932c77654 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,7 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Website**: add coinbase transaction documentation covering transaction structure, application logic, reward distribution, fee transfers, account creation, and comprehensive testing - ([#1553](https://github.com/o1-labs/mina-rust/pull/1553)) + ([#1582](https://github.com/o1-labs/mina-rust/pull/1582)) - **CI**: Add validation workflows for block producer nodes infrastructure, including connectivity and API capability testing similar to plain nodes ([#1571](https://github.com/o1-labs/mina-rust/pull/1571)) From ecd058b92a3bca766f0d41de8a60591914c10f02 Mon Sep 17 00:00:00 2001 From: Danny Willems Date: Fri, 31 Oct 2025 22:30:46 +0800 Subject: [PATCH 3/3] Update transactions.md from PR 1553 with link fixes Replace the initial transactions.md with the comprehensive version from PR 1553. Convert undefined transaction type links to section anchors to prevent broken links until those documentation pages are created. --- website/docs/developers/transactions.md | 180 ++++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 website/docs/developers/transactions.md diff --git a/website/docs/developers/transactions.md b/website/docs/developers/transactions.md new file mode 100644 index 000000000..1803188e3 --- /dev/null +++ b/website/docs/developers/transactions.md @@ -0,0 +1,180 @@ +--- +sidebar_position: 5 +title: Introduction +description: Understanding transaction types in the Mina protocol implementation +slug: /developers/transactions +--- + +# Introduction + +## Overview + +Transactions in Mina represent state changes to the ledger. The protocol +supports both user-initiated transactions and protocol-generated transactions, +each serving distinct purposes in the blockchain's operation. + +This document provides an entry point for developers to understand how +transactions are structured and processed in the Rust codebase. + +## Transaction Types + +The top-level `Transaction` enum represents all possible transactions in the +Mina protocol: + + + +```rust reference title="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#L1093-L1100 +``` + +### User-Initiated Transactions + +**User Commands** are transactions submitted and signed by users: + +- **Payment transactions** - Transfer MINA tokens between accounts +- **Stake delegation** - Delegate stake to block producers +- **zkApp commands** - Execute complex multi-account zero-knowledge operations + +### Protocol Transactions + +**Protocol transactions** (also called **system transactions**) are generated +automatically by the system: + +- **Fee transfers** - Distribute collected transaction fees to block producers +- **[Coinbase rewards](./transactions/coinbase)** - Issue block production + rewards + +## Transaction Application Model + +Transactions in Mina are applied in two phases: + +### First Pass (`apply_transaction_first_pass`) + +The first pass validates preconditions and begins transaction application: + +- Validates account existence and permissions +- Checks nonces and balances +- Applies fee payments +- Performs initial state changes +- Returns `TransactionPartiallyApplied` containing transaction state + +**Function:** +[`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#L190) + +### Second Pass (`apply_transaction_second_pass`) + +The second pass completes the transaction after SNARK work: + +- Finalizes account updates +- Applies protocol-specific logic +- Updates receipt chain hashes +- Returns final `TransactionApplied` status + +**Function:** +[`ledger/src/scan_state/transaction_logic/transaction_applied.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/transaction_applied.rs) + +## Common Transaction Components + +### Fees + +All user-initiated transactions require fees. The `Fee` type is generated by a +macro along with other currency types in +[`ledger/src/scan_state/currency.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/currency.rs#L575-L578). + +Fees serve two purposes: they compensate block producers for including +transactions and prevent network spam by making it economically infeasible to +flood the network with transactions. Fees are paid by the transaction sender (or +fee payer in zkApp commands) and distributed to block producers through fee +transfers. + +### Nonces + +User accounts maintain nonces to prevent replay attacks. The `Nonce` type is +generated by a macro along with other currency types in +[`ledger/src/scan_state/currency.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/currency.rs#L575-L578). + +Each user-initiated transaction must specify the correct nonce, which increments +after successful application. + +### Memos + +Transactions can include optional 32-byte memos: + + + +```rust reference title="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#L548-L548 +``` + +Memos provide auxiliary information and are included in transaction commitments. + +### Slots + +A slot is a fixed time interval in the consensus protocol during which a block +can be produced. Slots are used to measure time in the blockchain and determine +block production opportunities. + +Transactions include validity windows using slot numbers. The `Slot` type is +generated by a macro along with other currency types in +[`ledger/src/scan_state/currency.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/currency.rs#L575-L578). + +The `valid_until` field specifies when a transaction expires. + +## Account Creation + +Creating new accounts requires an account creation fee (1 MINA by default): + +```rust +ConstraintConstants { + account_creation_fee: 1_000_000_000, // 1 MINA in nanomina + // ... +} +``` + +The fee is deducted from the amount being transferred to the new account: + +- **Payments**: Sender pays `amount + fee`, receiver gets + `amount - account_creation_fee` (if creating account) +- **Fee transfers**: Receiver gets `fee_amount - account_creation_fee` (if + creating account) +- **Coinbase**: Receiver gets `coinbase_amount - account_creation_fee` (if + creating account) + +## Transaction Status + +After application, transactions have a status: + + + +```rust reference title="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#L240-L243 +``` + +Failed transactions may still consume fees in some cases (zkApp commands with +fee payer failures). + +## Further Reading + +- [Coinbase Rewards](./transactions/coinbase) - Block production rewards + +Documentation for additional transaction types is coming soon: + +- Payment Transactions - Transferring tokens between accounts +- Stake Delegation - Delegating stake to block producers +- Fee Transfers - Protocol fee distribution +- zkApp Commands - Zero-knowledge applications + +## Related Files + +- [`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) - + Transaction type definitions +- [`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) - + First pass application +- [`ledger/src/scan_state/transaction_logic/transaction_applied.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/transaction_applied.rs) - + Second pass application +- [`ledger/src/scan_state/transaction_logic/signed_command.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/signed_command.rs) - + Signed command types +- [`ledger/src/scan_state/transaction_logic/zkapp_command/`](https://github.com/o1-labs/mina-rust/tree/develop/ledger/src/scan_state/transaction_logic/zkapp_command) - + zkApp command implementation +- [`ledger/src/scan_state/currency.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/currency.rs) - + Currency types (Fee, Nonce, Slot, Amount, Balance)