Nimiq Proof-of-Stake

Rust implementation of the Nimiq Proof-of-Stake blockchain.

Nimiq 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 consensus algorithm.

Nimiq Proof-of-Stake was conceived with performance in mind without sacrificing security.

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 section.

Table of Contents

• Background
• System requirements
• Installation
• Usage
• Configuration
• Testnet
• Docker
• Contributing
• License

Background

• Nimiq Proof-of-Stake Portal: General information and high level details of the Nimiq Proof-of-Stake blockchain
• Nimiq Albatross White Paper: White paper describing the consensus algorithm used in Nimiq Proof-of-Stake
• Nimiq Proof-of-Stake migration process: Migration process to Nimiq Proof-of-Stake
• Nimiq 1.0 Developer Reference: Details of the protocol architecture.
• Nimiq 1.0 JavaScript implementation: Nimiq 1.0 implementation

System requirements

• 64-bit computing architecture.
• File systems with sparse file support.
• It is highly recommended to run a clock synchronization protocol such as NTP. This is needed for properly accept blocks according to the timestamp and it is specially important for validators in order to produce blocks in the expected timestamps.

Installation

Besides Rust stable itself, the following packages are required to be able to compile the source code:

• clang
• cmake
• libssl-dev (in Debian/Ubuntu) or openssl-devel (in Fedora/Red Hat)
• pkg-config
• protobuf-compiler

After installing the previous packages, compiling the project is achieved through cargo:

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:

cargo install --path client/

Alternatively, you can install it directly from git:

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

Usage

After installation, you can run the client directly, like this:

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:

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.

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

cargo run --release --bin nimiq-client -- -c path/to/client.toml

Please take a look at the client.example.toml for all the configuration options.

Testnet

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

Getting funds

There are two ways of getting funds:

• Using an account in the Testnet Nimiq Wallet and requesting funds in the wallet.
• Directly using the Devnet Faucet:

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

Becoming a validator

Check this guide for steps on becoming a validator.

Docker (outgoing connections only)

Use docker pull ghcr.io/nimiq/core-rs-albatross:latest to pull the latest docker image. Then run it:

mkdir data
docker run -v $(pwd)/data:/home/nimiq/.nimiq -p 8648 -p 9200:9200 --name nimiq-rpc --rm ghcr.io/nimiq/core-rs-albatross:latest

Overview of exposed ports:

As you can see, the default port (8443) for accepting connections from other nodes is not exposed, so this is an outgoing connections only container. It is intended for RPC use and metrics gathering.

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.