Running a Symbol 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.

Note

Symbol Bootstrap runs on all the supported Operating Systems (Windows, Mac and Linux). This guide works out-of-the-box on Ubuntu 20.04 but other Linux distributions might require some adjustments. For instructions specific to CentOS 8 please follow spizzerb’s CentOS 8 guide (developed by a NEM community member).

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!

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 Symbol 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: Search for transactions, accounts, assets, and blocks in the test 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:


Last updated by Xavi Artigas on 2021-10-06.

Did you find what you were looking for? Give us your feedback.