Registering a Validator Node

Introduction

A Validator node is a Full Node that has registered with the Radix network to receive delegated stake and potentially be selected to participate in network consensus.

Validator nodes provide the critical infrastructure of the Radix network and may receive special incentive rewards as a result. However attempting to become one of the network’s 100 validator nodes is not a decision to be taken lightly, requiring commitment to high reliability operation and engagement with the Radix community. Registration as a validator node alone does not guarantee participation in consensus or that you will receive incentive rewards.

Once running, a validator node offers two interface endpoints on a private port:

The /node endpoint can be used to conduct transactions from the node’s account, including validator configuration, registration, and de-registration. The node’s account must hold XRD tokens to pay for network fees on these transactions.

The /system endpoint can be used to query aspects of the node and network such as current version, current peers, etc.

Prerequisites

To register a validator node, you need a Radix full node installed, running, and syncing with the network. If you haven’t yet set one, then please run through one of these guides:

1. Register the node as a validator

We’re using Amazon Web Services throughout our example, but you can install Radix nodes on any cloud service that supports Java, such as Google’s cloud platform or Microsoft Azure – or follow similar step to deploy on a private server.

There are four steps to register your node to take part in validation:

1.1. Get your node’s wallet address.

Execute the following command to fetch node address.

curl -d '{ "jsonrpc": "2.0", "method": "account.get_info", "params": [], "id":1}' -H "Content-Type: application/json" -X POST -u superadmin:nginx-password -k  "https://localhost/account"

This will return some basic information about your Radix instance:

{"result":{"address":"rdx1qspl7mgjqwgwqyjvy2tj8swe8a4lr6mxqdhwmn60cujl6a85mqh69eg37p9ph","balance":{"stakes":[],"tokens":[]}},"id":1,"jsonrpc":"2.0"}

The address field is the one you’re interested in: this is the node’s "wallet" address.

1.2. Send XRD tokens to your node

Use your Radix Desktop Wallet to send tokens to the node’s address. These XRD will be used by the node to pay any transaction fees, such as for the transaction that you will submit to register your node as a validator. Registration and update transactions will cost up to 30 XRD in transaction fees. (This is higher than typical token send transactions due to the requisite processing at the epoch’s end for these types of validator transactions.)

1.3. Get the node’s validator address

As well as a regular wallet address, nodes also have a validator address used for registration and setting the validator’s parameters (more on this later). Before you can register the node, you need to find its validator address using the following curl statement.

curl -d '{"jsonrpc": "2.0", "method": "validation.get_node_info", "params": [], "id": 1}' -H "Content-Type: application/json" -X POST -u admin:nginx-password -k "https://localhost/validation"

The node’s validator address will be returned as part of the message:

{
  "result": {
    "owner": "rdx1qspl7mgjqwgwqyjvy2tj8swe8a4lr6mxqdhwmn60cujl6a85mqh69eg37p9ph",
    "address": "rv1qthu8yn06k75dnwpkysyl8smtwn0v4xy29auzjlcrw7vgduxvnwnsnf8f0v",
    "stakes": [],
    "allowDelegation": true,
    "name": "",
    "validatorFee": 0,
    "registered": false,
    "totalStake": "0",
    "url": ""
  },
  "id": 1,
  "jsonrpc": "2.0"
}

Validator addresses are prefixed with rv.
Regular node addresses are prefixed with rdx.

1.4. Call endpoint to register the node as a validator

Make the following call to your node’s account API endpoint to create the transaction to register it as a validator (example parameters shown):

curl -s -u superadmin:nginx-password -X POST -k 'https://localhost/account' -H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0","method": "account.submit_transaction_single_step",
  "params":
  {"actions": [
    {"type": "RegisterValidator",
      "validator": "rv1qthu8yn06k75dnwpkysyl8smtwn0v4xy29auzjlcrw7vgduxvnwnsnf8f0v"},    (1)
    {"type": "UpdateValidatorFee",    (2)
      "validator": "rv1qthu8yn06k75dnwpkysyl8smtwn0v4xy29auzjlcrw7vgduxvnwnsnf8f0v",
      "validatorFee": 2},
    {"type":  "UpdateValidatorMetadata",
      "validator": "rv1qthu8yn06k75dnwpkysyl8smtwn0v4xy29auzjlcrw7vgduxvnwnsnf8f0v",
      "name": "My Validator",    (3)
      "url":  "https://my-validator.com"},    (4)
    {"type": "UpdateAllowDelegationFlag",
      "validator": "rv1qthu8yn06k75dnwpkysyl8smtwn0v4xy29auzjlcrw7vgduxvnwnsnf8f0v",
      "allowDelegation": true},    (5)
    {"type": "UpdateValidatorOwnerAddress",
      "validator": "rv1qthu8yn06k75dnwpkysyl8smtwn0v4xy29auzjlcrw7vgduxvnwnsnf8f0v",
      "owner": "rdx1qthu8yn06k75dnwpkysyl8smtwn0v4xy29auzjlcrw7vgduxvnwnst6derj" }    (6)
  ]}, "id": 1}'

This registration call takes a number of parameters that specify details about your validator node. Most of these are optional: if you don’t specify them, system details will be used. However, it is highly recommended that you fill in all parameters.

All of these details on your validator node will be displayed for the benefit of the staking public in the Radix Explorer.

