Olympia to Babylon node migration

Now that the migration to Babylon has completed successfully, mainnet node runners should now simply run the v1.0.3 version of babylon-node, and can avoid needing to follow the steps in this guide.

This page is intended for node runners who already have a running mainnet Olympia node and wish to use it to bootstrap their mainnet Babylon node.

The procedure described on this page allows to participate in the Babylon network as soon as it is possible and is highly recommended for all Olympia node runners. It is especially strongly recommended for all registered validators, and even stronger for the top 100 validators.

There is a timeline at the bottom of this document, describing when certain things will happen in the lead-up to Babylon.

An overview of Babylon network bootstrapping process

Any decentralized ledger requires (among other things) two crucial pieces of information:

  • The initial state of the ledger

  • A set of rules that govern how the state can change

The Radix network (both Olympia and Babylon versions) is no different.

The Olympia network simply started with a predefined initial state (the "genesis transaction"), which included e.g. the initial XRD distribution. Radix Engine V1 is then "a set of rules" that, to this day, drives the ledger state changes.

The Babylon network, on the other hand, does not start with with a predefined state (as in "known at the time of the Babylon node release"). Its ledger is a continuation of the Olympia network ledger. That means that the initial state that Radix Engine V2 (which is the Babylon "set of state changing rules") will use will be the final state of the Olympia network.

From above, we can conclude that:

  • There is a notion of a "final state" of the Olympia network. Or, in technical terms: at some point during the lifetime of the network, the "set of rules" must change so that no more state changes are allowed. Or, in yet another words: at some point the network will shut down and cease to commit any new transactions.

  • The Babylon node must somehow know that Olympia has shut down and must have a way to acquire its final state, which it will then use as its own initial state.

The mechanisms that satisfy both requirements have been implemented in Olympia and Babylon nodes respectively.

Olympia node

The final release of the Olympia node (1.5.0) includes an "engine shutdown" protocol update. This update, once enacted, will configure Radix Engine V1 so that it can’t commit any new transactions. The update will undergo the regular Olympia coordinated protocol updates mechanism.

Also included is a dedicated API server (exposing a single endpoint: /olympia-end-state), separate from the Core API, that the Babylon node will use to query for the final state (and receive it once the shutdown protocol update is enacted).

Babylon node

Babylon node implements a mechanism that allows it to boot in "boostrapper" mode without the initial ledger state. In this mode, the transaction processing engine (Radix Engine V2) remains inactive, as do most of its APIs. Instead, the node periodically queries the configured Olympia end state API. Once the end state is received and processed (to adjust it to the Radix Engine V2 format) the node will fully start automatically. Note that this doesn’t mean that the network will immediately process transactions, this will only happen after at least 2/3 of validators (by stake) have their Babylon nodes fully initialized.

Node configuration

Validators are expected to run their Olympia nodes at least until the shutdown protocol update has been enacted. They’re also expected to have their Babylon nodes running in parallel, ready to pick up as soon as Olympia shuts down.

Note that if you are an active Olympia validator you should USE THE SAME NODE KEY (keystore file) on your Babylon node. Contrary to sharing a single key across multiple Olympia instances, it is perfectly fine to share a single key betwen Olympia and Babylon. Do not use the same key on more than one Babylon node though.

Olympia

  1. Make sure you’re running the latest version of Olympia node, that is: 1.5.0 (available our Github releases page). Those running docker should update to the latest tag radixdlt/radixdlt-core:1.5.0.

  2. Make sure your reverse-proxy (if you’re using one) is configured so that the /olympia-end-state API endpoint is reachable from your Babylon node server via a POST request. The bind address and port for this server (which is separate from the Core API server) can be specified using api.end-state.bind.address/api.end-state.port configuration properties (or RADIXDLT_END_STATE_API_PORT/RADIXDLT_END_STATE_API_BIND_ADDRESS env variables), it defaults to binding to all interfaces (0.0.0.0) on port 3400. Additionally, you should ensure that the proxy can safely handle responses of at least 100 MiB. You can find example configuration for Nginx here. For those running docker, this is already included in the radixdlt-nginx image version 1.3.7 (full tag: radixdlt/radixdlt-nginx:1.3.7) and no additional action is required, other than updating the containers to the latest version. The Babylon node will run regular checks on the connection to ensure it’s safely set up.

  3. Once you have your node set up, signal your readiness for the "olympia-shutdown" protocol update on the Olympia network. If you’re using a babylonnode CLI, here’s a command that does that: babylonnode api core signal-protocol-update-readiness.

