OCaml reference tracking

This document describes the system for tracking correspondence between Rust code in this repository and the original OCaml implementation in the Mina Protocol repository.

Overview

As mina-rust is a reimplementation of the Mina OCaml client, we maintain inline comments that reference the corresponding OCaml code. This helps developers:

1. Understand the original implementation context
2. Verify that the Rust implementation matches the OCaml behavior
3. Track changes in the OCaml codebase that may require updates in Rust

Comment format

OCaml references are added as doc comments directly above the Rust type or function:

/// OCaml reference: src/lib/mina_base/transaction_status.ml L:9-113
/// Commit: 55582d249cdb225f722dbbb3b1420ce7570d501f
/// Last verified: 2025-10-08
pub enum TransactionFailure {
    // ...
}

Format specification

• Line 1: /// OCaml reference: <path> L:<start>-<end>
  • <path>: Path to the OCaml file relative to the Mina repository root
  • L:<start>-<end>: Line range in the OCaml file (optional but recommended)
• Line 2: /// Commit: <commit-hash>
  • Full commit hash from the Mina repository
• Line 3: /// Last verified: <YYYY-MM-DD>
  • Date when the reference was last verified to be accurate

Validation script

The .github/scripts/check-ocaml-refs.sh script validates all OCaml references:

# Validate against compatible branch (default)
./.github/scripts/check-ocaml-refs.sh

# Validate against a specific branch
./.github/scripts/check-ocaml-refs.sh --branch develop

# Validate against a specific repository
./.github/scripts/check-ocaml-refs.sh --repo https://github.com/MinaProtocol/mina.git --branch develop

# Automatically update stale commit hashes
./.github/scripts/check-ocaml-refs.sh --update

What the script checks

1. File existence: Verifies the OCaml file exists at the specified path
2. Line ranges: Validates that line ranges don't exceed the file length
3. Code consistency: Verifies that the code at the referenced commit matches the code on the current branch (ensures the reference is still accurate)
4. Commit staleness: Checks if the commit hash matches the current HEAD

Exit codes

• 0: All references are valid or only stale commits (warning)
• 1: Invalid references found (missing files or invalid line ranges)

Automated verification

A GitHub Actions workflow runs weekly to:

1. Validate all OCaml references against the latest compatible branch
2. Automatically update stale commit hashes and verification dates
3. Create a pull request with the updates

The workflow can also be triggered manually via the Actions tab.

Adding new references

When implementing new features from the OCaml codebase:

1. Add the OCaml reference comment above your Rust type/function
2. Use the current commit hash from the Mina repository
3. Set the verification date to today
4. Include line ranges to make it easy to find the exact code

Example:

/// OCaml reference: src/lib/mina_base/fee_transfer.ml L:19-45
/// Commit: 55582d249cdb225f722dbbb3b1420ce7570d501f
/// Last verified: 2025-10-08
#[derive(Debug, Clone, PartialEq)]
pub struct SingleFeeTransfer {
    pub receiver_pk: CompressedPubKey,
    pub fee: Fee,
    pub fee_token: TokenId,
}

Finding the correct line range

To find the line range for an OCaml reference:

1. Navigate to the file in the Mina repository
2. Find the relevant type or function definition
3. Note the starting and ending line numbers
4. Use format L:<start>-<end>

For single-line references, use the same number: L:42-42

Best practices

1. Be specific: Include line ranges to point to exact definitions
2. Verify regularly: Run the validation script before committing
3. Update when needed: If you update Rust code based on OCaml changes, update the commit hash and date
4. Document differences: If the Rust implementation intentionally differs, add a note explaining why

Example references

See ledger/src/scan_state/transaction_logic/mod.rs for examples of properly formatted OCaml references.