Update OCaml references in transaction_partially_applied.rs

CHANGELOG.md

@@ -19,6 +19,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))

ledger/src/scan_state/transaction_logic/transaction_partially_applied.rs

@@ -398,7 +398,9 @@ pub struct FailureCollection {
     inner: Vec<Vec<TransactionFailure>>,
 }
 
-/// <https://github.com/MinaProtocol/mina/blob/bfd1009abdbee78979ff0343cc73a3480e862f58/src/lib/transaction_logic/mina_transaction_logic.ml#L2197C1-L2210C53>
+/// OCaml reference: src/lib/transaction_logic/mina_transaction_logic.ml L:2197-2210
+/// Commit: bfd1009abdbee78979ff0343cc73a3480e862f58
+/// Last verified: 2025-10-16
 impl FailureCollection {
     fn empty() -> Self {
         Self {
@@ -440,17 +442,51 @@ impl FailureCollection {
     }
 }
 
-/// Structure of the failure status:
-///  I. No fee transfer and coinbase transfer fails: `[[failure]]`
-///  II. With fee transfer-
-///   Both fee transfer and coinbase fails:
-///     `[[failure-of-fee-transfer]; [failure-of-coinbase]]`
-///   Fee transfer succeeds and coinbase fails:
-///     `[[];[failure-of-coinbase]]`
-///   Fee transfer fails and coinbase succeeds:
-///     `[[failure-of-fee-transfer];[]]`
+/// Applies a coinbase transaction to the ledger.
+///
+/// Processes the coinbase by first applying the optional fee transfer (if present),
+/// then applying the coinbase reward to the receiver. Updates account balances and
+/// timing, creates accounts if needed, and handles permission checks.
+///
+/// # Parameters
+///
+/// - `constraint_constants`: Protocol constants including account creation fees
+/// - `txn_global_slot`: Current global slot for timing validation
+/// - `ledger`: Mutable ledger to update
+/// - `coinbase`: Coinbase transaction containing receiver, amount, and optional
+///   fee transfer
+///
+/// # Returns
+///
+/// Returns [`CoinbaseApplied`] containing:
+/// - `coinbase`: The input coinbase with transaction status
+/// - `new_accounts`: Vector of newly created account IDs
+/// - `burned_tokens`: Amount of tokens burned from failed transfers
+///
+/// # Errors
+///
+/// Returns `Err` if:
+/// - `fee_transfer.fee` exceeds `coinbase.amount` (checked subtraction fails)
+/// - Burned tokens overflow when summing across transfers
+///
+/// For protocol-level documentation and behavioral specification, see:
+/// <https://o1-labs.github.io/mina-rust/docs/developers/transactions/coinbase>
+///
+/// # Tests
+///
+/// Test coverage (in `ledger/tests/test_transaction_logic_first_pass_coinbase.rs`):
+///
+/// - `test_apply_coinbase_without_fee_transfer`
+/// - `test_apply_coinbase_with_fee_transfer`
+/// - `test_apply_coinbase_with_fee_transfer_creates_account`
+/// - `test_apply_coinbase_with_fee_transfer_to_same_account`
+/// - `test_apply_coinbase_creates_account`
+///
+/// # OCaml Reference
 ///
-/// <https://github.com/MinaProtocol/mina/blob/2ee6e004ba8c6a0541056076aab22ea162f7eb3a/src/lib/transaction_logic/mina_transaction_logic.ml#L2022>
+/// OCaml reference: src/lib/transaction_logic/mina_transaction_logic.ml L:2074-2178
+/// Commit: 0063f0196d046d9d2fc8af0cea76ff30f51b49b7
+/// Last verified: 2025-10-16
 pub fn apply_coinbase<L>(
     constraint_constants: &ConstraintConstants,
     txn_global_slot: &Slot,
@@ -649,7 +685,9 @@ where
     })
 }
 
-/// <https://github.com/MinaProtocol/mina/blob/2ee6e004ba8c6a0541056076aab22ea162f7eb3a/src/lib/transaction_logic/mina_transaction_logic.ml#L607>
+/// OCaml reference: src/lib/transaction_logic/mina_transaction_logic.ml L:607
+/// Commit: 2ee6e004ba8c6a0541056076aab22ea162f7eb3a
+/// Last verified: 2025-10-16
 fn sub_account_creation_fee(
     constraint_constants: &ConstraintConstants,
     action: AccountState,

website/docs/developers/transactions.md

@@ -0,0 +1,185 @@
+---
+sidebar_position: 5
+title: Transactions
+description: Understanding transaction types in the Mina protocol implementation
+slug: /developers/transactions
+---
+
+# Transactions
+
+## 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](#user-initiated-transactions)** are transactions submitted and
+signed by users:
+
+- **[Payment transactions](#user-initiated-transactions)** - Transfer MINA
+  tokens between accounts
+- **[Stake delegation](#user-initiated-transactions)** - Delegate stake to block
+  producers
+- **[zkApp commands](#user-initiated-transactions)** - Execute complex
+  multi-account zero-knowledge operations
+
+### Protocol Transactions
+
+**Protocol transactions** (also called **system transactions**) are generated
+automatically by the system:
+
+- **[Fee transfers](#protocol-transactions)** - 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)