Skip to content

Conversation

@dannywillems
Copy link
Member

@dannywillems dannywillems commented Dec 18, 2025

Summary

  • Add a new documentation page in the developers section explaining Mina
    blockchain concepts using traditional database terminology
  • Makes documentation more accessible to developers familiar with databases
    but new to web3
  • Add the page to the Introduction section of the developers sidebar

Content overview

The page covers:

  • Core concept mappings: Ledger as KV store, accounts as records,
    transactions as write operations
  • Authentication layer: Signatures, public/private keys
  • Authorization layer: zkApps, permissions, preconditions
  • Logging and audit: Archive nodes, events, actions
  • Infrastructure: Consensus, nodes, transition frontier
  • Unique properties: Succinct verification, programmable authorization,
    decentralization

Type of Change

  • This change requires a documentation update

Testing

  • Verify page builds with make docs-build
  • Verify page appears in sidebar under Developers > Introduction
  • Review content for technical accuracy

Changelog Summary

  • Added documentation page explaining Mina as a decentralized programmable
    database for developers familiar with traditional database concepts.

Add a new page in the developers section that explains Mina blockchain
concepts using traditional database terminology. This makes the
documentation more accessible to developers familiar with databases but
new to web3.

The page covers:
- Core concept mappings (ledger as KV store, transactions as writes)
- Authentication and authorization layers
- Logging and audit capabilities (archive nodes, events)
- Infrastructure layer comparisons
- What makes Mina unique (succinct verification, programmable auth)
@dannywillems dannywillems marked this pull request as draft December 18, 2025 15:08
@github-actions
Copy link

OCaml Reference Validation Results

Repository: https://github.com/MinaProtocol/mina.git
Branch: compatible
Status: ❌ Validation failed

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: 1af70b43bda0b9b05bd6aa641200ec479c1e7b8f

Validating references...
========================
✓ VALID: crates/ledger/src/account/account.rs -> src/lib/mina_base/account.ml L:201-224
  ⚠ STALE COMMIT: fc6be4c58091c761f827c858229c2edf9519e941 (current: 1af70b43bda0b9b05bd6aa641200ec479c1e7b8f)
❌ INVALID: crates/ledger/src/scan_state/transaction_logic/for_tests.rs
   Code at L:2285-2285 differs between commit 5da42ccd72e791f164d4d200cf1ce300262873b3 and current branch
   Referenced: https://github.com/MinaProtocol/mina/blob/5da42ccd72e791f164d4d200cf1ce300262873b3/src/lib/transaction_logic/mina_transaction_logic.ml#L2285-L2285
   Current:    https://github.com/MinaProtocol/mina/blob/compatible/src/lib/transaction_logic/mina_transaction_logic.ml#L2285-L2285
❌ INVALID: crates/ledger/src/scan_state/transaction_logic/for_tests.rs
   Code at L:2351-2356 differs between commit 5da42ccd72e791f164d4d200cf1ce300262873b3 and current branch
   Referenced: https://github.com/MinaProtocol/mina/blob/5da42ccd72e791f164d4d200cf1ce300262873b3/src/lib/transaction_logic/mina_transaction_logic.ml#L2351-L2356
   Current:    https://github.com/MinaProtocol/mina/blob/compatible/src/lib/transaction_logic/mina_transaction_logic.ml#L2351-L2356
❌ INVALID: crates/ledger/src/scan_state/transaction_logic/for_tests.rs
   Code at L:2407 differs between commit 5da42ccd72e791f164d4d200cf1ce300262873b3 and current branch
   Referenced: https://github.com/MinaProtocol/mina/blob/5da42ccd72e791f164d4d200cf1ce300262873b3/src/lib/transaction_logic/mina_transaction_logic.ml#L2407-L2407
   Current:    https://github.com/MinaProtocol/mina/blob/compatible/src/lib/transaction_logic/mina_transaction_logic.ml#L2407-L2407