You need not set any additional configuration properties on your Olympia node.

Babylon

A final Babylon node version has now been published. You must update your Babylon node to v1.0.0 before the mainnet launch to have a successful switchover.

It is a simple update / binary swap to update to the Babylon node version from rcnet-v3.1-r5 to v1.0.0. See update instructions on the v1.0.0 release notes on Github.

If you’re a registered Olympia validator make sure to use the same node key for your Babylon node as you did for the Olympia node. Only then will you be able to continue participating in the consensus as a validator on the Babylon side.

If you were running a non-validating full node then you can either reuse the same key or generate a new one.

Make sure your node runs with the recommended hardware sepcifications:

CPUs Memory (GB) Storage(GB) Network Bandwidth (Gbps) Operating System

8

16

250 GB of SSD space (initially)

Up to 10

Ubuntu 22.04.2.0 LTS (Jammy Jellyfish)

Also make sure to update the JAVA_OPTS accordingly to use the increased memory. For systemd you will find this setting most likely in /etc/radixdlt/node/secrets/environment:

JAVA_OPTS="... -Xms12g -Xmx12g ..."
...

For docker-compose setup in the docker-compose.yml:

...
services:
  core:
    cap_add:
    - NET_ADMIN
    environment:
      JAVA_OPTS: ... -Xms12g -Xmx12g ...
      mem_limit: 14000m
...

These values can be decreased after the successful migration. The nodecli will default to the increased values to prevent the migration slowing a lot halfway due to memory eviction

Option 1: Use the babylonnode CLI’s migration mode

Ensure you’ve installed and are running the latest version of the babylonnode CLI.

Then, follow the instructions on this page: Configuring a Babylon node for migration from Olympia with the CLI.

Option 2: Manual set-up

  1. Setup a Babylon node using your preferred method (Docker/Systemd) as described on Babylon node setup page.

  2. Make sure to have configured your node for mainnet, and then make sure to set the following migration-specific configuration properties:

network.id=1
network.p2p.seed_nodes=radix://node_rdx1qf2x63qx4jdaxj83kkw2yytehvvmu6r2xll5gcp6c9rancmrfsgfw0vnc65@52.212.35.209,radix://node_rdx1qgxn3eeldj33kd98ha6wkjgk4k77z6xm0dv7mwnrkefknjcqsvhuu4gc609@54.79.136.139,radix://node_rdx1qwrrnhzfu99fg3yqgk3ut9vev2pdssv7hxhff80msjmmcj968487uugc0t2@43.204.226.50,radix://node_rdx1q0gnmwv0fmcp7ecq0znff7yzrt7ggwrp47sa9pssgyvrnl75tvxmvj78u7t@52.21.106.232

# This allows the Babylon node to boot without the initial ledger state and
# configures it to use the Olympia node as an (asynchronous) initial state source.
genesis.use_olympia=true

# The URL of your Olympia End State API - use the root URL,
# without a trailing slash (specifically, it should not include the "/olympia-end-state" path).
# The certificate (if using https) doesn't need to be valid - a self-signed certificate will work
# without any additional configuration. This does not impose any risk - the response itself contains
# a signature and is always validated before processing (see "genesis.olympia.node_bech32_address" below).
genesis.olympia.node_end_state_api_url=https://127.0.0.1:3400

# These are optional, and only need to be specified if you're using a reverse-proxy
# (e.g. nginx, which the Node CLI sets up for you) with basic auth to protect your Olympia End State API.
genesis.olympia.node_end_state_api_auth_user=<only-set-if-using-proxy>
genesis.olympia.node_end_state_api_auth_password=<only-set-if-using-proxy>

# This is a Bech32 address of your Olympia node,
# which you can read from the "/system/configuration" endpoint.
# Note that it is different from the address of your Babylon node,
# even though they're derived from the same underlying key!
# The Babylon node uses it to verify that the end state response hasn't been tampered with.
# Also note that this is the "node address", not the "validator address" (it should start with "rn1q").
genesis.olympia.node_bech32_address=rn1q....

