Getting started with the Albatross Alpha Testnet

:warning: Update (July 2020): The alpha testnet is currently stalled and the seed node is shut down. Work on Albatross is ongoing and there is currently no estimated timeframe for a new testnet. Please check in Nimiq’s Discord#coders-dojo or in Telegram#CodersDojo for updates.


The Albatross Alpha Testnet was just announced! For technical people, who want to try it out, these are the steps to become a validator and try staking.

This is a wiki post, which means every logged in user can edit it!

Please note that the Alpha Testnet is called “Alpha” for a reason. As mentioned in the announcent post, this version of the Testnet can be extremely unstable and might get reset often. Please don’t use any mainnet Accounts for testing.

Table of Contents

  1. Setup
  2. Run the Client
  3. Check your Status with JSON-RPC
  4. Create or Import your Account
  5. Become a Validator
  6. Stake on Behalf of a Validator
  7. Retire and Unstake
  8. Send a Transaction
  9. RPC Methods

1 Setup

1.0 Prerequisites

in order to be able to compile the rust code you need several software packages to be installed before you can compile the code.

Debian:
sudo apt install build-essential libssl-dev

1.1 Install Rust

To install the Rust compiler and its package manager Cargo, see the installation instructions on this page: https://www.rust-lang.org/learn/get-started

Then install the nightly version of Rust and make it the default by running:

rustup install nightly
rustup default nightly

1.2 Get the Code

Clone the Albatross source code from Github:

git clone [email protected]:nimiq/core-rs-albatross.git
# or clone via HTTPS:
git clone https://github.com/nimiq/core-rs-albatross.git

Then check out the testnet branch:

git checkout albatross-devnet

2 Run the Client

2.1 Build

In your $HOME directory, create a folder named “.nimiq”:

mkdir ~/.nimiq
# Go into the /client directory:
cd core-rs-albatross/client

# Cargo will take care of everything:
cargo run

On first run, cargo will automatically download and compile all required dependencies and then build the Nimiq Client. This might take a while and will use your full CPU.

After it compiled and started for the first time, it will create an example config file in the ~/.nimiq/ folder in your home directory, then the client will exit because you don’t have a config yet.

2.2 Configure

You need to copy ~/.nimiq/client.toml.example to ~/.nimiq/client.toml. You can leave all config options as they are for now to start a basic full node (no other consensus types are available yet).

Note: To be able to control your node and to stake and validate, you need to enable the JSON-RPC server in your client.toml. You do that by uncommenting #[rpc-server] => [rpc-server] around line 122.

2.3 Sync the Blockchain

After you finished your configuration, simply run the client again from inside the /client directory with cargo run. It will connect to the seed node, then to the other nodes in the network and start syncing the blockchain. Since only the full (archive) consensus type is available right now, all blocks including micro blocks are synced, starting from the Genesis Block. Depending on how long the Alpha Testnet has been running, this can take a while. See the next chapter to query your node for its status.

3 Check your Status with JSON-RPC

If you enabled the JSON-RPC Server in your node’s config, you can query your node and send commands with simple HTTP POST requests, or with specialized RPC clients.

3.1 Curl

A simple, but not very userfriendly method to send commands is with the curl CLI tool, available in any UNIX terminal. To query the current consensus state, you can run:

curl -X POST localhost:8648 -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"consensus","id":0}'

If you changed the port of the JSON-RPC Server in your config, you need to adjust the port (:8648) in the above command.

While syncing, the response you’ll get is {"jsonrpc":"2.0","id":0,"result":"syncing"}.

3.2 jsonrpc-cli

You can also use dedicated JSON-RPC clients, such as dan-da/jsonrpc-cli, a PHP tool. Check the README for installation instructions. Then run your RPC commands like this:

./jsonrpc-cli 127.0.0.1:8648 blockNumber

Note: jsonrpc-cli does not seem to work with localhost as the hostname, so you need to specify the loopback IP address 127.0.0.1 instead.

jsonrpc-cli does not report errors in results automatically. So when you get null as the response of your RPC command, try adding --resultonly=off to the command in front of the IP address, to see the whole response object, including the error field.

4 Create or Import your Account

You can either create a new account in your node or import an existing private key.

4.1 Create Account

./jsonrpc-cli 127.0.0.1:8648 createAccount <password>

The created account’s address, public key and private key will be returned and displayed in the terminal.

Important: You should save the private key now, because you cannot retrieve it again. Stored accounts are lost when you delete your node’s database (when the Alpha Testnet is restarted).

4.2 Import Private Key

If you already have a private key you want to import, pass it in HEX format to the importRawKey RPC method:

./jsonrpc-cli 127.0.0.1:8648 importRawKey <your private key> <password (optional)>

The address of the imported account is returned.

4.3 Check your Balance

