diff --git a/CHANGELOG.md b/CHANGELOG.md index 0d320426e..932c77654 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 + ([#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)) 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) 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',