validate Command

Overview

The validate command performs comprehensive validation of your blockchain to ensure:

All blocks are cryptographically valid
Block chain is properly linked (each block references the previous block)
Digital signatures are authentic
Block contents match their hashes
No tampering has occurred

This is a critical command for maintaining trust in the blockchain’s integrity.

Syntax

ubu-block --config <CONFIG_FILE> validate

Parameters

The validate command takes no additional parameters beyond the global --config flag.

What It Validates

The validation process checks multiple aspects of blockchain integrity:

Genesis Block Verification

Confirms the genesis block (height 0) exists
Validates genesis block signature
Checks initialization hash

Chain Continuity

Verifies each block’s prev_hash matches the previous block’s hash
Ensures no blocks are missing in the sequence
Validates height progression (0, 1, 2, 3…)

Cryptographic Signatures

Validates each block’s digital signature
Confirms signatures match registered public keys
Ensures no forged or tampered blocks

Block Hash Integrity

Recalculates each block’s hash from its contents
Compares calculated hash with stored hash
Detects any modification to block data

Merkle Tree Validation

Reconstructs Merkle trees from election results
Verifies Merkle root matches stored root
Ensures result data hasn’t been altered

Data Consistency

Validates result data format
Checks foreign key integrity (station_id, candidate_id)
Ensures vote counts are non-negative

Example Usage

Basic Validation

ubu-block --config config.toml validate

Expected Output (Valid Chain):

INFO ubu_block] Blockchain is valid!

After Initialization

Always validate after initializing:

# Initialize
ubu-block --config config.toml init --source setup_constituencies.sql

# Validate
ubu-block --config config.toml validate

After Receiving Blocks

Validate after syncing from other nodes:

# Sync from peer (using p2p or API)
# ...

# Validate received data
ubu-block --config config.toml validate

Validation Failure

If validation fails, the command panics with detailed error information:

thread 'main' panicked at 'Could not verify block, found 0e70cebe0ab3bd8c3606a08d26483d092534eea4ccdb7816fc2692aee5ed3109, block: Block { height: 1, prev_hash: "abc123...", results: [CandidateResult { station_id: 22113056303301, candidate_id: 1, votes: 71 }], ... }', src/db.rs:189:17

This indicates:

Which block failed: Height and hash of the invalid block
Expected vs. actual hash: What hash should be vs. what was found
Block contents: The data in the failing block

Why Validation Fails

Data Tampering

Someone modified data directly in the SQLite database (e.g., changing vote counts, station IDs, or candidate IDs).Example: Updating votes in the results table without recreating the block.

Broken Chain Linkage

A block’s prev_hash doesn’t match the actual hash of the previous block.Causes:

Deleted blocks
Reordered blocks
Corrupted database

Invalid Signature

A block’s signature cannot be verified with the claimed public key.Causes:

Forged blocks
Public key mismatch
Corrupted signature data

Merkle Tree Mismatch

The Merkle root in a block doesn’t match the root calculated from the block’s results.Causes:

Modified result data
Corrupted Merkle root
Results added/removed from block

Database Corruption

SQLite database file is corrupted or incomplete.Causes:

Disk errors
Incomplete file transfer
Power failure during write

Detecting Tampering

The validation command is specifically designed to detect tampering. Here’s an example from the README:

Tampering Example

Original State: Candidate “Omosh” has 21 votes

Tamper Attempt: Edit the database:

UPDATE "results" SET "votes" = 71 WHERE _rowid_ = 1

Query Shows Modified Data:

ubu-block --config config.toml query -q "SELECT * FROM results"

| Omosh | ODM | 71 |  # Changed from 21!

Validation Detects Tampering:

ubu-block --config config.toml validate

thread 'main' panicked at 'Could not verify block, found 0e70cebe0ab3bd8c3606a08d26483d092534eea4ccdb7816fc2692aee5ed3109, block: Block { ... votes: 71 } ...'

No Fungua Server: The validation failure proves the data was tampered with. You cannot modify blockchain data without detection.

When to Validate

Run validation:

After Initialization: Confirm genesis block is valid
After Receiving Blocks: Verify data from other nodes
Before Important Operations: Ensure chain integrity before critical actions
Periodic Audits: Regular validation as part of maintenance
After Suspicion: If you suspect data tampering or corruption
Post-Recovery: After database restoration from backup

Performance

Validation performance depends on blockchain size:

Small chains (< 1,000 blocks): Instant validation (< 1 second)
Medium chains (1,000 - 10,000 blocks): A few seconds
Large chains (> 10,000 blocks): Several seconds to minutes

Validation is CPU-intensive due to:

