Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history 
Update README.md file according latest requests.
This fixes #3030.
  • Loading branch information
@ines-toupeira @jsdanielh
ines-toupeira authored and jsdanielh committed Nov 18, 2024
1 parent 098ebb8 commit 062af4c
Showing 1 changed file with 101 additions and 99 deletions.
200 changes: 101 additions & 99 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,75 +1,85 @@
# Nimiq Proof-of-Stake

![nimiq](https://raw.githubusercontent.com/nimiq/designs/master/logo/RGB/colored/png/nimiq_logo_rgb_horizontal.png)

> Rust implementation of the Nimiq Proof-of-Stake blockchain.
<a href="https://github.com/nimiq/core-rs-albatross">
<img src="https://raw.githubusercontent.com/nimiq/developer-center/refs/heads/main/assets/images/logos/albatross-repo-logo.svg" alt="Nimiq PoS Albatross Repository" width="600" />
</a>
<br/>
<br/>

[![Build Status](https://github.com/nimiq/core-rs-albatross/actions/workflows/build+test.yml/badge.svg?branch=albatross)](https://github.com/nimiq/core-rs-albatross/actions/workflows/build+test.yml?query=branch%3Aalbatross)
[![dependency status](https://deps.rs/repo/github/nimiq/core-rs-albatross/status.svg)](https://deps.rs/repo/github/nimiq/core-rs-albatross)

**[Nimiq](https://nimiq.com/)** is a frictionless payment protocol for the web.
[Nimiq](https://nimiq.com/) is a frictionless payment protocol for the web.

This repository is currently under development. It contains the implementation of the Nimiq Proof-of-Stake protocol based on the [Albatross](https://arxiv.org/abs/1903.01589) consensus algorithm.
This repository contains the Rust implementation of the Nimiq Proof-of-Stake protocol based on the Albatross consensus algorithm. It is designed to deliver high performance without sacrificing security. The Mainnet is now fully operational and ready for live transactions. It has been rigorously tested and is ready for production use.

Nimiq Proof-of-Stake was conceived with performance in mind without sacrificing security.
For the Testnet use and more detailed information on how to connect and use the network, please refer to the [Testnet](#testnet) section.

Currently, the protocol can be exercised in an environment aimed for developers where bugs are expected to happen.
For more detailed information about how to connect and use the testnet network, please refer to the [Testnet](#testnet) section.
---

## Table of Contents

- [Background](#background)
- [System requirements](#system-requirements)
### Table of Contents
- [Reference](#reference)
- [Hardware Requirements](#hardware-requirements-per-node-type)
- [Installation](#installation)
- [Documentation](#documentation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Testnet](#testnet)
- [Service Nodes Guides](#service-nodes-guides)
- [Docker](#docker)
- [Testnet](#testnet)
- [Software Integrity and Authenticity](#software-integrity-and-authenticity)
- [Contributing](#contributing)
- [License](#license)

## Background
### Reference

- [Nimiq Proof-of-Stake Portal](https://www.nimiq.com/albatross/): General information and high level details of the Nimiq Proof-of-Stake blockchain
- [Nimiq Albatross White Paper](https://arxiv.org/abs/1903.01589): White paper describing the consensus algorithm used in Nimiq Proof-of-Stake
- [Nimiq Proof-of-Stake migration process](https://www.nimiq.com/blog/nimiq-20-albatross-hard-fork-preparations/): Migration process to Nimiq Proof-of-Stake
- [Nimiq 1.0 Developer Reference](https://nimiq-network.github.io/developer-reference/): Details of the protocol architecture.
- [Nimiq 1.0 JavaScript implementation](https://github.com/nimiq/core-js/): Nimiq 1.0 implementation
- [Nimiq Proof-of-Stake Portal](https://www.nimiq.com/albatross/): General information and high level details of the Nimiq Proof-of-Stake blockchain.
- [Nimiq Albatross White Paper](https://arxiv.org/abs/1903.01589): White paper describing the consensus algorithm used in Nimiq Proof-of-Stake.
- [Nimiq Developer Center](https://www.nimiq.com/developers/): The place for all the developer documentation and protocol design implementation.
- [JSON-RPC Specification](https://www.nimiq.com/developers/build/set-up-your-own-node/rpc-docs/): Documentation for interacting with the network using JSON-RPC.
- [Nimiq Proof-of-Stake Migration Technicalities](https://www.nimiq.com/developers/migration/migration-technical-details): Migration process to Nimiq Proof-of-Stake.
- [Migration for Integrators](https://www.nimiq.com/developers/migration/migration-integrators): A guide for those who want a more in depth overview of the transitioning process from Proof-of-Work to Proof-of-Stake.
- [Blockchain Explorer](https://nimiq.watch/): Block Explorer for the Mainnet.

## System requirements
## Hardware Requirements per Node Type

- 64-bit computing architecture.
- 2 or more CPU cores
- 2GB of available RAM memory
- 5GB of free disk space, an SSD is highly recommended (100GB or more is required for history nodes)
- File systems with sparse file support.
- It is highly recommended to run a clock synchronization protocol such as NTP. This
is needed to properly accept blocks according to the timestamp and it is especially
important for validators in order to produce blocks in the expected timestamps.
| PoS Node Type | Memory | CPU | Storage | Network | Syncing Time |
| --- | --- | --- | --- | --- | --- |
| **History** | Minimum 16GB RAM (higher recommended) | Minimum 4 vCPUs, 8 recommended | Minimum 1TB of storage (2TB when enabling indexing); storage usage starts at a few gigabytes and grows linearly with blockchain size over time | High-speed, reliable internet connection; Good I/O performance (SSDs required) | Sync time increases over the life of the blockchain |
| **Full** | Minimum 16GB RAM | 4 vCPUs recommended | Minimum Minimum 60GB of storage | High-speed, reliable internet connection; Good I/O performance (SSDs recommended) | Sync time grows linearly but slowly |
| **Light** | Minimum 4GB RAM | 64-bit recommended | Works with minimal storage | Moderate-speed internet connection (1 Mbps or higher) | Syncs in a few seconds |

## Installation
#### Additional Recommendations:
- File System: Ensure support for sparse files.
- Clock Synchronization: Use a protocol like NTP for accurate block acceptance, which is essential for validators to produce blocks on time.

Besides [Rust stable](https://www.rust-lang.org/learn/get-started#installing-rust) itself,
the following packages are required to be able to compile the source code:
### Service Nodes Additional Requirements
Nimiq has also two specific node types with specialized roles in maintaining the network security and performing more advanced tasks.

- `clang`
- `cmake`
- `libssl-dev` (in Debian/Ubuntu) or `openssl-devel` (in Fedora/Red Hat)
- `pkg-config`
- **Validators** for block production:
- **PoS Node Type**: Full or History
- **Memory**: 16GB RAM minimum
- **CPU**: 4 vCPUs recommended

We currently do not make any guarantees about the minimum supported Rust version to consumers, but we currently test two versions older than the current Rust stable.
- **Prover nodes** for zero-knowledge proof generation:
- **PoS Node Type**: Full or History
- **Memory**: 64GB RAM minimum
- **CPU**: 8vCPUs recommended

After installing the previous packages, compiling the project is achieved through [`cargo`](https://doc.rust-lang.org/cargo/):
## Installation

1. Install the latest version of Rust by following the instructions on the [Rust website](https://www.rust-lang.org/learn/get-started#installing-rust) and following packages to be able to compile the source code:
- `clang`
- `cmake`
- `libssl-dev` (in Debian/Ubuntu) or `openssl-devel` (in Fedora/Red Hat)
- `pkg-config`

We currently do not make any guarantees about the minimum supported Rust version to consumers, but we currently test two versions older than the current Rust stable.

2. Clone the core-rs repository and compile the project with `cargo`:
```bash
git clone https://github.com/nimiq/core-rs-albatross
cd core-rs-albatross
cargo build --release
```

If you want to install the client onto your system (into `$HOME/.cargo/bin`), run:

3. Install the client onto your system (into `$HOME/.cargo/bin`) with:
```bash
cargo install --path client/
```
Expand All @@ -80,92 +90,84 @@ Alternatively, you can install it directly from git:
cargo install --git https://github.com/nimiq/core-rs-albatross.git
```

## Documentation
Extensive documentation explaining how the protocol is built up, the JSON-RPC specification, how to get started building applications on top of Nimiq and more can be found at the [Nimiq Developer Center](https://www.nimiq.com/developers/).

## Software Integrity and Authenticity
You can refer to the [documentation](./build/README.md) to learn more about reproducing Nimiq software for yourself as well as checking software signatures in order to verify the integrity and authenticity of software.

## Usage

After installation, you can run the client directly, like this:
### Configuration
You need a configuration file to customize your node according to your specific requirements. Follow one of the methods below to create and edit your configuration file.

**Option A**
The configuration file is generated automatically and in a specific location.
1. Generate the configuration file with the following command:
```bash
cargo run --release --bin nimiq-client
```

### Configuration

By default the client will look for a configuration file in `$HOME/.nimiq/client.toml`.
In order to create this file yourself, you can use the example config file as follow:

This generates a sample file and places it in a folder `./nimiq`.
2. Copy the sample configuration file into a new file in the same directory where you will edit it according to your needs:
```bash
cargo run --release --bin nimiq-client # Run the client. This will create the example config file.
cp $HOME/.nimiq/client.example.toml $HOME/.nimiq/client.toml # Create your config from the example.
nano $HOME/.nimiq/client.toml # Edit the config. Explanations are included in the file.
cp $HOME/.nimiq/client.example.toml $HOME/.nimiq/client.toml
```
3. Edit your configuration file following the explanations inside. Check some [important settings](#configuration) to take into account below.
4. Run the client:
```bash
cargo run --release --bin nimiq-client
```
By default, the client will look for the config file in `$HOME/.nimiq/client.toml`.

If you want to directly specify your own configuration file when running the client, you can do so as follow:

**Option B**
Download the example file and manually place it.
1. Copy this [sample configuration file](https://github.com/nimiq/core-rs-albatross/blob/albatross/lib/src/config/config_file/client.example.toml) to your preferred location.
2. Edit the configuration file and adjust settings as needed. Refer to the [configuration settings](#configuration) for guidance.
3. Run the client with the specified file:
```bash
cargo run --release --bin nimiq-client -- -c path/to/client.toml
```

Please take a look at the [`client.example.toml`](lib/src/config/config_file/client.example.toml) for all the configuration options.

### Testnet
### Service Nodes Guides
You can also choose to run a validator or a prover node. Check our guides with the full step-by-step description:
- [Validators](https://www.nimiq.com/developers/build/set-up-your-own-node/becoming-a-validator)
- [Prover nodes](https://www.nimiq.com/developers/build/set-up-your-own-node/prover-node-guide)

The testnet network is currently in a phase open to the general public to use.
Its main purpose is to invite everyone to exercise and test the Nimiq Proof-of-Stake functionality and we invite people to file and report any [issues](https://github.com/nimiq/core-rs-albatross/issues/new) through our GitHub repository.

#### Getting funds

There are two ways of getting funds:

- Using an account in the [Testnet Nimiq Wallet](https://wallet.pos.nimiq-testnet.com/) and requesting funds in the wallet.
- Directly using the [Devnet Faucet](https://faucet.pos.nimiq-testnet.com/):
## Docker

```
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "address=NQXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX" https://faucet.pos.nimiq-testnet.com/tapit
```
1. Create a `data` folder in the main directory with `mkdir ~/data`.
2. Pull the latest image from the container registry:
`docker pull ghcr.io/nimiq/core-rs-albatross:latest`.
3. Create a `client.toml` file in `~/data` with `cp ./lib/src/config/config_file/client.example.toml ~/data/client.toml`.
4. Customize the configuration file to match your requirements. Refer to the [sample configuration file](https://github.com/nimiq/core-rs-albatross/blob/albatross/lib/src/config/config_file/client.example.toml) and [configuration settings](#configuration) for guidance.
5. Run the client via Docker:
`docker run -v $(pwd)/data:/home/nimiq/.nimiq -p 8443:8443 -p 8648:8648 -p 9100:9100 --name nimiq-rpc --rm ghcr.io/nimiq/core-rs-albatross:latest`.

#### Becoming a validator
**Overview of Exposed Ports:**

Check [this guide](https://www.nimiq.com/developers/build/set-up-your-own-node/becoming-a-validator) for steps on becoming a validator.
| Port | Description |
| --- | --- |
| 8443 | Incoming network connections port |
| 8648 | RPC port |
| 9100 | Metrics port |

## Docker
## Testnet
The Testnet network is publicly available for testing and experimentation. Its main purpose is to invite everyone to exercise and test the Nimiq Proof-of-Stake functionality and we invite people to file and report any [issues](https://github.com/nimiq/core-rs-albatross/issues/new) through our GitHub repository.

Use `docker pull ghcr.io/nimiq/core-rs-albatross:latest` to pull the latest docker image.
Then mount a volume to configure the client:
You can use the Testnet by setting the [consensus.network](https://github.com/nimiq/core-rs-albatross/blob/a61a230915726261874163e94fdf81ee9c253404/lib/src/config/config_file/client.example.toml#L121) in your configuration file set to `test-albatross`. Additionally uncomment the [network.seed_nodes](https://github.com/nimiq/core-rs-albatross/blob/b8ed402c9096ffb54afea52347b91ab7831e75de/lib/src/config/config_file/client.example.toml#L29) for the Testnet and comment the Mainnet ones.

```
mkdir data
cp ./lib/src/config/config_file/client.example.toml data/client.toml
```
#### Getting funds

Note that you can modify the client configuration and this is a must if you are running a validator.
For more documentation on the configuration file, check the [configuration](#configuration) section of this guide.
There are two ways of getting funds:

Once the data directory is created and ready, you can run the client with:
- Using an account in the [Testnet Nimiq Wallet](https://wallet.pos.nimiq-testnet.com/) and requesting funds in the wallet.
- Directly using the [Testnet Faucet](https://faucet.pos.nimiq-testnet.com/):

```
docker run -v $(pwd)/data:/home/nimiq/.nimiq -p 8443:8443 -p 8648:8648 -p 9100:9100 --name nimiq-rpc --rm ghcr.io/nimiq/core-rs-albatross:latest
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "address=NQXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX" https://faucet.pos.nimiq-testnet.com/tapit
```

Overview of exposed ports:
| Port | Description |
|------|--------------|
| 8443 | Incoming connections port |
| 8648 | RPC port |
| 9100 | Metrics port |
### Software Integrity and Authenticity
To ensure the software you are running is authentic and has not been tampered with, refer to the [documentation](https://github.com/nimiq/core-rs-albatross/blob/albatross/build/README.md). It provides details on reproducing Nimiq software and verifying software signatures.

## Contributing

If you'd like to contribute to the development of Nimiq please follow our [Code of Conduct](/.github/CODE_OF_CONDUCT.md)
and [Contributing Guidelines](/.github/CONTRIBUTING.md).

Small note: When editing the README, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification.

## License

This project is licensed under the [Apache License 2.0](./LICENSE.md).
This project is licensed under the [Apache License 2.0](./LICENSE.md).

0 comments on commit 062af4c

Please sign in to comment.