Bor
Bor, the core component of the Shibarium network, operates on the principles outlined in EIP-225, following the Clique consensus protocol.
Validator Committee Selection in Shibarium: Shibarium relies on the Bor layer, where a committee of Validators is selected from the Validator pool based on their stake. This selection occurs at regular intervals and is shuffled periodically, determined by the Validator's governance concerning dynasty and network. The probability of being selected as a member of the block producer committee is determined by the ratio of Stake to Staking power.
Validator Selection Process: Validators are assigned slots proportionally based on their stake. Historical Ethereum block data is used as a seed to shuffle this array. Validators are then selected based on the producer count maintained by the Validator's governance. The Tendermint's proposer selection algorithm is employed to choose a producer for each sprint on Bor.
Bor Consensus Mechanics: In the Proof-of-Stake (PoS) system of Shibarium, participants stake Bone tokens on a designated Ethereum smart contract, known as the "staking contract", to become validators. The Bor module in Heimdall selects active validators as block producers.
Span and Sprint Mechanism: A span is a defined set of blocks in which a specific subset of validators is chosen. Within a span, each validator is assigned voting power, influencing their chances of being selected as a block producer. A sprint, a smaller subset of blocks within a span, designates a single block producer for block generation.
Block Authorization and Backup Mechanism: Block producers, also known as signers, authorize blocks by signing the block's hash. Bor designates backup producers in case the primary producer fails to generate a block. The wiggle time, a predefined delay, determines when a backup producer starts generating a block.
Difficulty Metrics and Fork Resolution: Blocks signed in-turn have higher difficulty than out-of-turn signatures. Bor addresses forks by selecting the fork with the highest cumulative difficulty, prioritizing in-turn block production.
View Change and Span Commitment: At the end of each span, Bor undergoes a view change, fetching new producers for the subsequent span. This involves an HTTP call to the Heimdall node for new span data and a commitSpan call to the BorValidatorSet genesis contract.
State Synchronization with Ethereum: Bor features a mechanism to relay events from the Ethereum chain. This involves triggering the StateSynced event on Ethereum, monitoring by Heimdall, and commitment by Bor at the start of every sprint. State Sync ensures consistency between Ethereum and Bor chains.
State Sync Mechanism: State Sync transfers data from Ethereum to Bor through system calls. Validators on the Heimdall layer listen to StateSynced events and pass them on to the Bor layer. Bor updates its state using a system call after fetching new state-sync records post every sprint.
System Call and State Receiver Interface: The system call is crucial for changing state to a contract without making a transaction. Bor calls it internally with the system address. The receiver contract on Bor implements the IStateReceiver interface, allowing the execution of onStateReceive.
State-Sync Logs and Bor Block Receipts: State-sync logs are handled differently from normal logs in Bor. Bor produces a new transaction/receipt for the client after each sprint, including all logs for the state-sync. The tx hash is derived from the block number and block hash, and it does not alter consensus logic.
This comprehensive mechanism ensures the seamless operation of Shibarium, facilitating the integration and synchronization of data between different layers of the network.
Commands
Here's a curated list of common commands and Shibarium-specific operations essential for node operators. Whether you’re setting up a full node, validator node or troubleshooting, these commands will assist you in managing your Shibarium PoS environment effectively.
Frequently Used Commands for Bor & Heimdall
Use the tabs below to switch between commands for Bor and Heimdall:
To execute Bor IPC commands, use the following syntax:
bor attach .bor/data/bor.ipc <command>
| IPC Command | RPC Command | Description |
|---|---|---|
admin.peers.length | curl -H "Content-Type: application/json" --data '{"jsonrpc": "2.0", "method": "net_peerCount", "params": [], "id": 74}' localhost:8545 | Retrieves the number of peers connected to the node. |
admin.nodeInfo | Provides detailed information about the node. | |
eth.syncing | curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "eth_syncing","params": []}' localhost:8545 | Indicates whether the node is syncing (true) or not (false). |
eth.syncing.highestBlock - eth.syncing.currentBlock | Compares the current block of your node to the highest block. | |
eth.blockNumber | curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "eth_blockNumber","params": []}' localhost:8545 | Returns the latest block number processed by the node. |
debug.setHead("0x"+((eth.getBlock('latest').number) - 1000).toString(16)) | Rewinds the blockchain to 1000 blocks prior. | |
admin.nodeInfo.enode | Retrieves the public enode URL of the node. | |
eth.syncing.currentBlock * 100 / eth.syncing.highestBlock | Calculates the remaining percentage for block synchronization. | |
eth.getBlock("latest").number | curl http://YourIP:8545 -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0", "id":1, "method":"bor_getSigners", "params":["0x98b3ea"]}' | Queries the height of the latest Bor block. |
curl http://YourIP:8545 -X POST -H "Content-Type: application/json" --data '{"method":"eth_chainId","params":[],"id":1,"jsonrpc":"2.0"}' | Retrieves the chainID. |
| Command | Description |
|---|---|
curl localhost:26657/net_info? | Returns the number of connected peers using jq .result.n_peers. |
curl -s localhost:26657/status | Retrieves Heimdall’s current block height using jq .result.sync_info.latest_block_height. |
curl localhost:26657/net_info | Queries the node using its moniker with grep moniker. |
curl -s localhost:26657/status | Checks if Heimdall is in sync using jq .result.sync_info.catching_up. |
curl -s localhost:26657/status | Verifies Heimdall’s sync status using `jq .result \ |
heimdalld unsafe-reset-all | Resets the database in case of issues. |
curl localhost:26657/status | Provides comprehensive information about Heimdall. |
Node Management Commands
| Description | Command |
|---|---|
| Locate Heimdall genesis file | $CONFIGPATH/heimdall/config/genesis.json |
| Locate heimdall-config.toml | /etc/heimdall/config/heimdall-config.toml |
| Locate config.toml | /etc/heimdall/config/config.toml |
| Locate heimdall-seeds.txt | $CONFIGPATH/heimdall/heimdall-seeds.txt |
| Start Heimdall | $ sudo service heimdalld start |
| Start Heimdall rest-server | $ sudo service heimdalld-rest-server start |
| Start Heimdall bridge-server | $ sudo service heimdalld-bridge start |
| Locate Bor genesis file | $CONFIGPATH/bor/genesis.json |
| Start Bor | sudo service bor start |
| Retrieve Heimdall logs | /var/log/ |
| Check Heimdall logs | tail -f heimdalld.log |
| Check Heimdall rest-server logs | tail -f heimdalld-rest-server.log |
| Check Heimdall bridge logs | tail -f heimdalld-bridge.log |
| Check Bor logs | tail -f bor.log |
Useful Configuration Commands
Sync Status of Heimdall
To check if Heimdall is synced, run:
curl http://localhost:26657/status
Latest Block Height on Heimdall
To check the latest block height on Heimdall, run:
curl localhost:26657/status
Latest Block Height on Bor
To check the latest block height on Bor, use:
curl http://<your ip>:8545 -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0", "id":1, "method":"bor_getSigners", "params":["0x98b3ea"]}'
Cleanup: Deleting Remnants of Heimdall and Bor
For Linux package:
sudo dpkg -i
sudo rm -rf /etc/bor
For Binaries:
sudo rm -rf /etc/bor
sudo rm /etc/heimdall
Terminate Bor Process
For Linux:
ps -aux | grep bor
sudo kill -9 <PID>
For Binaries:
cd CS-2003/bor
bash stop.sh
Retrieve Latest Peer Details
To retrieve the latest peer details, run:
bor attach bor.ipc
admin.peers.forEach(function(value){
console.log(value.enode+',')
})
exit
Stop Heimdall and Bor Services
For Linux packages:
sudo service heimdalld stop
sudo service bor stop
For Binaries:
pkill heimdalld
pkill heimdalld-bridge
cd CS-2001/bor
bash stop.sh
Remove Heimdall and Bor Directories
For Linux packages:
sudo rm -rf /etc/heimdall/*
sudo rm -rf /etc/bor/*
For Binaries:
sudo rm -rf /var/lib/heimdalld/
sudo rm -rf /var/lib/bor