Getting started with the Albatross Alpha Testnet

Documentation Community Tutorials
#1

: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. Inactivate and Unstake
  8. Send a Transaction
  9. RPC Methods

Note
For consistency purposes, we display the data types commands as an example, such ./jsonrpc-cli 127.0.0.1:9100 getValidatorByAddress '{"address": "<address>"}’. The accurate data should look like the following:

  • '{"address": "NQ16 LEK4 D4AE 80YS DS1N Q7PK 63PU AYVB GGVF"}'
  • '{"wallet": "NQ16 LEK4 D4AE 80YS DS1N Q7PK 63PU AYVB GGVF"}'
  • '{"signing_secret_key": "88791c723c7bb4ce5701a2e6b9ad93930e1800d72dddeb054e6d8a74ae50ceef"}'
  • '{"voting_secret_key": "cceb56e6248800b690d4e1e0caa70fff5b2c0af8ea5cb1cea1a8ba26a574432eee8996e0ba3fc895447bab5445890731fb9bb8182bc4cfe97f43f774798aae4582c26549aa562bea5b6d123cc5ab778d5f0b3c1c91b7acd2d4f6a85b676f0000"}'
  • '{"key_data": "8f7f4725b5b4b730f12cdd7d348ad4eb6157890ff689c70a1d0eba970c04db93"}'
  • '{"validity_start_height": "6789"}'
  • '{"value": 100}'
  • '{"fee": 2}'

Value and fees are returned in Luna.

1 Setup

1.0 Prerequisites

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

Fedora:

sudo dnf install openssl-devel

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 stable version of Rust and make it the default by running:

rustup install stable
rustup default stable

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

2 Run the Client

2.1 Build

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

mkdir ~/.nimiq

# Go into the repository directory:
cd core-rs-albatross

# Cargo will take care of everything:
cargo run --release --bin nimiq-client

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 configuration file in in your home directory in the ~/.nimiq/ folder. Then the client will exit because you don’t have a configuration yet.

2.2 Configure

You need to copy ~/.nimiq/client.toml.example to ~/.nimiq/client.toml. You can leave all configuration options as they are for now to start a full history 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.Check if the #[rpc-server] => [rpc-server] is uncommented around line 123.

2.3 Sync the Blockchain

After you finished your configuration, simply rerun the client from inside the core-rs-albatross directory with cargo run --release --bin nimiq-client. It will connect to the seed node, then to the other nodes in the network, and finally start syncing to the blockchain. Since only the full history sync is available 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 quite some time. 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 configuration, 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 user-friendly 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:9100 -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"isConsensusEstablished","id":0}'

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

If you sync successfully, the response you’ll get is {"jsonrpc":"2.0","result":true,"id":0}, otherwise you’ll get a false response {"jsonrpc":"2.0","result":false,"id":0}.

3.2 arpl

Check this repository README for instructions on using the remote management for Nimiq Albatross nodes.

3.3 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:9100 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:9100 createAccount '{"null": []}'
# or
./jsonrpc-cli 127.0.0.1:9100 createAccount '{"passphrase": "MyPassphrase"}'

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:9100 importRawKey '{"key_data": "<String>", "passphrase": "MyPassphrase"}'
# or
./jsonrpc-cli 127.0.0.1:9100 importRawKey '{"key_data": "<String>"}'

The address of the imported account is returned.

4.3 Check your Balance

./jsonrpc-cli 127.0.0.1:9100 getAccountByAddress '{"address": "<address>"}'

Your current balance is returned as a field in the returned account, as in this example:

{
    "address": "NQ16 LEK4 D4AE 80YS DS1N Q7PK 63PU AYVB GGVF",
    "balance": 1000296575553,
    "type": "basic"
}

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: createNewValidatorTransactions. It takes these arguments:

  • validator_address: Your identifier address
  • sender_address: NIM address used to create this transaction
  • signing_key: Public key of the validator (Schnorr)
  • voting_key: Public key of the validator (BLS)
  • reward_address: NIM address used for the reward
  • signal_data: Optional field used by validator for consensus coordination
  • fee: Fee for the transaction in Luna
  • validity_start_height: The validity window of a transaction

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] configuration, your node created your validator key as ~/.nimiq/validator_key.dat. You can query it in HEX format with

  1. Use the following command to get the validator address:
./jsonrpc-cli 127.0.0.1:9100 getAddress '{"null": []}'
  1. Use the response to get the data of your validator with the following command:
./jsonrpc-cli 127.0.0.1:9100 getValidatorByAddress '{"address": "<address>"}'

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:9100 unlockAccount '{"address": "<address>"}'
# or
./jsonrpc-cli 127.0.0.1:9100 unlockAccount '{"address": "<address>", "passphrase": "MyPassphrase"}'

5.3 Send Validator Transaction

Finally, we become a validator:

./jsonrpc-cli 127.0.0.1:9100 sendNewValidatorTransaction '{"sender_wallet": "<address>", "validator_wallet":"<address>", "signing_secret_key": "<SchnorrPublicKey>", "voting_secret_key": "<BlsPublicKey>", "reward_address": "<address>", "signal_data": "", "fee": Coin, "validity_start_height": "u32"}'

After you send this command and the transaction gets accepted (the 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 balance 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 validator’s stake, increasing their likelihood of becoming a block producer. Note that all block rewards are received by the validator’s reward address, not yours. The arrangement of distributing rewards among stakers is made off-chain.

./jsonrpc-cli 127.0.0.1:9100 sendNewStakerTransaction '{"sender_wallet": "<address>", "staker_wallet":"<address>", "value": Coin, "fee": Coin, "validity_start_height": "u32"}'
# or
./jsonrpc-cli 127.0.0.1:9100 sendNewStakerTransaction '{"sender_wallet": "<address>", "staker_wallet":"<address>", "delegation": "<address>", "value": Coin, "fee": Coin, "validity_start_height": "u32"}'

7 Inactivateand Unstake

7.1 Inactivate your Validator

Inactivates the validator.

./jsonrpc-cli 127.0.0.1:9100 sendInactivateValidatorTransaction '{"sender_wallet": "<address>", "validator_address":"<address>", "signing_secret_key": "<SchnorrPublicKey>", "fee": Coin, "validity_start_height": "u32"}’

7.2 Unstake delegated Stake

Removes stake from a staker’s address via RPC.

./jsonrpc-cli 127.0.0.1:9100 sendUnstakeTransaction '{"staker_wallet": "<address>", "recipient": "<address>", "value": Coin, "fee": Coin, "validity_start_height": "u32"}’

8 Send a Transaction

To send a transaction, you can use the sendBasicTransaction 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:9100 sendBasicTransaction '{"wallet":"<address>", "recipient": "<address>", "value": Coin, "fee": Coin, "validity_start_height": "u32"}'

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 createBasicTransaction 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: core-rs-albatross/rpc-server/src/dispatchers at albatross · nimiq/core-rs-albatross · GitHub (multiple files containing different RPC commands can be found in this directory).

Some helpful methods are documented here:

Method Description
isConsensusEstablished Retrieve the current state of your node
getBlockNumber Get the current blockchain head height of your node
getEpochNumber Get the current epoch your node is in
getAccountByAddress "<address>" Get the balance returned as a field of returned data
getValidatorByAddress Get a list of the current validators and their stakes
listAccounts List all accounts available in your node
getPeerCount Get the number of connected peers
getPeerList Get a list of all connected peers and their details
getPeerId Get the peer ID from your node
11 Likes
#2

Good post!

I’ll give a try and give you feedback

1 Like
#3

Hi again.

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

https://github.com/aitorp6/nimiq_rpc_class

5 Likes
#4

Do we have an explorer for this?

Great work nevertheless!

#5

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

3 Likes
#6

What are the suggested requirements to running validator node?