Hash calculations (SHA-256)
Signature verification (Ed25519)
Merkle tree reconstruction

Validation can be parallelized in future versions for better performance on large chains.

Validation in Node Types

Observer Nodes

Observer nodes should validate:

On startup
After syncing new blocks
Periodically (e.g., hourly)

Submission Nodes

Submission nodes validate:

Before accepting new submissions
After adding blocks to the chain
On startup

Verification Nodes

Verification nodes validate:

Continuously as part of consensus
Before cross-referencing with official sources
After reward distribution calculations

Troubleshooting

Validation Takes Too Long

Issue: Validation is slow on large blockchains. Solutions:

Run validation less frequently
Use incremental validation (validate only new blocks)
Consider hardware upgrades (faster CPU, SSD)

Panic on Valid Chain

Issue: Validation panics even though chain should be valid. Possible causes:

Database schema mismatch
Corrupted indexes
Software version incompatibility

Solutions:

Rebuild indexes:
```
REINDEX;
```
Check software versions match
Compare with other nodes

False Positives After Sync

Issue: Validation fails after syncing from another node. Diagnosis:

Validate the source node’s chain
Check network transfer integrity
Compare block hashes with source

Solution: Re-sync from a trusted source.

Recovery from Validation Failure

If validation fails:

Identify the Issue

Note which block(s) failed and the error message.

Determine Cause

Was data modified directly?
Database corruption?
Sync issue from untrusted source?

Restore from Backup

If you have a backup:

cp data/blockchain.db.backup data/blockchain.db
ubu-block --config config.toml validate

Re-sync from Trusted Source

If no backup, sync from a known-good node:

Delete corrupted database
Sync from trusted peer
Validate after sync

Report the Issue

If the cause is unclear, report to the Ubu-Block team with:

Error message
Block height and hash
Steps to reproduce

Security Implications

Critical Security Feature: Validation is your defense against data manipulation. Never skip validation or ignore failures.

Tamper Evidence: Any modification to blockchain data is detected
Trust Verification: Confirms all blocks are signed by authorized keys
Data Integrity: Ensures election results are authentic and unmodified
Audit Trail: Validation failures are logged for investigation

Implementation Details

The validate command is implemented in apps/cli/src/validate.rs:4-8 and:

Creates a BlockChain instance from config
Calls blockchain.is_valid() to perform validation
Uses assertions that panic on validation failure
Logs success with log::info!
Validates all blocks from genesis to current height

Core validation logic is in the blockchain crate:

Iterates through all blocks sequentially
Verifies each block’s hash, signature, and linkage
Reconstructs and verifies Merkle trees
Checks cryptographic signatures with Ed25519

Next Steps

Query Results

Query validated blockchain data

Tamper Detection

Learn more about tamper detection

Blockchain Concepts

Understand blockchain structure

Security

Deep dive into cryptographic security

REST API

CLI Reference

Rust Crates

Overview

Syntax

Parameters

What It Validates

Example Usage

Basic Validation

After Initialization

After Receiving Blocks

Validation Failure

Why Validation Fails

Detecting Tampering

Tampering Example

When to Validate

Performance

Validation in Node Types

Observer Nodes

Submission Nodes

Verification Nodes

Troubleshooting

Validation Takes Too Long

Panic on Valid Chain

False Positives After Sync

Recovery from Validation Failure

Security Implications

Implementation Details

Next Steps

Query Results

Tamper Detection

Blockchain Concepts

Security

Build docs developers (and LLMs) love

REST API

CLI Reference

Rust Crates

​Overview

​Syntax

​Parameters

​What It Validates

​Example Usage

​Basic Validation

​After Initialization

​After Receiving Blocks

​Validation Failure

​Why Validation Fails

​Detecting Tampering

​Tampering Example

​When to Validate

​Performance

​Validation in Node Types

​Observer Nodes

​Submission Nodes

​Verification Nodes

​Troubleshooting

​Validation Takes Too Long

​Panic on Valid Chain

​False Positives After Sync

​Recovery from Validation Failure

​Security Implications

​Implementation Details

​Next Steps

Query Results

Tamper Detection

Blockchain Concepts

Security

Build docs developers (and LLMs) love

Overview

Syntax

Parameters

What It Validates

Example Usage

Basic Validation

After Initialization

After Receiving Blocks

Validation Failure

Why Validation Fails

Detecting Tampering

Tampering Example

When to Validate

Performance

Validation in Node Types

Observer Nodes

Submission Nodes

Verification Nodes

Troubleshooting

Validation Takes Too Long

Panic on Valid Chain

False Positives After Sync

Recovery from Validation Failure

Security Implications

Implementation Details

Next Steps