Running a node

This guide walks you through the process of setting up a node to join Symbol’s public network.

You can safely experiment connecting to Symbol’s network by connecting to the test network (testnet) instead of the main public network (mainnet). Testnet might be offline or replaced without notice because it is used extensively for testing purposes, though. To work in a private environment network, install a local network for learning and development purposes instead.

To run the network, you are going to use the package Symbol Bootstrap. To better understand how this package works it is highly recommended to read the Using Symbol Bootstrap guide.

Hardware requirements

Running a blockchain node is very demanding in terms of disk space, memory and CPU requirements. Failure to meet the following minimum requirements will produce a node that will struggle to keep up with the rest of the network. The global blockchain will not be affected but the node will rarely be eligible to collect any node rewards.

Note

It is strongly recommended to use dedicated CPU and RAM. When they are shared (as is the case on some Virtual Server providers) performance is heavily impacted.

Minimum node specifications
Requirement	Peer node	API node	Dual & Voting node
CPU	2 cores	4 cores	4 cores
RAM	8GB	16GB	16GB
Disk size	500 GB	750 GB	750 GB
Disk speed	1500 IOPS SSD	1500 IOPS SSD	1500 IOPS SSD

The following table shows the recommended requirements. Using these will provide a much smoother experience and provide a certain degree of future proofing.

Recommended node specifications
Requirement	Peer node	API node	Dual & Voting node
CPU	4 cores	8 cores	8 cores
RAM	16GB	32GB	32GB
Disk size	500 GB	750 GB	750 GB
Disk speed	1500 IOPS SSD	1500 IOPS SSD	1500 IOPS SSD

The `testnet` and `mainnet` presets

Symbol Bootstrap has presets called testnet and mainnet which instantiate a node that connects to the appropriate public network. The particular capabilities of this node are selected through the assembly option.

This guide uses testnet as an example but feel free to change it to mainnet.

To create a peer node:

Peer nodes, also called a harvester nodes, are the backbone of the network. Among other things, they verify transactions and add new blocks to the blockchain, collecting fees in the process.

symbol-bootstrap start -p testnet -a peer

To create an API node:

API nodes provide external access to the network through a REST API.

symbol-bootstrap start -p testnet -a api

To check that the node is up and running open a new browser tab and go to localhost:3000/chain/info. You should get a response from the API node.

API nodes take up more memory and storage than Peer nodes. If you have memory or storage constraints and you are running into issues, it is recommended that you switch to running a Peer only node instead.

To create a dual node:

Dual nodes provide the functionality of both Peer and API nodes.

symbol-bootstrap start -p testnet -a dual

Running the node

You really don’t need to use anything else but symbol-bootstrap start. Use any of the commands above to instantiate and boot a Symbol node and Ctrl+C to shut it down.

Alternatively, you can start in detached mode (--detached) to run in the background.

Note

Upon first launch the node will synchronize with the rest of the network, downloading the complete blockchain. This might take a few hours and during this time REST requests directed to your node (if it is an API node) might be delayed and report an incorrect chain height.

Retrieving the node account

The node you just created has an associated Symbol account which you can use to interact with the node. For instance, you need this account to provide funds to the node so it can emit transactions.

The account’s keys and addresses can be retrieved from a text file in the target folder named target/addresses.yml.

This file has YAML format and looks like this:

networkType: 152
nemesisGenerationHashSeed: 1082491EFE93AA7DAC6D0282634953DB8B5FDDAE669237B030695A9F308883D5
nodes:
    -
        name: peer-node-0
        friendlyName: peer-node-0
        roles: 'Peer,Voting'
        main:
            # Use these to access the node's account
            privateKey: ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
            publicKey: E8A918BD78C0D9CFA8D0B53BB721E62925ACB4BF92068533A3D94210D01E1D39
            address: TBMXGFREJRVWJY756BVHLJAHZCOP3BW53ALFYOY
        transport:
            # Use these in Delegated Harvesting requests
            privateKey: ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
            publicKey: 7C63AF4CECE2690944FAFE3D9D52EB400447F30CCAC185BC9BE5D54CF536DDE3
            address: TBTRVMCJ7TEZNCV74IX3INJHGAOLMQOU2JQEX7Y
        remote:
            privateKey: ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
            publicKey: 6B1936560F85096E398AAF4647EADB6C748100E6D248D98B2916F003B806E725
            address: TDN3G4REJA7BWDQ2TLB3M522RAYKV5AB55EEPGQ
        voting:
            privateKey: ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
            publicKey: E97B99E7EDE0738CBE2C3BB13F3B0EEB8A361FAAD51271887D12389F1AEEF4EC
            address: TBBK644JF2XMW35A7BUG6SADTLHAQ2M2KO7O2FQ
        vrf:
            privateKey: ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
            publicKey: B304E6F9650CFFA52C6DC51CED29397F6C50F1E2F9AC34993549E0E3E4461027
            address: TABWAGQNSI4AWPE3IVGS53CQWAN5BYRM5BHMNFA