Verify the configuration

After setting up both Olympia and Babylon nodes you should verify your setup by checking the following:

  • The /engine/configuration response from your Olympia Core API should include a shutdown protocol update (aka "fork"): "olympia-shutdown". Example command: curl -X POST https://127.0.0.1:3333/engine/configuration \ --data '{"network_identifier": {"network": "mainnet"}}' | jq '.forks[] | .name'.

  • Your Babylon node should be successfully connected to your Olympia node. It should print a message that starts with "Successfully connected to the Olympia node…​" at regular intervals, and at least one such message that includes a (received 100 MiB test payload) phrase.

  • On your Babylon node, a GET call to your /system/version API returns { "version": "v1.0.0" }.

  • If you’re an active validator, don’t forget to signal your readiness for the "olympia-shutdown" protocol update. You can verify that your signal has been correctly recorded by querying the /system/health API. The response should include a fork_vote_status of NO_ACTION_NEEDED.

Migration timeline/summary

This section outlines a timeline for Olympia to Babylon network migration. The steps that Node Runners should take have been highlighted.

  1. ☑ 24th August 2023:

    • The Radix team releases an Olympia node version 1.5.0, which includes the "olympia-shutdown" protocol update

    • Node Runners update their Olympia nodes to 1.5.0 and configure them as described on this page (making sure the /olympia-end-state API is accessible)

    • Node Runners (registered validators only) signal their protocol update readiness on the Olympia network, using their 1.5.0 node (for example using the radixnode api core signal-protocol-update-readiness command). See this page about coordinated protocol updates for more information.

  2. ☑ Thursday 31st August 2023:

    • The Radix team releases the RCnet v3 Babylon node

    • [OPTIONAL] Node Runners may choose to get involved with the second Stokenet migration to test their setups.

  3. ☑ Friday 15th September 2023:

    • The Radix team releases clear instructions for setting up a mainnet Babylon node. Please note that this will not be the final version, and there will be a required update on Friday 22nd September 2023.

    • Node Runners setup their Babylon mainnet nodes as described on this page (specifically the genesis.* configuration)

    • Node Runners should verify that the communication channel between their Babylon node and their Olympia node works correctly. This can be done by inspecting the logs on the Babylon node (look for "Successfully connected to the Olympia node…​" and verify that there are no other warnings/errors)

  4. ☑ Friday 22nd September 2023:

    • The Radix team releases the v1.0.0 mainnet Babylon node version, and communicate that clearly on Discord.

    • Node Runners must update their babylon node to this version. This update will be a simple binary swap.

    • Node Runners after this announcement should double check that they are running the latest Olympia node version (1.5.0) and the latest Babylon node version.

    • Node Runners (registered validators only) should double-check they have correctly signalled readiness for the Olympia-end protocol update.

    • The Radix team will reset the Babylon stokenet environment with a new ledger, running the mainnet Babylon node version, and ask any community node runners running stokenet nodes on Babylon to also reset. This environment can be used for testing and deploying dApps against a mainnet-compatible network in the run-up to mainnet launch.

  5. ☑ Mainnet Epoch 32718 (likely some time between 27th and 29th September):

    • The "olympia-shutdown" protocol update will be enacted at a target epoch of 32718 (provided that enough validators have signalled their readiness at this time) and the Olympia network will cease to process transactions

    • Once that happens Node Runners should verify that their Babylon node have acquired the initial (genesis) state from the Olympia node and that it has been processed (look for "Radix node <address> started successfully…​" in the logs). Note that the processing may take some time (it shouldn’t take more than 30 minutes)

    • Until a quorum of validators (>2/3 by stake) have their Babylon nodes initiated, the node will keep issuing consensus timeouts (again, inspect the logs) - this is expected and indicates that the node has been correctly initialized.

    • Once the quorum of validators have their Babylon nodes initiated, the Babylon network will become live (no more consensus timeouts) and will start processing transactions.

  6. ☑ Shortly after the switchover, the Radix team will release an updated node version, with a hard-coded genesis file for mainnet, allowing node runners who haven’t done the automated switchover to run this version. This is version v1.0.3.