From 44b5998b105198881529b56f028fa5b0851b248b Mon Sep 17 00:00:00 2001 From: Danny Willems Date: Fri, 31 Oct 2025 23:01:49 +0800 Subject: [PATCH 1/2] Add fee transfers documentation and update sidebar Adds comprehensive fee transfer transaction documentation including: - Overview and transaction structure - Single vs. double transfer examples - Token constraints and validation - Account creation handling - Test coverage references Updates sidebar to include fee-transfers.md under Transaction types. Changes ported from mina-rust PR #1553. --- .../developers/transactions/fee-transfers.md | 164 ++++++++++++++++++ website/sidebars.ts | 1 + 2 files changed, 165 insertions(+) create mode 100644 website/docs/developers/transactions/fee-transfers.md diff --git a/website/docs/developers/transactions/fee-transfers.md b/website/docs/developers/transactions/fee-transfers.md new file mode 100644 index 000000000..6cd19a479 --- /dev/null +++ b/website/docs/developers/transactions/fee-transfers.md @@ -0,0 +1,164 @@ +--- +sidebar_position: 3 +title: Fee transfers +description: Understanding fee transfer transactions in the Mina protocol +slug: /developers/transactions/fee-transfers +--- + +# Fee transfers + +## Overview + +Fee transfers are protocol-generated transactions that distribute collected +transaction fees to block producers. Unlike user commands, fee transfers are +created automatically during block production and do not require user +signatures. + +A fee transfer consists of: + +- **Receiver(s)**: One or two block producers receiving fees +- **Fee amount(s)**: The fee amount(s) to distribute +- **Token**: Must be the default token (MINA) + +## Transaction structure + +Fee transfers use a specialized structure that supports one or two receivers: + + + +```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#L357-L357 +``` + + + +```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#L330-L334 +``` + +### Creating fee transfers + +Fee transfers are constructed using the `of_singles` method which validates +token compatibility: + + + +```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#L396-L412 +``` + +## Transaction application + +### First pass + +During the first pass (`apply_transaction_first_pass`), the fee transfer: + +1. **Validates token compatibility** + - All fees must be in the default token (MINA) + - Rejects non-default tokens + +2. **Processes single or double transfers** + - For single transfers: adds fee to receiver's balance + - For double transfers: adds respective fees to both receivers + - Creates receiver accounts if they don't exist + +3. **Deducts account creation fees** + - If receiver account doesn't exist, charges account creation fee + - Receiver gets: `fee_amount - account_creation_fee` + +**Implementation:** +`ledger/src/scan_state/transaction_logic/transaction_partially_applied.rs` + +### No fee payment + +Fee transfers do not pay fees themselves - they are protocol transactions: + +- No nonce increment +- No fee payer +- No signature required +- Cannot be submitted by users + +## Account creation + +If a receiver account doesn't exist, it is created automatically. The account +creation fee (1 MINA by default) is deducted from the fee being transferred. + +## Single vs. double transfers + +### Single transfer + +Distributes fees to one block producer. See +[test_apply_single_fee_transfer_success](https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_fee_transfer.rs#L94-L95) +for an example: + + + +```rust reference title="ledger/tests/test_transaction_logic_first_pass_fee_transfer.rs" +https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_fee_transfer.rs#L94-L95 +``` + +### Double transfer + +Distributes fees to two block producers (e.g., coinbase producer and snark work +producer). See +[test_apply_double_fee_transfer_success](https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_fee_transfer.rs#L169-L174) +for an example: + + + +```rust reference title="ledger/tests/test_transaction_logic_first_pass_fee_transfer.rs" +https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_fee_transfer.rs#L169-L174 +``` + +## Token constraints + +Fee transfers must use the default token. For double transfers, both tokens must +match. The validation is implemented in +[FeeTransfer::of_singles](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/mod.rs#L400): + + + +```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#L400-L408 +``` + +See +[test_apply_fee_transfer_incompatible_tokens](https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_fee_transfer.rs#L333-L337) +for an example creating fee transfers with incompatible tokens: + + + +```rust reference title="ledger/tests/test_transaction_logic_first_pass_fee_transfer.rs" +https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_fee_transfer.rs#L333-L337 +``` + +The validation fails with an error: + + + +```rust reference title="ledger/tests/test_transaction_logic_first_pass_fee_transfer.rs" +https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_fee_transfer.rs#L344-L346 +``` + +## Testing + +Comprehensive tests are available in +[`ledger/tests/test_transaction_logic_first_pass_fee_transfer.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_fee_transfer.rs): + +- [`test_apply_single_fee_transfer_success`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_fee_transfer.rs#L75) - + Single fee transfer to existing account +- [`test_apply_double_fee_transfer_success`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_fee_transfer.rs#L137) - + Double fee transfer to two receivers +- [`test_apply_fee_transfer_creates_account`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_fee_transfer.rs#L237) - + Fee transfer creating new account +- [`test_apply_fee_transfer_incompatible_tokens`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_fee_transfer.rs#L316) - + Token compatibility validation + +## 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) - + Fee transfer 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) - + Fee transfer application logic +- [`ledger/tests/test_transaction_logic_first_pass_fee_transfer.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/tests/test_transaction_logic_first_pass_fee_transfer.rs) - + Fee transfer tests diff --git a/website/sidebars.ts b/website/sidebars.ts index 4373da2b8..3ed4b1574 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -95,6 +95,7 @@ const sidebars: SidebarsConfig = { label: 'Transaction types', items: [ 'developers/transactions/coinbase', + 'developers/transactions/fee-transfers', ], }, ], From aaa9194f7577c0025d9005d15b57bccd724e8ce1 Mon Sep 17 00:00:00 2001 From: Danny Willems Date: Fri, 31 Oct 2025 23:07:26 +0800 Subject: [PATCH 2/2] CHANGELOG: add entry for patch 1584 --- CHANGELOG.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 74207b474..395b41000 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 structure, application logic, reward distribution, fee transfers, account creation, and comprehensive testing ([#1582](https://github.com/o1-labs/mina-rust/pull/1582)) +- **Website**: add fee transfer transaction documentation covering single and + double transfers, token constraints, account creation handling, and + comprehensive testing examples. Update OCaml references to new structured + format with commit hashes and verification dates + ([#1584](https://github.com/o1-labs/mina-rust/pull/1584)) - **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))