This guide will show you how to run a
bifrost node on your system and some simple examples of how you can interact with the Topl blockchain.
This guide assumes that you have installed
bifrostonto your system. If not, you can refer to Installing Bifrost guide for instructions on how to do that.
bifrost application has 3 network configurations to run as of writing this article.
- Mainnet: The settings that are used on the main Topl network.
- Valhalla: The settings that are used on the main public Topl testnet.
- Private: The settings that are used by Bifrost developers while working on improving Bifrost functionality
You might be asking what the difference is between
valhalla and why there are two networks? To put it simply, Topl is an open-source blockchain and anyone is free to spin up a network based on Topl's software components. The
mainnet network was the first one and currently contains all of the real value of Topl.
Testing the network's features and capabilities can be expensive and will consume real value. So we have spun up a sandbox or testnet version of the network. Instead of using real
poly tokens for transactions, you use test polys. Alternatively, you can spin up your own custom Topl network, but that is outside the scope of this guide.
bifrost you enter something like this into the terminal (given that you are in the directory containing the bifrost jar file):
java -jar bifrost-1.x.x.jar \ --config path/to/config.json \ --seed "test" \ --forge \ --disableAuth
To get the complete list of available options, use `java -jar bifrost-1.x.x.jar --help
-c --config <str> file path to a user defined config file -d --debug Turn on debugging information -n --network <network> specify preset network by name -s --seed <str> string to deterministically generate keys on private and local networks -f --forge enable forging as soon as the node starts --disableAuth Allow the node to receive API requests without an API key --apiKeyHash <str> hash of API key --help prints this command list
In this section, we will use the path
/home/user/toplto store all the
bifrostrelated configuration files as an example, and please replace it with the directory you have chosen to store the files.
We will focus on the 7 key command-line parameters for running a node:
--config : This requires the path of the
For example, if you have created a
<CUSTOM>.conffile to the path
/home/user/topl/custom.conf, then the argument would look like this
--debug: This command line parameter turns on the debugging information for the Bifrost node.
--network: This expects one of the predefined config networks as an argument.
Here is an example
This will begin the Bifrost node running with the Valhalla parameters.
--seed : This expects a string to deterministically generate the keys for the genesis addresses on private and local networks. This is used primarily so that the user will have access to the polys and arbits that are attributed upon the genesis of the network.
--forge : This does not expect an argument and will start the node forging immediately after it starts.
--disableAuth : This command line argument disables the api_key authentication allowing you to connect with your node over HTTP without configuring an API key
--apiKeyHash : With this command you can provide a Base58 encoded hash of the value that you want to use for the apiKey. This allows for you to construct a more secure node that will require the apiKey for successful HTTP connections.
In addition, let's look at some of the more important parameters that you can modify using a custom configuration file:
bifrost.application.dataDir: This expects the path to the directory where we will store the actual blockchain data like blocks, transactions, and other datatypes that can be stored on the Topl blockchain.
For example, if we decided that all of the files required by the
bifrostnode will be in the path
/home/user/topl/. Then we could create a database directory like this
mkdir -p /home/user/topl/db.
The directory structure would then be something like this:
/home/user/topl/ ├── db ├── config.conf 1 directory, 2 files
bifrost.application.rpcApi.bindAddress: In this case, this expects the
local address of the machine to which to bind to.
Here is an example
bindAddress = "0.0.0.0:9085"
In this case, we expect http clients in your network to connect via
0.0.0.0:9085. In conjunction with providing the
local addressthis command also sets the port that your
bifrostnode will use to listen to any incoming connections.
Here is a realistic example for running
java -jar bifrost-1.3.3.jar \ --config /home/user/topl/customtestnet.conf \ --debug \ -- seed "test" \ -- forge \ -- disableAuth
If you have everything set correctly, you should see something similar to the following
20:44:17.131| INFO co.topl.settings.AppSettings$ - No network specified, running as private testnet. 20:44:17.748| INFO co.topl.network.NetworkController - Declared address: None 20:44:17.805| INFO co.topl.network.NetworkController - Registered Actor[akka://bifrost/user/peerSynchronizer#341653336] as the handler for List((2,Peers message), (1,GetPeers message)) 20:44:17.975| INFO co.topl.db.LDBFactory$ - Loaded org.fusesource.leveldbjni.JniDBFactory with leveldbjni version 1.8 20:44:18.154| INFO co.topl.nodeView.CleanupWorker - Cleanup worker started 20:44:18.161| INFO co.topl.network.NetworkController - Registered Actor[akka://bifrost/user/nodeViewSynchronizer#-403724455] as the handler for List((65,Sync), (55,Inv), (22,RequestModifier), (33,Modifier)) 20:44:18.371| INFO co.topl.nodeView.history.History - Block 28XxAtDYfdCkEr8UyzT9f2fDWdn3Uqdu29V58qCiT8y5g appended to parent tksQdfioySWXrLbm7prosYBKze9Augu71ZXde9KuJC4Y at height 1 with score Some(100000000). 20:44:18.392| INFO co.topl.nodeView.state.State$ - Initializing state to watch for all public keys 20:44:18.393| INFO c.t.n.state.ProgramBoxRegistry$ - Initializing state with Program Box Registry 20:44:18.404| INFO c.t.nodeView.state.TokenBoxRegistry$ - Initializing state with Token Box Registry 20:44:18.449| INFO co.topl.nodeView.NodeViewHolder - NodeViewHolder publishing ready signal 20:44:18.450| INFO co.topl.consensus.Forger - Forger transitioning to the operational state 20:44:18.450| INFO co.topl.nodeView.MempoolAuditor - MemPool Auditor transitioning to the operational state 20:44:18.450| INFO co.topl.network.NodeViewSynchronizer - NodeViewSynchronizer transitioning to the operational state 20:44:18.450| INFO co.topl.network.PeerSynchronizer - PeerSynchronizer transitioning to the operational state 20:44:18.450| INFO co.topl.network.PeerManager - PeerManager transitioning to the operational state 20:44:18.453| INFO co.topl.consensus.Forger - Received a START signal, forging will commence shortly. java.vm.version = 11.0.11+8-jvmci-21.1-b05 jvmci.Compiler = null 20:44:18.593| INFO co.topl.network.NetworkController - No declared address was provided. Skipping address validation. 20:44:18.600| INFO co.topl.network.NetworkController - Network Controller transitioning to the operational state 20:44:18.619| INFO co.topl.BifrostApp - P2P protocol bound to /0.0.0.0:9084 20:44:19.273| INFO co.topl.BifrostApp - HTTP server bound to /0.0.0.0:9085
Updated about 1 year ago