Skip to content

Add coinbase transaction documentation #1582

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 3 commits into
base: develop
Choose a base branch
from
Open

Add coinbase transaction documentation #1582

wants to merge 3 commits into from

Conversation

@dannywillems
Copy link
Member

@dannywillems dannywillems commented Oct 31, 2025 •
edited
Loading

Summary

This PR adds comprehensive documentation for coinbase transactions to the website, covering:

  • Transaction structure and creation
  • Application logic for first pass processing
  • Coinbase reward distribution and amounts
  • Fee transfer interactions with SNARK workers
  • Account creation handling
  • Comprehensive test coverage

The documentation includes code references, examples, and links to relevant implementation files.

@github-actions
Copy link

github-actions bot commented Oct 31, 2025 •
edited
Loading

OCaml Reference Validation Results

Repository: https://github.com/MinaProtocol/mina.git
Branch: compatible
Status: ✓ Validation passed

Click to see full validation output 
Checking OCaml references against https://github.com/MinaProtocol/mina.git (branch: compatible)
Fetching current commit from compatible...
Current OCaml commit: 142600a5fa09c31c704c952f7da315399c6082b8

Validating references...
========================
✓ VALID: ledger/src/account/account.rs -> src/lib/mina_base/account.ml L:201-224
  ⚠ STALE COMMIT: fc6be4c58091c761f827c858229c2edf9519e941 (current: 142600a5fa09c31c704c952f7da315399c6082b8)
✓ VALID: ledger/src/scan_state/transaction_logic/for_tests.rs -> src/lib/transaction_logic/mina_transaction_logic.ml L:2285-2285
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 142600a5fa09c31c704c952f7da315399c6082b8)
✓ VALID: ledger/src/scan_state/transaction_logic/for_tests.rs -> src/lib/transaction_logic/mina_transaction_logic.ml L:2351-2356
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 142600a5fa09c31c704c952f7da315399c6082b8)
✓ VALID: ledger/src/scan_state/transaction_logic/for_tests.rs -> src/lib/transaction_logic/mina_transaction_logic.ml L:2407
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 142600a5fa09c31c704c952f7da315399c6082b8)
✓ VALID: ledger/src/scan_state/transaction_logic/mod.rs -> src/lib/mina_base/transaction_status.ml L:9-51
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 142600a5fa09c31c704c952f7da315399c6082b8)
✓ VALID: ledger/src/scan_state/transaction_logic/mod.rs -> src/lib/mina_base/transaction_status.ml L:452-454
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 142600a5fa09c31c704c952f7da315399c6082b8)
✓ VALID: ledger/src/scan_state/transaction_logic/mod.rs -> src/lib/mina_base/with_status.ml L:6-10
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 142600a5fa09c31c704c952f7da315399c6082b8)
✓ VALID: ledger/src/scan_state/transaction_logic/mod.rs -> src/lib/mina_base/fee_transfer.ml L:76-80
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 142600a5fa09c31c704c952f7da315399c6082b8)
✓ VALID: ledger/src/scan_state/transaction_logic/mod.rs -> src/lib/mina_base/fee_transfer.ml L:68-69
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 142600a5fa09c31c704c952f7da315399c6082b8)
✓ VALID: ledger/src/scan_state/transaction_logic/mod.rs -> src/lib/mina_base/coinbase.ml L:17-21
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 142600a5fa09c31c704c952f7da315399c6082b8)
✓ VALID: ledger/src/scan_state/transaction_logic/mod.rs -> src/lib/transaction/transaction.ml L:8-11
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 142600a5fa09c31c704c952f7da315399c6082b8)
✓ VALID: ledger/src/scan_state/transaction_logic/signed_command.rs -> src/lib/mina_base/signed_command_payload.ml L:34-48
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 142600a5fa09c31c704c952f7da315399c6082b8)
✓ VALID: ledger/src/scan_state/transaction_logic/signed_command.rs -> src/lib/mina_base/stake_delegation.ml L:11-13
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 142600a5fa09c31c704c952f7da315399c6082b8)
✓ VALID: ledger/src/scan_state/transaction_logic/signed_command.rs -> src/lib/mina_base/signed_command_payload.ml L:179-181
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 142600a5fa09c31c704c952f7da315399c6082b8)
✓ VALID: ledger/src/scan_state/transaction_logic/signed_command.rs -> src/lib/mina_base/signed_command_payload.ml L:239-243
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 142600a5fa09c31c704c952f7da315399c6082b8)
✓ VALID: ledger/src/scan_state/transaction_logic/signed_command.rs -> src/lib/mina_base/signed_command_payload.ml L:352-362
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 142600a5fa09c31c704c952f7da315399c6082b8)

Summary
=======
Total references found: 16
Valid references: 16
Invalid references: 0
Stale commits: 16

⚠ Warning: 16 reference(s) have stale commits
Run with --update to update them automatically

@github-actions
Copy link

github-actions bot commented Oct 31, 2025 •
edited
Loading

✓ Code Reference Verification Passed

All code references in the documentation have been verified successfully!

Total references checked: 9
Valid references: 9

The documentation is in sync with the codebase on the develop branch.

richardpringle
richardpringle previously approved these changes Oct 31, 2025
View reviewed changes
Copy link
Contributor

@richardpringle richardpringle left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I'm being honest here, I didn't find these docs to be super helpful. I don't think it hurts merging them, but they are not concise enough. They don't really help me navigate the code. And all link should point somewhere that lead to a better understanding (like the docs.rs style page). With that said, I think it's fine to merge this as it's probably better than no docs, but only by a little.

website/docs/developers/transactions.md
<!-- 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
Copy link
Contributor

@richardpringle richardpringle Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be a permalink. If/when this becomes outdated, it's easier to figure out the changes if it's a permalink.

I see that there are others links in this PR too, same does for them.

Copy link
Contributor

@richardpringle richardpringle Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, I don't think this renders the way you want it to.

Copy link
Member Author

@dannywillems dannywillems Nov 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does render as I want it to:

Image

website/docs/developers/transactions.md
- 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)
Copy link
Contributor

@richardpringle richardpringle Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be better if this link pointed to the rendered inline docs which I do believe we publish, right?

website/docs/developers/transactions/coinbase.md
Comment on lines +1 to +6
---
sidebar_position: 4
title: Coinbase rewards
description: Understanding coinbase reward transactions in the Mina protocol
slug: /developers/transactions/coinbase
---
Copy link
Contributor

@richardpringle richardpringle Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is this?

@dannywillems
Add coinbase transaction documentation
892922a 
Add comprehensive documentation for coinbase transactions covering
structure, application logic, reward distribution, fee transfers,
account creation, and testing.

CHANGELOG: add entry for patch 1553
@dannywillems
CHANGELOG: add entry for patch 1582
1aa335b
@dannywillems
Update transactions.md from PR 1553 with link fixes
ecd058b 
Replace the initial transactions.md with the comprehensive version from
PR 1553. Convert undefined transaction type links to section anchors to
prevent broken links until those documentation pages are created.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@richardpringle richardpringle richardpringle left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

Rust node
Status: No status

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@dannywillems @richardpringle