Use the information in the main section to access the node’s account. When activating delegated harvesting, use the information in the transport section as the node’s public TLS key.

Encrypted private keys

By default Symbol Bootstrap encrypts all private keys in addresses.yml so they are not visible (see the security mode section for more details).

To access the private keys (to withdraw funds from the main account, for example) you will need to use the symbol-bootstrap decrypt command:

symbol-bootstrap decrypt \
   --source target/addresses.yml \
   --destination target/addresses_plain.yml

This will produce a target/addresses_plain.yml file with the decrypted keys.

⚠️ Delete this file after reading the keys!

⚠️ Keep your Secret Keys secret at all times!

Providing funds to the node

Before the node can begin harvesting or voting (see below) it needs a minimum amount of funds. In the testnet test environment you can use Symbol’s Faucet to provide these funds.

Go to faucet, insert the address of your node’s account and the amount of symbol.xym you need and click on CLAIM.

You will see that your request is first unconfirmed (pending) and after a few seconds it becomes confirmed. Your node is now funded and ready to operate!

Submitting link keys

Harvesting and Voting nodes require an extra configuration step before they can be used:

Enabling harvesting

Symbol Bootstrap creates peer nodes with remote harvesting enabled by default, but they still need to be registered by announcing the AccountKeyLinkTransaction and VrfKeyLinkTransaction to the network.

This can be done by Symbol Bootstrap too, but it needs to be a step separated from symbol-bootstrap start because funds are required to announce transactions.

Once the node is running with symbol-bootstrap start and you have funded its account, from a different terminal (but from the same folder), simply type:

symbol-bootstrap link

This creates the required VrfKeyLinkTransaction transactions and announces them to the network. If it succeeds (it might take some seconds, as the transaction needs to be confirmed) your new node is ready to harvest.

Note

Without extra parameters, symbol-bootstrap link tries to send the registration transaction to the local node (running on the other terminal) which will forward it to the rest of the network. If your node is not running at this moment, or it is not an API node, you can use the --useKnownRestGateways parameter, or provide the URL of another node using --url (use the Symbol Explorer to find the list of current nodes in testnet or mainnet).

Enabling voting

The block finalization process requires that some network nodes vote about the correctness of blocks before they are definitely added to the blockchain. For your new node to participate (and collect voting rewards) it has to register as a voter by announcing a VotingKeyLinkTransaction to the network. Symbol Bootstrap can take care of this too.

Note

We are going to create a new voting node. If you already created a non-voting node which you no longer need, you can remove the target folder or, more conveniently, use the --reset switch next time you invoke symbol-bootstrap.

First, you need to configure the node as a voter, so, besides selecting the desired preset and assembly you have to provide a custom preset file with the following content:

nodes:
- voting: true

So if you call the above file enable-voting-preset.yml the whole command would be:

symbol-bootstrap start -p testnet -a <assembly> -c enable-voting-preset.yml

Once the node is running, from a different terminal (but from the same folder), simply type:

symbol-bootstrap link

Just like in the harvesting case, this creates the required VotingKeyLinkTransaction and submits it to the network. Upon successful completion, your new node is ready to vote.

Voting key renewal

For security reasons voting keys have a maximum validity of 6 months. This means that every 6 months you need to renew your voting keys.

Again, Symbol bootstrap takes care of this. You just need to run these commands one month before the keys expire from the same folder where you initially ran symbol-bootstrap start (there is no need to stop the client):

symbol-bootstrap updateVotingKeys
symbol-bootstrap link

The current keys will be examined and if any is close to expiration it will be renewed. If no action is needed the link command will do nothing, so no transaction fees will be paid (see Symbol Bootstrap’s manual for more information).

Therefore, running the above commands once a month guarantees that your voting keys will always be up to date.

⚠️ If you fail to renew on time your node will stop voting. Your account will not receive any voting reward until your keys are renewed.

Running a secure node

It is possible to setup a node in such a way that the private keys are never stored in plain text on a computer connected to the Internet. Read about it in the Running a secure node.

Configuring node properties

Follow the Configuring node properties guide to change parameters such as the public name of the node.

Interacting with the network

You can use the following tools to test the functionality of your new node:

Blockchain Explorer (MAINNET and TESTNET): Search for transactions, accounts, assets, and blocks in the network.
Desktop Wallet: Cross-platform client for Symbol. Available for Mac, Linux, and Windows.
Command-Line Interface: Execute the most commonly used actions from your terminal.
The Symbol faucet: Receive symbol.xym units to test Symbol’s services.

Next steps

Now that your node is up and running, you can take a look at the following guides:

Navigation

Running a node

Hardware requirements

The testnet and mainnet presets

To create a peer node:

To create an API node:

To create a dual node:

Running the node

Retrieving the node account

Providing funds to the node

Submitting link keys

Enabling harvesting

Enabling voting

Running a secure node

Configuring node properties

Interacting with the network

Next steps

The `testnet` and `mainnet` presets