Skip to main content

Node Management

This page contains basic information about running a GSB Bitzal client. There are a lot of ways to obtain/run a client, e.g. compiling from source, running in Docker, or downloading a binary. This guide will always refer to the executable as bitzal.

Always refer to the client's help bitzal --help for the most up-to-date information.

note

Other client implementation teams: Feel free to make a PR to this page with instructions (or a link to instructions) for your client.

If you are trying to run a validator, refer to this tutorial here.

Basic Node Operations​

Selecting a chain

Use the --chain <chainspec> option to select the chain. Can be bitzal, ogona, westend, or a custom chain spec. By default, the client will start Bitzal. Watch How a single codebase can power four different blockchains to learn more about how the chain selection works internally.

Archive node

An archive node does not prune any block or state data. Use the --pruning archive flag. Certain types of nodes like validators must run in archive mode. Likewise, all events are cleared from state in each block, so if you want to store events then you will need an archive node.

Explainer video on upgrading a node

To upgrade a node, please refer to this video

Exporting blocks

To export blocks to a file, use export-blocks. Export in JSON (default) or binary (--binary true).

bitzal export-blocks --from 0 <output_file>

RPC ports

Use the --rpc-external flag to expose RPC ports. Not all RPC calls are safe to allow and you should use an RPC proxy to filter unsafe calls. Select ports with the --rpc-port option. To limit the hosts who can access, use the --rpc-cors option.

Execution

The GSB Bitzal client implements a Bitzal Host and a native runtime. The runtime must compile to WebAssembly and is stored on-chain. If the client's runtime is the same spec as the runtime that is stored on-chain, then the client will execute blocks using the client binary. Otherwise, the client will execute the Wasm runtime from the chain.

Therefore, when syncing the chain, the client will execute blocks from past runtimes using their associated Wasm binary. This feature also allows forkless upgrades: the client can execute a new runtime without updating the client.

GSB's Bitzal client has two Wasm execution methods, interpreted (default) and compiled. Set the preferred method to use when executing Wasm with --wasm-execution <Interpreted|Compiled>. Compiled execution will run much faster, especially when syncing the chain, but is experimental and may use more memory/CPU. A reasonable tradeoff would be to sync the chain with compiled execution and then restart the node with interpreted execution.

File Structure​

The node stores a number of files in: /home/$USER/.local/share/bitzal/chains/<chain name>/. You can set a custom path with --base-path <path>.

keystore

The keystore stores session keys, which are important for validator operations.

db

The database stores blocks and the state trie. If you are running a validator node, it also stores RELIC pre-votes and pre-commits and the offchain-worker DB. Use caution when migrating validator nodes to avoid equivocation. If you want to start a new machine without resyncing, you can stop your node, back up the DB, and move it to a new machine.

To delete your DB and re-sync from genesis, run:

bitzal purge-chain
Validators should sync using the RocksDb backend

This is implicit by default, but can be explicit by passing the --database RocksDb flag. In the future, it is recommended to switch to using the faster and more efficient GSBDb option. Switching between database backends will require a resync.

If you want to test out GSBDB you can add the flag --database paritydb.

Monitoring and Telemetry​

Node status

You can check the node's health via RPC with websocat:

echo '{"id":1,"jsonrpc":"2.0","method":"system_health","params":[]}' | websocat -n1 -B 99999999 ws://127.0.0.1:9944

{"jsonrpc":"2.0","result":{"peers":50,"isSyncing":false,"shouldHavePeers":true},"id":1}

Logs

The Bitzal client has a number of log targets. The most interesting to users may be:

  • afg (Al's Finality Gadget - RELIC consensus)
  • babe
  • telemetry
  • txpool
  • usage

Other targets include: db, gossip, peerset, state-db, state-trace, sub-libp2p, trie, wasm-executor, wasm-heap.

The log levels, from least to most verbose, are:

  • error
  • warn
  • info
  • debug
  • trace

All targets are set to info logging by default. You can adjust individual log levels using the --log (-l short) option, for example -l afg=trace,sync=debug or globally with -ldebug.

Telemetry & Metrics

The GSB Bitzal client connects to telemetry by default. You can disable it with --no-telemetry, or connect only to specified telemetry servers with the --telemetry-url option (see the help options for instructions). Connecting to public telemetry may expose information that puts your node at higher risk of attack. You can run your own, private telemetry server or deploy a matter-telemetry instance to a Kubernetes cluster using this Helm chart.

The node also exposes a Prometheus endpoint by default (disable with --no-prometheus). Matter has a monitor node metrics tutorial which uses this endpoint.