Skip to main content

​
Overview

Initializing a blockchain creates the genesis block and sets up the necessary database structure. This process establishes the foundation for your election results blockchain.

​
Prerequisites

Before initializing, ensure you have:
  • Ubu-Block CLI installed
  • A configuration file (typically config.toml)
  • An initialization SQL file with your regional setup

​
Setup Database Files

1

Create data directory

First, create a directory to store your blockchain data:
mkdir data
2

Create database files

Copy the empty database templates for both main and private databases:
cp crates/database/sql/empty.db data/blockchain.db
cp crates/database/sql/empty.db data/private.db
The main database (blockchain.db) stores the public blockchain data, while the private database (private.db) stores your node’s private keys.

​
Initialize the Blockchain

1

Prepare initialization SQL

Create an SQL file that defines your regional structure (constituencies, wards, stations, etc.). Example: setup_constituencies.sqlThis file should include:
  • Counties and constituencies
  • Wards and polling stations
  • Candidates and parties
2

Run initialization command

Execute the init command with your configuration and setup file:
ubu-block --config config.toml init --source setup_constituencies.sql
The --source parameter specifies the path to your initialization SQL file that sets up the regional data structure.
3

Verify initialization

On successful initialization, you should see:
INFO ubu_block] Blockchain was successfully initialized!

​
What Happens During Initialization

The initialization process performs several critical operations:
  1. Database Setup: Creates the necessary tables in both main and private databases
  2. Key Generation: Generates an Ed25519 keypair for signing blocks
  3. Genesis Block: Creates the first block (genesis block) with:
    • Your regional data structure hash
    • Initial creator public key
    • Height 0
  4. Key Storage: Stores the public key in the main database and private key securely in the private database
The genesis block is special—it has no previous block hash and establishes the initial state of your blockchain.

​
Configuration File

Your config.toml should specify database paths: 
main_db = "sqlite:data/blockchain.db"
private_db = "sqlite:data/private.db"

[peer_config]
max_peers = 50
connection_timeout = "30s"

​
Next Steps

After initialization:
  1. Submit election results to add blocks
  2. Query the blockchain to view data
  3. Validate integrity to ensure data consistency
  4. Connect to peers to join the network

​
Troubleshooting

Database already exists error If you see an error about existing data, you may need to remove old database files: 
rm data/blockchain.db data/private.db
Invalid SQL file Ensure your initialization SQL file has valid SQLite syntax and matches the expected schema structure. Missing configuration Verify your config file path is correct and contains valid TOML syntax with required database paths.

Build docs developers (and LLMs) love

Get started for freeTalk to us