Skip to content

Latest commit

 

History

History
173 lines (133 loc) · 9.67 KB

README.md

File metadata and controls

173 lines (133 loc) · 9.67 KB
Raw
Nimiq PoS Albatross Repository

Build Status dependency status

Nimiq is a frictionless payment protocol for the web.

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.

For the Testnet use and more detailed information on how to connect and use the network, please refer to the Testnet section.

Table of Contents

Reference

Hardware Requirements per Node Type

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

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.

Service Nodes Additional Requirements

Nimiq has also two specific node types with specialized roles in maintaining the network security and performing more advanced tasks.

  • Validators for block production:

    • PoS Node Type: Full or History
    • Memory: 16GB RAM minimum
    • CPU: 4 vCPUs recommended

  • Prover nodes for zero-knowledge proof generation:

    • PoS Node Type: Full or History
    • Memory: 64GB RAM minimum
    • CPU: 8vCPUs recommended

Installation

  1. Install the latest version of Rust by following the instructions on the Rust website 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.

  1. Clone the core-rs repository and compile the project with cargo:
git clone https://github.com/nimiq/core-rs-albatross
cd core-rs-albatross
cargo build --release
  1. Install the client onto your system (into $HOME/.cargo/bin) with:
cargo install --path client/

Alternatively, you can install it directly from git:

cargo install --git https://github.com/nimiq/core-rs-albatross.git

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:
cargo run --release --bin nimiq-client

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:

cp $HOME/.nimiq/client.example.toml $HOME/.nimiq/client.toml
  1. Edit your configuration file following the explanations inside. Check some important settings to take into account below.
  2. Run the client:
cargo run --release --bin nimiq-client

By default, the client will look for the config file in $HOME/.nimiq/client.toml.

Option B Download the example file and manually place it.

  1. Copy this sample configuration file to your preferred location.
  2. Edit the configuration file and adjust settings as needed. Refer to the configuration settings for guidance.
  3. Run the client with the specified file:
cargo run --release --bin nimiq-client -- -c path/to/client.toml

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:

Docker

  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 and configuration settings 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.

Overview of Exposed Ports:

Port Description
8443 Incoming network connections port
8648 RPC port
9100 Metrics port

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 through our GitHub repository.

You can use the Testnet by setting the consensus.network in your configuration file set to test-albatross. Additionally uncomment the network.seed_nodes for the Testnet and comment the Mainnet ones.

Getting funds

There are two ways of getting funds:

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

Software Integrity and Authenticity

To ensure the software you are running is authentic and has not been tampered with, refer to the documentation. 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 and Contributing Guidelines. Small note: When editing the README, please conform to the standard-readme specification.

License

This project is licensed under the Apache License 2.0.