@@ -398,7 +398,9 @@ pub struct FailureCollection {
398398 inner : Vec < Vec < TransactionFailure > > ,
399399}
400400
401- /// <https://github.com/MinaProtocol/mina/blob/bfd1009abdbee78979ff0343cc73a3480e862f58/src/lib/transaction_logic/mina_transaction_logic.ml#L2197C1-L2210C53>
401+ /// OCaml reference: src/lib/transaction_logic/mina_transaction_logic.ml L:2197-2210
402+ /// Commit: bfd1009abdbee78979ff0343cc73a3480e862f58
403+ /// Last verified: 2025-10-16
402404impl FailureCollection {
403405 fn empty ( ) -> Self {
404406 Self {
@@ -440,17 +442,51 @@ impl FailureCollection {
440442 }
441443}
442444
443- /// Structure of the failure status:
444- /// I. No fee transfer and coinbase transfer fails: `[[failure]]`
445- /// II. With fee transfer-
446- /// Both fee transfer and coinbase fails:
447- /// `[[failure-of-fee-transfer]; [failure-of-coinbase]]`
448- /// Fee transfer succeeds and coinbase fails:
449- /// `[[];[failure-of-coinbase]]`
450- /// Fee transfer fails and coinbase succeeds:
451- /// `[[failure-of-fee-transfer];[]]`
445+ /// Applies a coinbase transaction to the ledger.
446+ ///
447+ /// Processes the coinbase by first applying the optional fee transfer (if present),
448+ /// then applying the coinbase reward to the receiver. Updates account balances and
449+ /// timing, creates accounts if needed, and handles permission checks.
450+ ///
451+ /// # Parameters
452+ ///
453+ /// - `constraint_constants`: Protocol constants including account creation fees
454+ /// - `txn_global_slot`: Current global slot for timing validation
455+ /// - `ledger`: Mutable ledger to update
456+ /// - `coinbase`: Coinbase transaction containing receiver, amount, and optional
457+ /// fee transfer
458+ ///
459+ /// # Returns
460+ ///
461+ /// Returns [`CoinbaseApplied`] containing:
462+ /// - `coinbase`: The input coinbase with transaction status
463+ /// - `new_accounts`: Vector of newly created account IDs
464+ /// - `burned_tokens`: Amount of tokens burned from failed transfers
465+ ///
466+ /// # Errors
467+ ///
468+ /// Returns `Err` if:
469+ /// - `fee_transfer.fee` exceeds `coinbase.amount` (checked subtraction fails)
470+ /// - Burned tokens overflow when summing across transfers
471+ ///
472+ /// For protocol-level documentation and behavioral specification, see:
473+ /// <https://o1-labs.github.io/mina-rust/docs/developers/transactions/coinbase>
474+ ///
475+ /// # Tests
476+ ///
477+ /// Test coverage (in `ledger/tests/test_transaction_logic_first_pass_coinbase.rs`):
478+ ///
479+ /// - `test_apply_coinbase_without_fee_transfer`
480+ /// - `test_apply_coinbase_with_fee_transfer`
481+ /// - `test_apply_coinbase_with_fee_transfer_creates_account`
482+ /// - `test_apply_coinbase_with_fee_transfer_to_same_account`
483+ /// - `test_apply_coinbase_creates_account`
484+ ///
485+ /// # OCaml Reference
452486///
453- /// <https://github.com/MinaProtocol/mina/blob/2ee6e004ba8c6a0541056076aab22ea162f7eb3a/src/lib/transaction_logic/mina_transaction_logic.ml#L2022>
487+ /// OCaml reference: src/lib/transaction_logic/mina_transaction_logic.ml L:2074-2178
488+ /// Commit: 0063f0196d046d9d2fc8af0cea76ff30f51b49b7
489+ /// Last verified: 2025-10-16
454490pub fn apply_coinbase < L > (
455491 constraint_constants : & ConstraintConstants ,
456492 txn_global_slot : & Slot ,
@@ -649,7 +685,9 @@ where
649685 } )
650686}
651687
652- /// <https://github.com/MinaProtocol/mina/blob/2ee6e004ba8c6a0541056076aab22ea162f7eb3a/src/lib/transaction_logic/mina_transaction_logic.ml#L607>
688+ /// OCaml reference: src/lib/transaction_logic/mina_transaction_logic.ml L:607
689+ /// Commit: 2ee6e004ba8c6a0541056076aab22ea162f7eb3a
690+ /// Last verified: 2025-10-16
653691fn sub_account_creation_fee (
654692 constraint_constants : & ConstraintConstants ,
655693 action : AccountState ,
0 commit comments