Add coinbase transaction documentation

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))

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:
+
+<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic/mod.rs#L1093-L1100 -->
+
+```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:
+
+<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic/mod.rs#L548-L548 -->
+
+```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:
+
+<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic/mod.rs#L240-L243 -->
+
+```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)

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:
+
+<!-- CODE_REFERENCE: 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#L438-L442
+```
+
+<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic/mod.rs#L416-L419 -->
+
+```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:
+
+<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic/mod.rs#L452-L476 -->
+
+```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)):
+
+<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic/mod.rs#L464-L472 -->
+
+```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:
+
+<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic/transaction_partially_applied.rs#L559-L561 -->
+
+```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

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',