Merge pull request #839 from openmina/guides

docs: Added Block Producer Guide, Cleaned up other guides

Author: tizoc

README.md

@@ -1,4 +1,3 @@
-
 # The Open Mina Node
 
 ## With the Rust-based Open Mina node, you can produce, validate and apply blocks
@@ -7,15 +6,17 @@
 
 ## Run the Block Producer
 
-Once you have completed the [pre-requisites](https://github.com/openmina/openmina/blob/main/docs/producer-demo.md#prerequisites) for your operating system, follow these steps:
+Once you have completed the [pre-requisites](./docs/docker-installation.md) for your operating system, follow these steps:
 
 ### Setup Option 1: Download Docker Compose Files from the Release
 
 1. **Download the Docker Compose files:**
+
    - Go to the [Releases page](https://github.com/openmina/openmina/releases) of this repository.
    - Download the latest `openmina-vX.Y.Z-docker-compose.zip` (or `.tar.gz`) file corresponding to the release version (available since v0.8.0).
 
 2. **Extract the files:**
+
    - Unzip or untar the downloaded file:
      ```bash
      unzip openmina-vX.Y.Z-docker-compose.zip
@@ -34,6 +35,7 @@ Once you have completed the [pre-requisites](https://github.com/openmina/openmin
 ### Setup Option 2: Clone the Repository
 
 1. **Clone this repository:**
+
    ```bash
    git clone https://github.com/openmina/openmina.git
    ```
@@ -46,9 +48,10 @@ Once you have completed the [pre-requisites](https://github.com/openmina/openmin
 ### Launch
 
 **Run the following command to start the demo:**
-   ```bash
-   docker compose -f docker-compose.local.producers.yml up --pull always --force-recreate
-   ```
+
+```bash
+docker compose -f docker-compose.local.producers.yml up --pull always --force-recreate
+```
 
 And finally:
 
@@ -66,18 +69,16 @@ In the design of the Open Mina node, we are utilizing much of the same logic as
 
 ## Overview of the Node’s current functionalities
 
-
-| Current functionalities | In Development | Future Plans |  
-|---------------------------------------------------------------------------------------------|--------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|  
-| ☑ **Produce and prove blocks** (with and without transactions). | ☐ Receiving and broadcasting transactions from/into the transaction pool. | ☐ Direct transfer of MINA funds using Webnode |  
-| ☑ **Produce SNARK proofs** for transactions. | ☐ A block replayer that uses data from the archive nodes| ☐ O1JS support for Webnode.|  
-| ☑ **Connect to the network** and sync up to the best tip block | | |  
-| ☑ **Validate and apply new blocks** and transactions to update consensus and ledger state. | | |  
-| ☑ **Broadcast messages**: blocks, SNARK pool | | |
+| Current functionalities                                                                          | In Development                                                                  | Future Plans                                        |
+| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | --------------------------------------------------- |
+| ☑ **Produce and prove blocks** (with and without transactions).                            | ☐ Receiving and broadcasting transactions from/into the transaction pool. | ☐ Direct transfer of MINA funds using Webnode |
+| ☑ **Produce SNARK proofs** for transactions.                                               | ☐ A block replayer that uses data from the archive nodes                  | ☐ O1JS support for Webnode.                   |
+| ☑ **Connect to the network** and sync up to the best tip block                             |                                                                                 |                                                     |
+| ☑ **Validate and apply new blocks** and transactions to update consensus and ledger state. |                                                                                 |                                                     |
+| ☑ **Broadcast messages**: blocks, SNARK pool                                               |                                                                                 |                                                     |
 
 Please note that receiving and broadcasting transactions from/into the transaction pool is already possible, but is still an early alpha version and needs more work.
 
-
 ## Updates to the Front End
 
 We've added two new pages to the node's front end:
@@ -86,21 +87,19 @@ We've added two new pages to the node's front end:
 
 ![image](https://github.com/user-attachments/assets/a66b993d-5a9f-42a7-a946-f19f6e18e6ab)
 
-
 Shows a list of the transactions from the pool and a side panel detail.
 
 ### Benchmarks
 
 ![image](https://github.com/user-attachments/assets/5aa9f0b8-2f53-4c2e-8b60-ed2ccaa7335b)
 
 The benchmarks page helps us to send transactions. The transactions are signed in the front end by the Mina signer.
-Every user can send transactions and they can see in the mempool whether the transactions were sent by their node. 
+Every user can send transactions and they can see in the mempool whether the transactions were sent by their node.
 
 ## Launch the block producer demo
 
 Run the Open Mina block producer node by following this [guide](https://github.com/openmina/openmina/blob/main/docs/producer-demo.md).
 
-
 ## How to launch the node (with Docker compose):
 
 From the directory containing the Docker Compose files (either the root of the cloned repository or the directory where the released Docker Compose files were extracted):
@@ -113,7 +112,6 @@ Then visit http://localhost:8070 in your browser.
 
 ![image](https://github.com/user-attachments/assets/b8e10a12-ec96-44a9-951a-ef0c1b291428)
 
-
 By default, `docker compose up` will use the latest node and frontend images available (tagged with `latest`), but specific versions can be selected by using the `OPENMINA_TAG` and `OPENMINA_FRONTEND_TAG` variables.
 
 ## How to launch the node (without Docker compose):
@@ -133,7 +131,7 @@ Ubuntu or Debian-based Linux distribution with the following packages installed:
 
 Example (debian-based):
 
-``` sh
+```sh
 # Either using "sudo" or as the "root" user
 sudo apt install curl git libssl-dev pkg-config protobuf-compiler build-essential
 ```
@@ -146,7 +144,7 @@ If you have not yet installed homebrew:
 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 ```
 
-``` sh
+```sh
 brew install curl git openssl pkg-config protobuf gcc make
 ```
 
@@ -175,33 +173,40 @@ cargo run --release -p cli node
 ### 1. Node.js v20.11.1
 
 #### MacOS
+
 ```bash
 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 brew install [email protected]
 ```
 
 #### Linux
+
 ```bash
 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
 source ~/.bashrc
 nvm install 20.11.1
 ```
 
 #### Windows
+
 Download [Node.js v20.11.1](https://nodejs.org/) from the official website, open the installer and follow the prompts to complete the installation.
 
 ### 2. Angular CLI v16.2.0
+
 ```bash
 npm install -g @angular/[email protected]
 ```
 
 ### 3. Installation
+
 Open a terminal and navigate to this project's root directory
 
 ```bash
 cd PROJECT_LOCATION/openmina/frontend
 ```
+
 Install the dependencies
+
 ```bash
 npm install
 ```
@@ -226,10 +231,8 @@ npm start
 - [cli/](cli) - OpenMina cli.
 - [frontend/](frontend) - OpenMina frontend.
 
-
 [Details regarding architecture](ARCHITECTURE.md)
 
-
 ## The Open Mina Documentation
 
 - [Why we are developing Open Mina](docs/why-openmina.md)
@@ -255,12 +258,9 @@ npm start
   - [Medium](https://medium.com/openmina)
   - [Twitter](https://twitter.com/viable_systems)
 
-
 [changelog]: ./CHANGELOG.md
 [changelog-badge]: https://img.shields.io/badge/changelog-Changelog-%23E05735
-
 [release-badge]: https://img.shields.io/github/v/release/openmina/openmina
 [release-link]: https://github.com/openmina/openmina/releases/latest
-
 [Apache licensed]: https://img.shields.io/badge/license-Apache_2.0-blue.svg
-[Apache link]: https://github.com/openmina/openmina/blob/master/LICENSE
+[Apache link]: https://github.com/openmina/openmina/blob/master/LICENSE

docs/alpha-testing-guide.md

@@ -4,51 +4,57 @@ This guide will walk you through running the **Alpha Rust Node** on Devnet using
 
 ## 1. Prerequisites
 
-Ensure you have **Docker** installed. For installation instructions specific to your operating system, follow the steps outlined in the **Producer Demo Launch Guide**:
+Ensure you have **Docker** installed:
 
-- [Docker Installation Guide for Linux, macOS, and Windows](https://github.com/openmina/openmina/blob/main/docs/producer-demo.md#prerequisites)
+- [Docker Installation Guide for Linux, macOS, and Windows](./docker-installation.md)
 
 ## 2. Download & Start the Node
 
 1. **Download the Latest Release**:
+
    - Visit the [Open Mina Releases](https://github.com/openmina/openmina/releases).
    - Download the latest `openmina-vX.Y.Z-docker-compose.zip`.
 
 2. **Extract the Files**:
+
    ```bash
    unzip openmina-vX.Y.Z-docker-compose.zip
    cd openmina-vX.Y.Z-docker-compose
    ```
 
 3. **Start the Node on Devnet and Save Logs**:
    Start the node and save the logs for later analysis:
+
    ```bash
    docker compose up --pull always && docker compose logs > openmina-node.log
    ```
 
 4. **Access the Dashboard**:
    Open `http://localhost:8070` in your browser.
-   
-   The dashboard will show the syncing process in real time. 
+
+   The dashboard will show the syncing process in real time.
    <img width="1417" alt="image" src="https://github.com/user-attachments/assets/d9a5f5b3-522f-479b-9829-37402c63bb98">
-   
-   >**1. Connecting to Peers:** The node connects to peers. You’ll see the number of connected, connecting, and disconnected peers grow.
+
+   > **1. Connecting to Peers:** The node connects to peers. You’ll see the number of connected, connecting, and disconnected peers grow.
    >
-   >**2. Fetching Ledgers:** The node downloads key data: Staking ledger, Next epoch ledger, and Snarked ledger. Progress bars show the download status.
+   > **2. Fetching Ledgers:** The node downloads key data: Staking ledger, Next epoch ledger, and Snarked ledger. Progress bars show the download status.
    >
-   >**3. Fetching & Applying Blocks:** The node downloads recent blocks to match the network’s current state. The dashboard tracks how many blocks are fetched and applied.
+   > **3. Fetching & Applying Blocks:** The node downloads recent blocks to match the network’s current state. The dashboard tracks how many blocks are fetched and applied.
 
 ## 3. Monitoring and troubleshooting
 
 ### Inspecting Saved Logs
+
 If you’ve saved logs to a file, you can use tail or similar tools to view them:
 
 ```bash
 tail -f openmina-node.log
 ```
 
 ### Restart the Node:
+
 If the node becomes unresponsive or fails to start, restart the setup:
+
 ```bash
 docker compose down
 docker compose up --pull always

docs/block-producer-guide.md

@@ -0,0 +1,56 @@
+# Rust Node Block Production Testing on Devnet
+
+This guide is intended for setting up block producer nodes on **Mina Devnet** only.  
+Do not use this guide for Mina Mainnet until necessary security audits are complete.
+
+---
+
+## Prerequisites
+
+Ensure Docker and Docker Compose are installed on your system - [Docker Installation Guide](./docker-installation.md)
+
+## Download & Start the Node
+
+1. **Download the Latest Release**
+
+- Visit the [Open Mina Releases](https://github.com/openmina/openmina/releases)
+- Download the latest `openmina-vX.Y.Z-docker-compose.zip`
+- Extract the Files:
+
+  ```bash
+  unzip openmina-vX.Y.Z-docker-compose.zip
+  cd openmina-vX.Y.Z-docker-compose
+  mkdir openmina-workdir
+  ```
+
+2. **Prepare Your Keys**
+
+   [Docker Compose](../docker-compose.block-producer.yml) references `openmina-workdir`. It stores a private key and logs for block production.
+   Place your block producer's private key into the `openmina-workdir` directory and name it `producer-key`:
+
+   ```bash
+   cp /path/to/your/private_key openmina-workdir/producer-key
+   ```
+
+   Replace `/path/to/your/private_key` with the actual path to your private key file.
+
+3. **Launch Block Producer**
+
+   Use `MINA_PRIVKEY_PASS` to set the private key password. Optionally, use `COINBASE_RECEIVER` to set a different coinbase receiver:
+
+   ```bash
+   env COINBASE_RECEIVER="YourWalletAddress" MINA_PRIVKEY_PASS="YourPassword" \
+   docker compose -f docker-compose.block-producer.yml up -d --pull always
+   ```
+
+4. **Go to Dashboard**
+
+   Visit [http://localhost:8070](http://localhost:8070) to [monitor sync](http://localhost:8070/dashboard) and [block production](http://localhost:8070/block-production).
+
+### Access Logs
+
+Logs are stored in `openmina-workdir` with filenames like `openmina.log.2024-10-14`, `openmina.log.2024-10-15`, etc.
+
+### Provide Feedback
+
+Collect logs from `openmina-workdir` and report issues on the [rust-node-testing](https://discord.com/channels/484437221055922177/1290662938734231552) discord channel. Include reproduction steps if possible.

docs/docker-installation.md

@@ -0,0 +1,65 @@
+# Docker Installation Guide
+
+## Installation for
+
+- [Debian-based Linux](#docker-installation-on-debian-based-linux)
+- [Windows](#docker-installation-on-windows)
+- [macOS](#docker-installation-on-macos)
+
+## Docker Installation on Debian-based Linux
+
+1. Set up Docker's apt repository:
+
+    ```bash
+    # Add Docker's official GPG key:
+    sudo apt-get update
+    sudo apt-get install ca-certificates curl
+    sudo install -m 0755 -d /etc/apt/keyrings
+    sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
+    sudo chmod a+r /etc/apt/keyrings/docker.asc
+
+    # Add the repository to Apt sources:
+    echo \
+    "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
+    $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
+    sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+    sudo apt-get update
+    ```
+
+2. Install the Docker packages:
+
+    ```bash
+    sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+    ```
+
+3. Add your user to the `docker` group:
+
+    ```bash
+    sudo usermod -aG docker $USER
+    newgrp docker
+    ```
+
+4. Verify the installation:
+
+    ```bash
+    docker run hello-world
+    ```
+
+---
+
+## Docker Installation on Windows
+
+1. Download and Install [Docker Desktop for Windows](https://www.docker.com/products/docker-desktop/).
+
+2. Ensure Docker Desktop is running (check the system tray icon).
+
+---
+
+### Docker Installation on macOS
+
+1. Download and Install [Docker Desktop for Mac](https://www.docker.com/products/docker-desktop/).
+2. Verify the installation in Terminal:
+
+    ```bash
+    docker --version
+    ```