1 validator: the node’s validator address.
2 validatorFee: A percentage of the total emissions XRD earned by stakers to your node, which is continuously deducted and credited to your specified owner address as your node’s fee for operation. Setting the fee to 0% means the validator node takes none of the emissions fees earned by the node’s delegators.
The validator fee may be specified to up to two decimals of precision. e.g. 1 or 1.75 are valid, but the API will truncate 1.2345 to 1.23.
3 name: the public name of your node.
4 url: a URL that points to a webpage about your node.
5 allowDelegation: Setting this to true will allow others to delegate stake to your node. Setting it to false means that only new stake from your specified owner address will be accepted. The flag defaults to false when the node is initially registered.
6 owner: The wallet address where any validator fee emissions XRD will be credited. If you are disallowing external delegation, then this is also the only address that may stake to your node.

For more detailed information on earning XRD emissions and the limits and usage of the above parameters, please refer to the Validators and Node-runner Incentives page.

If the registration transaction is successful, the node will return the transaction details:

{
    "result": {
        "txID": "26b4afc018f106d23f4bcd9d9f5560b513fa3bbe7c3d4525349b824680d9376b"
    },
    "id": 1,
    "jsonrpc": "2.0"
}

And that’s it. Your node is now registered as a validator.

While your node is registered immediately, it will not be considered for inclusion in the validator set (based on the amount of stake delegated to it) until the beginning of the next epoch.

2. Confirm the node’s registration

To confirm your node’s registration, you can use the node’s validation API endpoint, which will give you the node’s current validator information.

curl -d '{"jsonrpc": "2.0", "method": "validation.get_node_info", "params": [], "id": 1}' -H "Content-Type: application/json" -X POST -u admin:nginx-password -k "https://localhost/validation"

You should receive a response that looks something like this:

{"result":{"owner":"rdx1qthu8yn06k75dnwpkysyl8smtwn0v4xy29auzjlcrw7vgduxvnwnst6derj","address":"rv1qthu8yn06k75dnwpkysyl8smtwn0v4xy29auzjlcrw7vgduxvnwnsnf8f0v","stakes":[],"validatorFee":0,"name":"My Validator","registered":true,"totalStake":"0","url":"https://my-validator.com","allowsDelegation":true},"id":1,"jsonrpc":"2.0"}

3. Update the Validator’s settings

Section 1, “Register the node as a validator” demonstrated a block of actions that can be used to register the node and set its parameters in the same REST transaction. The same method can be used to update the parameters individually (or again, as a block of actions).

3.1. Change the validator’s name or URL

To change the validator’s name or URL, simply call the registration method again with the new settings:

curl -s -u superadmin:nginx-password -X POST -k 'https://localhost/account' -H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0","method": "account.submit_transaction_single_step",
"params":
{"actions": [
{"type": "UpdateValidatorMetadata",     (1)
"validator": "rv1qthu8yn06k75dnwpkysyl8smtwn0v4xy29auzjlcrw7vgduxvnwnsnf8f0v",
"name": "New validator name",
"url": "https://new-validator-url.com"}
]}, "id": 1}'
1 Use the UpdateValidatorMetadata action to change the name and/or URL. You change either or both settings in the same call.

3.2. Change owner, validator fee and owner delegation flag

There are a number of calls that you can use to change the other settings on your validator node:

  • change owner address

  • change validator fee

  • change allow delegation flag

curl -s -u superadmin:nginx-password -X POST -k 'https://localhost/account' -H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0","method": "account.submit_transaction_single_step",
"params":
{"actions": [
{"type": "UpdateValidatorOwnerAddress",
"validator": "rv1qthu8yn06k75dnwpkysyl8smtwn0v4xy29auzjlcrw7vgduxvnwnsnf8f0v",
"owner": "rdx1qthu8yn06k75dnwpkysyl8smtwn0v4xy29auzjlcrw7vgduxvnwnst6derj" },
]}, "id": 1}'
curl -s -u superadmin:nginx-password -X POST -k 'https://localhost/account' -H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0","method": "account.submit_transaction_single_step",
"params":
{"actions": [
{"type": "UpdateValidatorFee",
"validator": "rv1qthu8yn06k75dnwpkysyl8smtwn0v4xy29auzjlcrw7vgduxvnwnsnf8f0v",
"validatorFee": 2},
]}, "id": 1}'
curl -s -u superadmin:nginx-password -X POST -k 'https://localhost/account' -H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0","method": "account.submit_transaction_single_step",
"params":
{"actions": [
{"type": "UpdateAllowDelegationFlag",
{"validator": "rv1qthu8yn06k75dnwpkysyl8smtwn0v4xy29auzjlcrw7vgduxvnwnsnf8f0v",
"allowDelegation": true},
]}, "id": 1}'

Remember, you can combine multiple actions in the same request, as shown in Section 1.4, “Call endpoint to register the node as a validator”

4. Unregister the validator

You can unregister your validator node at any time, switching it back to a full or archive node:

curl -s -u superadmin:nginx-password -X POST -k 'https://localhost/account' -H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0","method": "account.submit_transaction_single_step",
"params":
{"actions": [
{"type": "UnregisterValidator",     (1)
"validator": "rv1qthu8yn06k75dnwpkysyl8smtwn0v4xy29auzjlcrw7vgduxvnwnsnf8f0v"},
]}, "id": 1}'
If you have delegates signed on to your validator node, then you must inform them before you unregister the node.