./jsonrpc-cli 127.0.0.1:8648 getBalance "<your address>"

Your current balance is returned in Luna.

5 Become a Validator

To become a validator, you need to send a special transaction to the staking contract. There is an RPC method for this: createValidator. It takes these arguments:

  • sender_address: NIM address used to create this transaction
  • validator_key: Public key of validator (BLS)
  • proof_of_knowledge: Proof of knowledge of validator key
  • reward_address: NIM address used for the reward
  • amount: Initial staking amount in Luna
  • fee: Fee for transaction in Luna

These are the steps to become a validator:

5.1 Get your Validator Key and Proof of Knowledge

When you started your node for the first time, and if you did not remove the [validator] config, your node created your validator key as ~/.nimiq/validator_key.dat. You can query it in HEX format with

./jsonrpc-cli 127.0.0.1:8648 validatorKey

As the response you’ll get your validatorKey and proofOfKnowledge, both in HEX format. (The proof of knowledge is a signature of the public validator key, signed with your private validator key).

5.2 Unlock your Account

To be able to sign transactions, you need to unlock your Account in your node:

./jsonrpc-cli 127.0.0.1:8648 unlockAccount "<your address>" <password (if set)>

5.3 Send Validator Transaction

Finally, we become a validator:

./jsonrpc-cli 127.0.0.1:8648 createValidator \
	"<your address>" \
	<your validator-key from step 5.1> \
	<your proof-of-knowledge from step 5.1>  \
	"<your address again>" \
	<staking amount in Luna> \
	<fee in Luna>

Example:

./jsonrpc-cli 127.0.0.1:8648 createValidator "NQ69 MU19 XRVJ 2P5G NTDL JF3K C24G LUCQ L43E" b9a9a93cdf7d36f7e22257391c296cf59fd5153885279afc4ff27349a46028fc2966e2302a3987e19793b8bd6a58a31713d4aa8154745332b8b65506856a2b5d42e9f80a32717ea1cf14f34f399a8da9f10ab703be41adb7c2b7f1e13cffbd2e b63824c2dca0cba3a67b0a0a229e2606b753cf2b8ef58087feec878a7a04d3ba594ebd53208ddd4a39fd6ad538ed96c1 "NQ69 MU19 XRVJ 2P5G NTDL JF3K C24G LUCQ L43E" 100000000 0

After you send this command and the transaction gets accepted (command returns the transaction hash), you will become a validator in the next epoch. Your node will log that it produces blocks and your balance in your Account will increase when you get the block rewards in macro blocks.

6 Stake on Behalf of a Validator

You can stake your NIM on behalf of an online validator. Your staked NIM then count towards the validators stake, increasing their likelyhood of becoming a block producer. Note that all block rewards are received by the validators reward address, not yours.

./jsonrpc-cli 127.0.0.1:8648 stake \
	"<your address (sender)>" \
	<validator-key of validator> \
	<staking amount in Luna> \
	<fee in Luna>

7 Retire and Unstake

7.1 Retire your Validator

Retiring a validator is not yet implemented via RPC.

7.2 Unstake delegated Stake

Unstaking delegated stake currently seems to be broken.

8 Send a Transaction

To send a transaction, you can use the sendTransaction method:

To send a transaction, you need to pass a JSON object as the first argument, containing the transaction info:

./jsonrpc-cli 127.0.0.1:8648 sendTransaction '{"from":"<your address>","to":"<recipient address>","value":<value in Luna>,"fee":<fee in Luna>}'

Note: To send a transaction, your sender account must be unlocked in your node (see section 5.2).

If you only want to create a transaction, but not send it, you can use the createRawTransaction method with the same JSON object as argument. The method returns the signed transaction as a HEX string. You can then send the transaction with the sendRawTransaction method, passing the HEX string as the only argument.

9 RPC Methods

The source code for all RPC methods is in these files: https://github.com/nimiq/core-rs-albatross/tree/albatross/rpc-server/src/handlers

Some helpful methods are documented here:

Method Description
consensus Retrieve the current consensus stake of your node
blockNumber Get the current blockchain head height of your node
epochNumber Get the current epoch your node is in
getBalance "<address>" Retrieve the balance (in Luna) of the address
listStakes Get a list of the current validators and their stakes
listAccounts List all accounts available in your node
peerCount Get the number of connected peers
peerList Get a list of all connected peers and their details
peerPublicKey Get the public peer key from your node
10 Likes

Good post!

I’ll give a try and give you feedback

1 Like

Hi again.

Here I’ve posted my code to use Python as JSON-RPC client:

5 Likes

Do we have an explorer for this?

Great work nevertheless!

Ken Blazer is running an experimental explorer here:
https://albacore.mopsus.com

3 Likes

What are the suggested requirements to running validator node?