Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
([#1269](https://github.com/o1-labs/openmina/pull/1269/)).
- **CI**: set fail-fast to false to prevent cancellation of other jobs
([#1305](https://github.com/o1-labs/openmina/pull/1305))
- **Website**: (temporary) new design, for a first release and rename OpenMina
to "the Mina Russt node"
([#1312](https://github.com/o1-labs/openmina/pull/1312)).

### Fixed

Expand Down
9 changes: 5 additions & 4 deletions website/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# OpenMina Documentation Website
# Mina Rust Node Documentation Website

This directory contains the Docusaurus-based documentation website for OpenMina.
This directory contains the Docusaurus-based documentation website for the Mina
Rust Node.

## Quick Start

Expand Down Expand Up @@ -37,7 +38,7 @@ cd website && npm run serve

The documentation is organized around three main user personas:

- **Node Runners** (`docs/node-runners/`) - Installation, configuration, and
- **Node Operators** (`docs/node-operators/`) - Installation, configuration, and
operation guides
- **Developers** (`docs/developers/`) - Architecture, codebase understanding,
and contribution guides
Expand All @@ -55,7 +56,7 @@ The documentation is organized around three main user personas:

### New Pages

1. Create markdown files in the appropriate directory (`docs/node-runners/`,
1. Create markdown files in the appropriate directory (`docs/node-operators/`,
`docs/developers/`, or `docs/researchers/`)
2. Add frontmatter with title, description, and sidebar position:
```yaml
Expand Down
16 changes: 8 additions & 8 deletions website/docs/developers/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,22 +2,22 @@
sidebar_position: 1
title: Architecture Overview
description:
Understand OpenMina's Redux-style state machine architecture and design
principles
Understand the Mina Rust Node's Redux-style state machine architecture and
design principles
slug: /developers/architecture
---

# OpenMina Architecture
# Mina Rust Node Architecture

OpenMina follows a Redux-style state machine architecture for predictable,
debuggable behavior. This design ensures that all state changes are traceable
and the system behavior is deterministic.
The Mina Rust Node follows a Redux-style state machine architecture for
predictable, debuggable behavior. This design ensures that all state changes are
traceable and the system behavior is deterministic.

## Core Principles

### State Machine Pattern

OpenMina implements Redux principles adapted for a blockchain node:
The Mina Rust Node implements Redux principles adapted for a blockchain node:

- **State** - Centralized, immutable data structure representing the entire node
state
Expand All @@ -29,7 +29,7 @@ OpenMina implements Redux principles adapted for a blockchain node:

### Predictable State Management

Every state change in OpenMina follows the same pattern:
Every state change in the Mina Rust Node follows the same pattern:

```rust
// 1. Action is dispatched
Expand Down
24 changes: 12 additions & 12 deletions website/docs/developers/getting-started.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,8 @@ import BuildSpecializedSh from "!!raw-loader!./scripts/setup/build-specialized.s
import FormatAndLintSh from "!!raw-loader!./scripts/setup/format-and-lint.sh";
import NixDevelop from "!!raw-loader!./scripts/setup/nix-develop.sh";

Welcome to OpenMina development! This guide will help you set up your
development environment and build OpenMina from source.
Welcome to Mina Rust Node development! This guide will help you set up your
development environment and build the Mina Rust Node from source.

## Prerequisites

Expand Down Expand Up @@ -57,8 +57,8 @@ development environment and build OpenMina from source.

#### 2. Rust Toolchain

OpenMina requires both stable and nightly Rust toolchains, plus additional tools
for development:
The Mina Rust Node requires both stable and nightly Rust toolchains, plus
additional tools for development:

<CodeBlock language="bash">{InstallRustSh}</CodeBlock>

Expand Down Expand Up @@ -111,7 +111,7 @@ to install the dependencies automatically and enter the shell:

<CodeBlock language="bash">{NixDevelop}</CodeBlock>

## Clone and Build OpenMina
## Clone and Build the Mina Rust Node

### 1. Clone the Repository and Build

Expand All @@ -136,7 +136,7 @@ environment.

### Code Quality and Formatting

OpenMina maintains strict code quality standards:
The Mina Rust Node maintains strict code quality standards:

<CodeBlock language="bash">{FormatAndLintSh}</CodeBlock>

Expand Down Expand Up @@ -196,11 +196,11 @@ export PG_DB="openmina_archive"

## Architecture Overview

For detailed information about OpenMina's architecture, Redux-style state
machine pattern, and component organization, please see the
For detailed information about the Mina Rust Node's architecture, Redux-style
state machine pattern, and component organization, please see the
[Architecture Documentation](./architecture.md).

## Running OpenMina
## Running the Mina Rust Node

### Basic Node

Expand Down Expand Up @@ -234,7 +234,7 @@ make docs-serve

### Logging

OpenMina uses structured logging with different levels:
The Mina Rust Node uses structured logging with different levels:

```bash
# Set log level
Expand All @@ -257,7 +257,7 @@ npm start

### Testing Framework

OpenMina includes a comprehensive testing framework:
The Mina Rust Node includes a comprehensive testing framework:

```bash
# Build testing binary
Expand Down Expand Up @@ -290,4 +290,4 @@ make build-testing
- **API Docs**:
[Rust Documentation](https://o1-labs.github.io/openmina/api-docs/)

Welcome to the OpenMina development community! 🎉
Welcome to the Mina Rust Node development community! 🎉
21 changes: 11 additions & 10 deletions website/docs/developers/libp2p.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ integrity. Without a P2P network, nodes in the Mina blockchain would be isolated
and unable to exchange vital information, leading to fragmentation and
compromising the blockchain's trustless nature.

OpenMina implements a LibP2P networking stack to ensure compatibility with
The Rust node implements a LibP2P networking stack to ensure compatibility with
existing OCaml Mina nodes while providing a foundation for the transition to
WebRTC-based communication between Rust nodes.

Expand Down Expand Up @@ -47,7 +47,7 @@ easier to manage and debug.

![LibP2P Stack Layers](https://github.com/openmina/openmina/assets/60480123/25bb08e8-d877-42b6-9c1f-b2ce29b14520)

_Above: A simplified overview of the OpenMina LibP2P networking stack. The
_Above: A simplified overview of the Rust node LibP2P networking stack. The
abstraction is in ascending order, i.e. the layers at the top have more
abstraction than the layers at the bottom._

Expand Down Expand Up @@ -87,8 +87,8 @@ Mina nodes use the following RPCs:
### Overview

The P2P layer enables nodes in the Mina network to discover and connect with
each other. OpenMina nodes must be able to connect to peers, both other OpenMina
nodes (written in Rust) as well as native Mina nodes (written in OCaml).
each other. Rust nodes must be able to connect to peers, both other Rust nodes
(written in Rust) as well as native Mina nodes (written in OCaml).

To achieve this compatibility, we implement peer discovery via Kademlia as part
of our LibP2P networking stack. Previously, we used the RPC `get_initial_peers`
Expand Down Expand Up @@ -273,13 +273,14 @@ sense that it is backwards-compatible. For example, since multiple transports
are supported, we can change `tcp` to `udp`, and the address will still be
readable and valid.

## Integration with OpenMina
## Integration with the Rust Node

The LibP2P implementation in OpenMina serves as a compatibility layer, enabling
communication between:
The LibP2P implementation in the Mina Rust Node serves as a compatibility layer,
enabling communication between:

- **OCaml Mina nodes** ↔ **Rust OpenMina nodes** (via LibP2P)
- **Rust OpenMina nodes** ↔ **Rust OpenMina nodes** (preferably via WebRTC)
- **OCaml Mina nodes** ↔ **Mina Rust Node instances** (via LibP2P)
- **Mina Rust Node instances** ↔ **Mina Rust Node instances** (preferably via
WebRTC)

This dual-transport approach allows for gradual migration from the existing
OCaml implementation to the new Rust implementation while maintaining network
Expand All @@ -291,4 +292,4 @@ connectivity and compatibility.
design goals
- [WebRTC Implementation](webrtc) - WebRTC transport layer for Rust-to-Rust
communication
- [Architecture Overview](architecture) - Overall OpenMina architecture
- [Architecture Overview](architecture) - Overall Rust node architecture
35 changes: 19 additions & 16 deletions website/docs/developers/p2p-networking.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,22 +2,23 @@
sidebar_position: 4
title: P2P Networking Overview
description:
Comprehensive guide to OpenMina's peer-to-peer networking implementation
Comprehensive guide to the Mina Rust Node's peer-to-peer networking
implementation
slug: /developers/p2p-networking
---

# P2P Networking in OpenMina
# P2P Networking in the Mina Rust Node

This document provides a comprehensive overview of OpenMina's peer-to-peer
networking implementation, covering the design goals, architecture, and key
features that enable secure, scalable, and decentralized communication.
This document provides a comprehensive overview of the Mina Rust Node's
peer-to-peer networking implementation, covering the design goals, architecture,
and key features that enable secure, scalable, and decentralized communication.

## Design Goals

In blockchain networks, particularly in Mina, **security**,
**decentralization**, **scalability**, and **eventual consistency** (in that
order) are crucial. OpenMina's P2P design achieves these goals while building on
Mina Protocol's existing architecture.
order) are crucial. The Mina Rust Node's P2P design achieves these goals while
building on Mina Protocol's existing architecture.

### Security

Expand Down Expand Up @@ -58,8 +59,8 @@ transaction/snark pools) without crude rebroadcasts.

## Transport Layer

OpenMina uses WebRTC as the primary transport protocol for peer-to-peer
communication. WebRTC provides several advantages for security and
The Mina Rust Node uses WebRTC as the primary transport protocol for
peer-to-peer communication. WebRTC provides several advantages for security and
decentralization:

- **NAT Traversal**: Built-in support for connecting peers behind NAT routers
Expand All @@ -84,7 +85,7 @@ from:

### Long Polling Approach

OpenMina implements a poll-based approach resembling
The Mina Rust Node implements a poll-based approach resembling
[long polling](https://www.pubnub.com/guides/long-polling/):

**Core Principle**: Instead of peers flooding with messages, recipients must
Expand All @@ -109,7 +110,8 @@ reason about peer state and adjust messages accordingly.
### Connection Establishment

WebRTC connections require exchanging **Offer** and **Answer** messages through
a process called **Signaling**. OpenMina supports multiple signaling methods:
a process called **Signaling**. The Mina Rust Node supports multiple signaling
methods:

#### HTTP API Signaling

Expand All @@ -129,7 +131,7 @@ a process called **Signaling**. OpenMina supports multiple signaling methods:

### Communication Channels

OpenMina uses different
The Mina Rust Node uses different
[WebRTC DataChannels](https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel)
for each protocol, providing isolation and optimized handling:

Expand All @@ -152,7 +154,7 @@ sending a response, maintaining the poll-based architecture.

### Efficient Pool Propagation

OpenMina achieves scalable, eventually consistent, and efficient pool
The Mina Rust Node achieves scalable, eventually consistent, and efficient pool
propagation by leveraging the poll-based approach:

#### Consistency Strategy
Expand Down Expand Up @@ -180,12 +182,13 @@ efficiently tracks sent messages:

## OCaml Node Compatibility

For compatibility with existing OCaml nodes, OpenMina includes a
For compatibility with existing OCaml nodes, the Mina Rust Node includes a
[libp2p implementation](libp2p):

- **Inter-Implementation Communication**: OCaml ↔ Rust via LibP2P
- **Intra-Implementation Communication**: Rust ↔ Rust via WebRTC
- **Gradual Migration**: Enables smooth transition as more nodes adopt OpenMina
- **Gradual Migration**: Enables smooth transition as more nodes adopt the Mina
Rust Node

## Future Enhancements

Expand Down Expand Up @@ -219,5 +222,5 @@ increases propagation speed across the network.

- [WebRTC Implementation](webrtc) - Detailed WebRTC transport layer
documentation
- [Architecture Overview](architecture) - Overall OpenMina architecture
- [Architecture Overview](architecture) - Overall Mina Rust Node architecture
- [Getting Started](getting-started) - Development environment setup
2 changes: 1 addition & 1 deletion website/docs/developers/scripts/setup/clone-and-build.sh
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,5 @@ echo "Downloading required circuits..."
make download-circuits

# Build in debug mode (faster compilation, slower runtime)
echo "Building OpenMina in debug mode..."
echo "Building the Mina Rust Node in debug mode..."
make build
19 changes: 10 additions & 9 deletions website/docs/developers/updating-ocaml-node.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,10 @@ sidebar_position: 4
# Updating the OCaml Node

When a new Mina Protocol release becomes available, you need to update the OCaml
node references in OpenMina. The OCaml node releases are used to verify that the
current OpenMina version maintains compatibility with the official Mina Protocol
implementation through end-to-end and scenario testing. This guide walks through
the process based on the workflow used in
node references in the Mina Rust Node. The OCaml node releases are used to
verify that the current Mina Rust Node version maintains compatibility with the
official Mina Protocol implementation through end-to-end and scenario testing.
This guide walks through the process based on the workflow used in
[PR #1236](https://github.com/o1-labs/openmina/pull/1236).

## 1. Check for New Releases
Expand All @@ -25,7 +25,8 @@ configuration files. You'll need:

## 2. Automated Update with Script

OpenMina provides an automation script to handle the bulk of the update process:
The Mina Rust Node provides an automation script to handle the bulk of the
update process:

```bash
./website/docs/developers/scripts/update-ocaml-node.sh <old_hash> <new_hash> <old_version> <new_version>
Expand Down Expand Up @@ -71,8 +72,8 @@ After making updates:
1. **Build and Test**: Run the test suite to ensure compatibility
2. **Check References**: Verify all version references are updated consistently
3. **Configuration Validation**: Ensure new config files are properly referenced
4. **End-to-End Testing**: Run scenario tests to verify OpenMina compatibility
with the updated OCaml node
4. **End-to-End Testing**: Run scenario tests to verify Mina Rust Node
compatibility with the updated OCaml node
5. **CI Pipeline**: Verify that automated testing passes with new versions

## 5. Commit Structure
Expand All @@ -88,6 +89,6 @@ Following the pattern from commit
## Related Resources

- [Mina Protocol Releases](https://github.com/MinaProtocol/mina/releases/)
- [OpenMina Architecture Documentation](./architecture.md)
- [Mina Rust Node Architecture Documentation](./architecture.md)
- [Example PR #1236](https://github.com/o1-labs/openmina/pull/1236)
- [Node Runners Guide](../node-runners/getting-started.md)
- [Node Operators Guide](../node-operators/getting-started.md)
Loading
Loading