✓ VALID: crates/ledger/src/scan_state/transaction_logic/mod.rs -> src/lib/mina_base/transaction_status.ml L:9-51
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 1af70b43bda0b9b05bd6aa641200ec479c1e7b8f)
✓ VALID: crates/ledger/src/scan_state/transaction_logic/mod.rs -> src/lib/mina_base/transaction_status.ml L:452-454
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 1af70b43bda0b9b05bd6aa641200ec479c1e7b8f)
✓ VALID: crates/ledger/src/scan_state/transaction_logic/mod.rs -> src/lib/mina_base/with_status.ml L:6-10
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 1af70b43bda0b9b05bd6aa641200ec479c1e7b8f)
✓ VALID: crates/ledger/src/scan_state/transaction_logic/mod.rs -> src/lib/mina_base/fee_transfer.ml L:76-80
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 1af70b43bda0b9b05bd6aa641200ec479c1e7b8f)
✓ VALID: crates/ledger/src/scan_state/transaction_logic/mod.rs -> src/lib/mina_base/fee_transfer.ml L:68-69
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 1af70b43bda0b9b05bd6aa641200ec479c1e7b8f)
✓ VALID: crates/ledger/src/scan_state/transaction_logic/mod.rs -> src/lib/mina_base/coinbase.ml L:17-21
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 1af70b43bda0b9b05bd6aa641200ec479c1e7b8f)
✓ VALID: crates/ledger/src/scan_state/transaction_logic/mod.rs -> src/lib/transaction/transaction.ml L:8-11
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 1af70b43bda0b9b05bd6aa641200ec479c1e7b8f)
✓ VALID: crates/ledger/src/scan_state/transaction_logic/signed_command.rs -> src/lib/mina_base/signed_command_payload.ml L:34-48
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 1af70b43bda0b9b05bd6aa641200ec479c1e7b8f)
✓ VALID: crates/ledger/src/scan_state/transaction_logic/signed_command.rs -> src/lib/mina_base/stake_delegation.ml L:11-13
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 1af70b43bda0b9b05bd6aa641200ec479c1e7b8f)
✓ VALID: crates/ledger/src/scan_state/transaction_logic/signed_command.rs -> src/lib/mina_base/signed_command_payload.ml L:179-181
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 1af70b43bda0b9b05bd6aa641200ec479c1e7b8f)
✓ VALID: crates/ledger/src/scan_state/transaction_logic/signed_command.rs -> src/lib/mina_base/signed_command_payload.ml L:239-243
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 1af70b43bda0b9b05bd6aa641200ec479c1e7b8f)
✓ VALID: crates/ledger/src/scan_state/transaction_logic/signed_command.rs -> src/lib/mina_base/signed_command_payload.ml L:352-362
  ⚠ STALE COMMIT: 5da42ccd72e791f164d4d200cf1ce300262873b3 (current: 1af70b43bda0b9b05bd6aa641200ec479c1e7b8f)

Summary
=======
Total references found: 16
Valid references: 13
Invalid references: 3
Stale commits: 13

❌ Validation failed: 3 invalid reference(s) found

@github-actions
Copy link

⚠️ Code Reference Verification Failed

The documentation contains code references that do not match the current state of the codebase on the develop branch.

Issues Found

  • website/docs/developers/referencing-code-in-documentation.md:36 - File not found: ledger/src/scan_state/transaction_logic/valid.rs

Action Required

The code referenced in the documentation must be merged to develop before documentation can be added/modified.

Please follow this workflow:

  1. Merge the code changes to develop first (this PR or a separate code PR)
  2. Create a follow-up PR with the documentation updates that reference the merged code
  3. The verification will pass once the code is available on develop

See the documentation guidelines for more information about the two-PR workflow.

@dannywillems dannywillems marked this pull request as ready for review December 18, 2025 16:38
@dannywillems dannywillems marked this pull request as draft December 18, 2025 16:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

2 participants