We invite Nimiq’s developer community to test the Albatross Controlled Lab Environment. This setup uses Docker to launch 4 validators in a network, with access to the networking of all four nodes and access to RPC of one node.
Having Rust installed is not required, because the building of the client is also run in Docker.
- Install Docker and be able to run
docker-composecommands on the command line. Tutorials on how to set up Docker on your system are available on the internet
- Git clone, or download, the main branch
albatrossof the Albatross repository: https://github.com/nimiq/core-rs-albatross
- In the repository’s top folder, run the following command to build the Docker image:
docker buildx build -f build_ubuntu.Dockerfile . -t core --progress=plain
This will download the required Docker images for Rust and compile the Albatross client. This will take a few minutes and use the full CPU. You need at least 3GB RAM to complete the compilation!
- To start the lab setup, set the
NETWORK_NAMEenvironment variable to the network name you want to use. Example:
docker-compose upto start the network.
You should see the nodes seed1, seed2, seed3, and seed4 start up, establish connections between them, and then, after a few seconds, start producing blocks.
Stopping, restarting, rebuilding
To stop the network, simply CTRL+C in the terminal where they are running. To reset the state, run
Whenever you change something in the Rust code, you need to rebuild the Docker image with the
docker buildx build ... command from step 3 above and
docker-compose down and then
docker-compose up the network.
Changing only the
docker-compose.yml file does not require a rebuild, but still requires
docker-compose down and
docker-compose up to relaunch the containers.
- The network can most likely not start again from existing state after it was stopped. It works most reliably when starting fresh from the Genesis Block, so when you stopped the network, you need to
docker-compose down && docker-compose upto reset and restart.
- Syncing up to a running network from an external node does not work reliably yet, the team is actively working on that. For now, you need to make do with the existing validators in the setup (or add additional containers that start from the beginning).
Before reporting a new issue, check the issue tracker if somebody already reported it.
Report issues and panics with as much detail (debug output, traces) and reproduction instructions to Github at the above link.
You can connect to the RPC server of seed1. You need to route the hostname
seed1.nimiq.local (use whichever NETWORK_NAME you used) to
127.0.0.1 in your
/etc/hosts file. This is because Traefik, the reverse proxy that the Docker setup uses, routes requests to containers by hostname, so simply using
localhost won’t work.
# In file /etc/hosts ... 127.0.0.1 seed1.nimiq.local
The RPC server is available on port
8648, so point your RPC client to
RPC methods are listed on the RPC interfaces:
Method names are converted to camelCase for the RPC server, so
get_block_by_number becomes the RPC method
RPC via WebSocket
The RPC server also exposes a WebSocket interface, available at
ws://seed1.nimiq.local:8648/ws. The WebSocket server additionally allows you to subscribe to new block hashes via the
headSubscribe method (method name may change).
The server accepts messages in both
binary format - but sends all responses in
You can use any JSON-RPC 2.0 client.
I am maintaining an Albatross RPC command-line client (https://github.com/sisou/arpl) that you can install with:
npm install -g @sisou/albatross-remote # For yarn users: yarn global add @sisou/albatross-remote
arpl help to get an overview of how it works.
The client allows you to import accounts, send and fetch transactions, fetch blocks, start and stop staking and manage validators.
Start a REPL with
arpl --host=seed1.nimiq.local repl.
Genesis Account Keys
Private keys and validator secret keys of all accounts and validators of the genesis block are available in the genesis config:
Send a Transaction
To send a transaction with the
arpl RPC client, these are the commands:
# Start the interactive RPC client arpl --host=seed1.nimiq.local repl # Import one of the genesis accounts > account:import a24591648e20642fe5107d0285c1cc35d67e2033a92566f1217fbd3a14e07abc --unlock # => Account imported: NQ55 X103 EJXG 3S2U 3JNE L779 560T 3LNE 7S60 (unlocked) # Send a transaction > transaction:send \ "NQ55 X103 EJXG 3S2U 3JNE L779 560T 3LNE 7S60" \ # Sender (your unlocked account) "NQ58 VL4Q ALUE CU9N NUEA 1NYU EY6P HDCA 7GUE" \ # Recipient 1000 # NIM # => Transaction sent: <tx hash> # Fetch the transaction > transaction:get <tx hash> # => Shows the transaction object
To start staking with the
arpl RPC client, these are the commands:
# Start the interactive RPC client arpl --host=seed1.nimiq.local repl # If you haven't already, import one of the genesis accounts > account:import a24591648e20642fe5107d0285c1cc35d67e2033a92566f1217fbd3a14e07abc --unlock # => Account imported: NQ55 X103 EJXG 3S2U 3JNE L779 560T 3LNE 7S60 (unlocked) # Send a staking transaction to the staking contract > stake:start \ "NQ55 X103 EJXG 3S2U 3JNE L779 560T 3LNE 7S60" \ # Sender (your unlocked account) 0000000000000000000000000000000000000002 \ # Validator ID of seed2 500 # NIM # => Transaction sent: <tx hash> # Verify that your stake is now listed in the staking contract > stake:list # => You will see that your address is now listed with 500 NIM # as a staker for the ...002 validator
The Docker setup does not include any pool payout logic, so you will not receive any rewards on your address when you stake (delegate) to a validator! Only the validator reward address receives the block rewards.