|
| 1 | +# OCaml Node Coordination for Rust Development |
| 2 | + |
| 3 | +This document outlines features and improvements that the OCaml node could implement to enhance Rust node development and testing workflows, based on limitations and needs identified in the handover documentation. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The OpenMina (Rust) and OCaml Mina implementations need to work together in several key areas: |
| 8 | +- **Cross-implementation testing** for protocol compatibility |
| 9 | +- **Circuit generation** workflows that rely on OCaml implementation |
| 10 | +- **Fuzzing infrastructure** for differential testing |
| 11 | +- **P2P protocol evolution** toward unified networking |
| 12 | +- **Development workflows** that involve both implementations |
| 13 | + |
| 14 | +This document consolidates all identified areas where OCaml improvements would benefit Rust development. |
| 15 | + |
| 16 | +## Maintenance Burden Coordination |
| 17 | + |
| 18 | +### Circuit Generation Branch |
| 19 | + |
| 20 | +OpenMina's circuit generation process requires launching a custom build of the OCaml node from the `utils/dump-extra-circuit-data-devnet301` branch, which produces circuit cache data in `/tmp/coda_cache_dir` and dumps both usual circuit data plus extra data specifically required by OpenMina. |
| 21 | + |
| 22 | +Without mainline integration, the OpenMina team must manually maintain this branch, making this a high priority coordination need. The branch requires significant cleanup before integration into mainline Mina. When integrated, the circuit generation functionality could be added as a node subcommand that exports the required circuit data without starting the full node. |
| 23 | + |
| 24 | +### Fuzzer Branch |
| 25 | + |
| 26 | +The `openmina/fuzzer` branch contains the OCaml transaction fuzzer implementation used for differential testing between OCaml and Rust implementations. Like the circuit generation branch, this requires manual maintenance by the OpenMina team when not integrated into mainline Mina. While lower priority than circuit generation, integration would reduce maintenance overhead and streamline the fuzzing setup process. |
| 27 | + |
| 28 | +For detailed information about the fuzzing infrastructure and setup, see [Fuzzing Infrastructure](fuzzing.md). |
| 29 | + |
| 30 | +## Cross-Implementation Testing Challenges |
| 31 | + |
| 32 | +Cross-implementation testing between OCaml and Rust nodes faces several challenges due to architectural differences. The OCaml node was not designed to integrate with the Rust testing framework: |
| 33 | + |
| 34 | +- **Time Control**: Cannot be controlled via test framework time advancement |
| 35 | +- **State Inspection**: Cannot be inspected by Rust testing infrastructure |
| 36 | +- **Network Control**: Cannot manually control P2P connections from test framework |
| 37 | +- **Behavioral Control**: No control over internal execution flow from test framework |
| 38 | + |
| 39 | +These differences restrict the types of cross-implementation testing that can be performed. Currently, OCaml nodes can be used for basic interoperability validation rather than comprehensive protocol behavior testing. Addressing these differences through coordination with the OCaml Mina team could enable more thorough cross-implementation testing and better validation of protocol compatibility between the implementations. |
| 40 | + |
| 41 | +For detailed information about these limitations and potential improvements, see [Testing Infrastructure - OCaml Node Limitations](testing-infrastructure.md#ocaml-node-limitations). |
| 42 | + |
| 43 | +## Shared Infrastructure Dependencies |
| 44 | + |
| 45 | +### P2P Evolution |
| 46 | + |
| 47 | +The documented vision includes replacing the current Golang `libp2p_helper` with a Rust implementation that reuses OpenMina's P2P code, creating a unified networking layer across all Mina implementations. |
| 48 | + |
| 49 | +For detailed information about the P2P evolution plan and coordination requirements, see [P2P Evolution Plan](p2p-evolution.md). |
| 50 | + |
| 51 | +### Archive Service Integration |
| 52 | + |
| 53 | +OpenMina uses the same archive node helper processes as the OCaml node. Any incompatible changes to the archive interface would require coordinated updates to ensure both implementations continue to work with the shared archive infrastructure. |
| 54 | + |
| 55 | +## Protocol Compatibility Coordination |
| 56 | + |
| 57 | +### Hardfork Compatibility |
| 58 | + |
| 59 | +An OCaml implementation for automatic hardfork handling is currently in progress, and the Rust node needs to implement compatible behavior. Without coordination, incompatible hardfork implementations could lead to network splits where OCaml and Rust nodes follow different protocol rules, breaking consensus and network unity. |
| 60 | + |
| 61 | +Coordination is needed to ensure both implementations handle hardforks identically and maintain network compatibility during protocol upgrades. |
| 62 | + |
| 63 | +## Related Documentation |
| 64 | + |
| 65 | +- [Testing Infrastructure](testing-infrastructure.md) - OCaml node limitations in testing |
| 66 | +- [P2P Evolution Plan](p2p-evolution.md) - Unified P2P layer vision |
| 67 | +- [Fuzzing Infrastructure](fuzzing.md) - Current fuzzing setup and limitations |
| 68 | +- [Circuits](circuits.md) - Circuit generation process dependencies |
| 69 | +- [Mainnet Readiness](mainnet-readiness.md) - Cross-implementation compatibility requirements |
0 commit comments