feat: Improve README.md structure (#323)

Signed-off-by: georgi-l95 <[email protected]> Signed-off-by: Atanas Atanasov <[email protected]> Co-authored-by: Atanas Atanasov <[email protected]>
hashgraph · Nov 8, 2024 · 76811f0 · 76811f0
1 parent 63a5994
commit 76811f0
Show file tree

Hide file tree

Showing 16 changed files with 509 additions and 198 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,48 @@
-# hedera-block-node
-The block node is a new and unique node designed to consume the blocks streams, maintain state and expose additional targeted value adding APIs to the Hedera community.
-More details to come as this is work in progress
+# Hedera Block Node
+
+Implementation of the Hedera Block Node, which is responsible for consuming the block streams, maintaining state and exposing additional targeted value adding APIs to the Hedera community.
+
+## Table of Contents
+
+1. [Project Links](#project-links)
+1. [Prerequisites](#prerequisites)
+1. [Overview of child modules](#overview-of-child-modules)
+1. [Getting Started](#getting-started)
+1. [Support](#support)
+1. [Contributing](#contributing)
+1. [Code of Conduct](#code-of-conduct)
+1. [Security](#-security)
+1. [License](#license)
+
+## Project Links
+
+[![Build Application](https://github.com/hashgraph/hedera-block-node/actions/workflows/build-application.yaml/badge.svg?branch=main)](https://github.com/hashgraph/hedera-block-node/actions/workflows/build-application.yaml)
+[![E2E Test Suites](https://github.com/hashgraph/hedera-block-node/actions/workflows/e2e-tests.yaml/badge.svg?branch=main)](https://github.com/hashgraph/hedera-block-node/actions/workflows/e2e-tests.yaml)
+[![codecov](https://codecov.io/github/hashgraph/hedera-block-node/graph/badge.svg?token=OF6T6E8V7U)](https://codecov.io/github/hashgraph/hedera-block-node)
+
+[![Latest Version](https://img.shields.io/github/v/tag/hashgraph/hedera-block-node?sort=semver&label=version)](README.md)
+[![Made With](https://img.shields.io/badge/made_with-java-blue)](https://github.com/hashgraph/hedera-block-node/)
+[![Development Branch](https://img.shields.io/badge/docs-quickstart-green.svg)](docs/overview.md)
+[![License](https://img.shields.io/badge/license-apache2-blue.svg)](LICENSE)
+
+## Prerequisites
+
+- Java 21 (temurin recommended)
+- Gradle (using the wrapper `./gradlew` is highly recommended)
+- Docker (recommended for running the projects)
+- IntelliJ IDEA (recommended for development)
+
+## Overview of child modules
+
+- `server`: implementation of the block node, which contains the main application and all the necessary code to run the block node.
+- `simulator`: A simulator for the block node, which can be used to test the block node in a local environment.
+- `common`: Module responsible for holding common literals, utilities and types used by the other modules.
+- `suites`: A set of e2e tests that can be used to verify the correctness of the block node.
+- `tools`: A set of command line tools for working with block stream files.
+
+## Getting Started
+
+Refer to the [Hedera Block Node Documentation Overview](docs/overview.md) for more information about the project, design and guides.
 
 ## Support
 
@@ -20,46 +62,10 @@ This project is governed by the
 participating, you are expected to uphold this code of conduct. Please report unacceptable behavior
 to [[email protected]](mailto:[email protected]).
 
-## License
-
-[Apache License 2.0](LICENSE)
-
-# 🔐 Security
-
-Please do not file a public ticket mentioning the vulnerability. Refer to the security policy defined in the [SECURITY.md](https://github.com/hashgraph/hedera-sourcify/blob/main/SECURITY.md).
-
----
-
-# Usage
-
-## Configuration
+## 🔐 Security
 
-| Environment Variable              | Description                                                                                                   | Default Value |
-|-----------------------------------|---------------------------------------------------------------------------------------------------------------|---------------|
-| PERSISTENCE_STORAGE_ROOT_PATH     | The root path for the storage, if not provided will attempt to create a `data` on the working dir of the app. |               |
-| CONSUMER_TIMEOUT_THRESHOLD_MILLIS | Time to wait for subscribers before disconnecting in milliseconds                                             | 1500          |
-| SERVICE_DELAY_MILLIS              | Service shutdown delay in milliseconds                                                                        | 500           |
-| MEDIATOR_RING_BUFFER_SIZE         | Size of the ring buffer used by the mediator (must be a power of 2)                                           | 67108864      |
-| NOTIFIER_RING_BUFFER_SIZE         | Size of the ring buffer used by the notifier (must be a power of 2)                                           | 2048          |
-
-# Starting locally:
-```bash
-./gradlew run
-```
-
-In debug mode, you can attach a debugger to the port 5005.
-```bash
-./gradlew run --debug-jvm
-```
-
-Also you can run on docker locally:
-```bash
-./gradlew startDockerContainer
-```
-
-# Running Tests
-1) ./gradlew build
+Please do not file a public ticket mentioning the vulnerability. Refer to the security policy defined in the [SECURITY.md](https://github.com/hashgraph/hedera-block-node/blob/main/SECURITY.md).
 
+## License
 
-### Code Coverage
-[![codecov](https://codecov.io/github/hashgraph/hedera-block-node/graph/badge.svg?token=OF6T6E8V7U)](https://codecov.io/github/hashgraph/hedera-block-node)
+[Apache License 2.0](LICENSE)
diff --git a/docs/Protocol/README.md b/docs/Protocol/README.md
@@ -8,4 +8,4 @@ behavior of both sides of that API call, including common error conditions.
 ## Contents
 | Document | API call | Description |
 |:---|---:|:---|
-| publishBlockStream.md | `publishBlockStream` | The communication between a publisher and a block node when publishing a block stream from an authoritative source such as a consensus node.|
+| [publishBlockStream.md](publishBlockStream.md) | `publishBlockStream` | The communication between a publisher and a block node when publishing a block stream from an authoritative source such as a consensus node. |
diff --git a/docs/Protocol/publishBlockStream.md b/docs/Protocol/publishBlockStream.md
@@ -1,5 +1,14 @@
 # Block Node Connect Protocol for `publishBlockStream`
 
+## Table of Contents
+1. [Abstract](#abstract)
+   1. [Reliability note](#reliability-note)
+1. [Definitions](#definitions)
+1. [Base Protocol](#base-protocol)
+   1. [Base Protocol Diagram](#base-protocol-diagram)
+1. [Error Handling](#error-handling)
+   1. [Error Handling Diagram](#error-handling-diagram)
+
 ## Abstract
 This protocol describes how a Publisher and Block Node SHALL interact for
 the `publishBlockStream` API. The protocol provides for either side of the

diff --git a/docs/overview.md b/docs/overview.md
@@ -0,0 +1,23 @@
+# Hedera Block Node Documentation Overview
+
+This document will outline the structure and content of Block Node documentation.
+
+## Table of Contents
+
+1. [Projects](#projects)
+1. [Concepts](#concepts)
+1. [Release](#release)
+
+## Projects
+
+- [Hedera Block Node](../server/README.md): Provides an introduction to Hedera Block Node, its purpose and how it can be used.
+- [Simulator](../simulator/README.md): Offers instructions on how the Simulator can be utilized.
+- [Tools](../tools/README.md): Provides information on the command line tools available.
+
+## Concepts
+
+- [Hedera Block Node Protocol](Protocol/README.md): Overview of the Hedera Block Node Protocol
+
+## Release
+
+- [Release Process Documentation](release.md): Details the steps involved in creating a new release, tagging, and publishing artifacts.
diff --git a/docs/release.md b/docs/release.md
@@ -1,57 +1,68 @@
-## Release Process Documentation
+# Release Process Documentation
 
-### Overview
+## Table of Contents
+
+1. [Overview](#overview)
+1. [Kickstart Release Process](#kickstart-release-process)
+1. [Release Automation Workflow](#release-automation-workflow)
+   1. [Steps](#steps)
+1. [Publish Release Workflow](#publish-release-workflow)
+1. [Mermaid Diagram](#mermaid-diagram)
+1. [Release Meta Process](#release-meta-process)
+1. [Conclusion](#conclusion)
+
+## Overview
 
 This document outlines the release process for our project, detailing the steps involved in creating a new release, tagging, and publishing artifacts.
 
-### Kickstart Release Process
+## Kickstart Release Process
 
 1. **Milestone and Label Check**:
-    - Ensure all Pull Requests (PRs) have a milestone set and appropriate labels. This is important for generating accurate release notes.
-    - There is a CI check to ensure that all PRs have a milestone and labels set. If not, the PR will not be merged.
-    - Make sure all PRs and Issues related to the related milestone are already closed, if not closed them before proceeding or move them to the next milestone.
+   - Ensure all Pull Requests (PRs) have a milestone set and appropriate labels. This is important for generating accurate release notes.
+   - There is a CI check to ensure that all PRs have a milestone and labels set. If not, the PR will not be merged.
+   - Make sure all PRs and Issues related to the related milestone are already closed, if not closed them before proceeding or move them to the next milestone.
 2. **Trigger Release Automation Workflow**:
-    - Manually trigger the `release-automation.yaml` workflow with the desired version to be released.
-    - The workflow will create a new release branch, bump the version, and tag the release.
-    - The release branch will be used for any patch versions or hot-fixes.
-    - If the release branch already exists, the workflow should be triggered using the branch release, and the version should be bumped accordingly.
+   - Manually trigger the `release-automation.yaml` workflow with the desired version to be released.
+   - The workflow will create a new release branch, bump the version, and tag the release.
+   - The release branch will be used for any patch versions or hot-fixes.
+   - If the release branch already exists, the workflow should be triggered using the branch release, and the version should be bumped accordingly.
       - for example: if `release/0.1` exists, and you want to release `0.1.1`, trigger the workflow with `0.1.1` as the semver input and select `release/0.1` on "Use workflow from" dropdown.
 
-### Release Automation Workflow
+## Release Automation Workflow
 
 The release process is automated using a GitHub Actions workflow (`release-automation.yaml`). The workflow must be triggered manually with a SemVer version input, which specifies the version to be released. The input can be:
 - `x.n.0-rc1` for release candidates
 - `x.n.0` for general availability (GA) versions
 - `x.n.p` for patch versions, including hot-fixes
 
-#### Steps:
+### Steps:
 
 1. **Create or Update Release Branch**:
-    - Create a new release branch `release/0.n` if it doesn't exist.
-    - If the release branch was created, means it's a new release, create a PR on the main branch to increase the snapshot version to the next version.
-    - Bump the version to the input provided in the release branch.
+   - Create a new release branch `release/0.n` if it doesn't exist.
+   - If the release branch was created, means it's a new release, create a PR on the main branch to increase the snapshot version to the next version.
+   - Bump the version to the input provided in the release branch.
 
 2. **Tagging**:
-    - After bumping the version on the release branch, tag the version as `vX.n.p` (where `X.n.p` is the input).
-    - Push the tag, triggering the `Publish Release Workflow`.
+   - After bumping the version on the release branch, tag the version as `vX.n.p` (where `X.n.p` is the input).
+   - Push the tag, triggering the `Publish Release Workflow`.
 
 3. **Release Notes and Milestone**:
-    - Create release notes for the new Tag.
-    - Close the milestone associated with the release.
-    - Upload distribution artifacts to the release.
-    - Publish the artifacts to Sonatype Nexus / Maven Central.
+   - Create release notes for the new Tag.
+   - Close the milestone associated with the release.
+   - Upload distribution artifacts to the release.
+   - Publish the artifacts to Sonatype Nexus / Maven Central.
 
-### Publish Release Workflow
+## Publish Release Workflow
 
 The `Publish Release Workflow` (`publish-release.yaml`) is triggered by the Tag pushed in the previous step. This workflow performs the following tasks:
 
 1. **Docker Image Creation and Publishing**:
-    - Create a Docker image with the new release version and publish it to the GitHub Container Registry (`ghcr.io`).
+   - Create a Docker image with the new release version and publish it to the GitHub Container Registry (`ghcr.io`).
 
 2. **Helm Chart Publishing**:
-    - Publish a new Helm chart with the same version to the custom GitHub Pages of the repo in the `Charts` folder.
+   - Publish a new Helm chart with the same version to the custom GitHub Pages of the repo in the `Charts` folder.
 
-### Mermaid Diagram
+## Mermaid Diagram
 
 ```mermaid
 graph TD
@@ -84,20 +95,20 @@ graph TD
     end
 ```
 
-### Release Meta Process
+## Release Meta Process
 
 The meta process typically follows these steps:
 
 1. **Initial Release Candidate (RC)**:
-    - Trigger the Release Automation Workflow with an `rc` version (e.g., `x.n.0-rcY`).
-    - Perform integration and performance testing on this version.
+   - Trigger the Release Automation Workflow with an `rc` version (e.g., `x.n.0-rcY`).
+   - Perform integration and performance testing on this version.
 
 2. **General Availability (GA)**:
-    - Once testing is successful, trigger the Release Automation Workflow again for the same version but as a GA version (e.g., `x.n.0`).
+   - Once testing is successful, trigger the Release Automation Workflow again for the same version but as a GA version (e.g., `x.n.0`).
 
 3. **Patch Versions**:
-    - For any patch versions, changes will be merged (cherry-picked from main) into the release branch.
-    - Start a new release automation process for the patch version (e.g., `x.n.p`).
+   - For any patch versions, changes will be merged (cherry-picked from main) into the release branch.
+   - Start a new release automation process for the patch version (e.g., `x.n.p`).
 
 ```mermaid
 graph TD
@@ -110,10 +121,8 @@ graph TD
     D1 --> E1[Merge Patches from Main to Release Branch]
     E1 --> F1[Trigger Release Automation Workflow for x.n.p]
     F1 --> G1[Patch Version Released]
-
 ```
 
 ## Conclusion
 
 This release process ensures that all steps are automated, from checking PR milestones and labels to creating branches, tagging releases, and publishing Docker images and Helm charts. By following this documentation, you can streamline the release workflow and maintain consistency across all releases.
-
diff --git a/server/README.md b/server/README.md
@@ -0,0 +1,39 @@
+# Block Node Application
+
+## Table of Contents
+
+1. [Overview](#overview)
+1. [Prerequisites](#prerequisites)
+1. [Configuration](#configuration)
+1. [Metrics](#metrics)
+1. [Design](#design)
+   1. [Block Persistence](#block-persistence)
+   1. [Bi-directional Producer/Consumer Streaming with gRPC](#bi-directional-producerconsumer-streaming-with-grpc)
+
+## Overview
+
+The Block Stream Application is designed handle the output of a Hedera Node, which would be in form of Block Stream.
+By handling we can understand verifying, storing and applying needed state changes.
+It uses various configuration sources and dependency injection to manage its components.
+
+## Configuration
+
+Refer to the [Configuration](docs/configuration.md) for configuration options.
+
+## Quickstart
+
+Refer to the [Quickstart](docs/quickstart.md) for a quick guide on how to get started with the application.
+
+## Metrics
+
+Refer to the [Metrics](docs/metrics.md) for metrics available in the system.
+
+## Design
+
+### Block Persistence
+
+Refer to the [Block Persistence](docs/design/block-persistence.md) for details on how blocks are persisted.
+
+### Bi-directional Producer/Consumer Streaming with gRPC
+
+Refer to the [Bi-directional Producer/Consumer Streaming with gRPC](docs/design/bidi-producer-consumers-streaming.md) for details on how the gRPC streaming is implemented.
diff --git a/server/docs/configuration.md b/server/docs/configuration.md
@@ -0,0 +1,18 @@
+# Server Configuration
+
+The components of the Hedera Block Node all support loading configuration via the
+environment.
+
+## Default Values
+
+The default configuration allows users to quickly get up and running without having to configure anything. This provides
+ease of use at the trade-off of some insecure default configuration. Most configuration settings have appropriate
+defaults and can be left unchanged. It is recommended to browse the properties below and adjust to your needs.
+
+| Environment Variable | Description | Default Value |
+|:---|:---|---:|
+| PERSISTENCE_STORAGE_ROOT_PATH | The root path for the storage, if not provided will attempt to create a `data` on the working dir of the app. | |
+| CONSUMER_TIMEOUT_THRESHOLD_MILLIS | Time to wait for subscribers before disconnecting in milliseconds | 1500 |
+| SERVICE_DELAY_MILLIS | Service shutdown delay in milliseconds | 500 |
+| MEDIATOR_RING_BUFFER_SIZE | Size of the ring buffer used by the mediator (must be a power of 2) | 67108864 |
+| NOTIFIER_RING_BUFFER_SIZE | Size of the ring buffer used by the notifier (must be a power of 2) | 2048 |