Testing & Verification

Contents

1. Purpose of this page
2. Prerequisites
3. PoW Reference Verifier — verify-blake3-pow.py
4. BLAKE3 Test Vectors
5. Regtest Network Simulation — regtest-simulation.sh
6. Current Test Results
7. Known Limitations
8. Reporting Issues
9. Source Files

1. Purpose of this page #

This page provides technical tools to independently test and verify b3chain's proof-of-work implementation during early development.

Publishing these tools is how serious cryptographic projects behave. We expect people to test the system, and we believe our implementation is correct. If it isn't, we want to know.

If someone claims to offer a "B3C token" or "b3chain asset," you can always verify: if it is not reproducible using these published test scripts and the reference PoW implementation, it is not b3chain.

2. Prerequisites #

To run the verification tools, you need:

Quick setup

# Install the BLAKE3 Python binding
pip3 install blake3

# Clone the repository (when public)
git clone https://github.com/b3chain/b3chain.git
cd b3chain

# Build (for regtest simulation only)
mkdir build && cd build
cmake ..
cmake --build . -j$(nproc)

3. PoW Reference Verifier #

verify-blake3-pow.py is a standalone Python script that verifies the double BLAKE3-256 proof-of-work algorithm against known test vectors. It requires no running node — just Python and the blake3 library.

What it verifies

• Single BLAKE3-256 hash correctness (3 vectors)
• Double BLAKE3-256 construction correctness (2 vectors)
• Block header PoW hash computation (4 vectors)
• (Optional) Live block PoW validation from a running node

The PoW formula

PoW_hash = BLAKE3( BLAKE3( serialize(block_header) ) )

where block_header is the standard 80-byte encoding:
  nVersion     (4 bytes, int32, little-endian)
  hashPrevBlock (32 bytes, uint256, little-endian)
  hashMerkleRoot(32 bytes, uint256, little-endian)
  nTime        (4 bytes, uint32, little-endian)
  nBits        (4 bytes, uint32, little-endian)
  nNonce       (4 bytes, uint32, little-endian)

Block identity hashes (block hash, txid, merkle tree) still use double SHA-256, identical to Bitcoin. Only PoW validation uses BLAKE3.

Usage

# Verify test vectors only (no node required)
python3 contrib/testing/verify-blake3-pow.py

# Verify test vectors + live blocks from a running regtest node
python3 contrib/testing/verify-blake3-pow.py --rpc-port=18545

Expected output

============================================================
 B3Chain BLAKE3 PoW Verification
============================================================

[1/4] Single BLAKE3-256 vectors
  PASS: BLAKE3('')
  PASS: BLAKE3('b3chain')
  PASS: BLAKE3('abc')

[2/4] Double BLAKE3-256 vectors
  PASS: BLAKE3(BLAKE3(''))
  PASS: BLAKE3(BLAKE3('b3chain'))

[3/4] Block header PoW hash vectors
  PASS: 80-zero-bytes PoW hash
  PASS: 80-zero-bytes ID hash
  PASS: version=1 PoW hash
  PASS: version=1 ID hash

[4/4] Live block verification
  SKIP: No --rpc-port specified

============================================================
 RESULTS: 9/9 passed, 0 failed
============================================================
 All tests passed!

Verifiers must always match the consensus implementation byte-for-byte. If your verifier produces different hashes, your implementation is wrong — do not assume the reference is incorrect without investigation.

4. BLAKE3 Test Vectors #

These are the authoritative test vectors for b3chain's PoW algorithm. Use them to verify any independent implementation.

Single BLAKE3-256

Double BLAKE3-256

Block header vectors

Hashes are shown in big-endian display format (most significant byte first), the standard for displaying block hashes. Internal byte order is little-endian.

Pseudocode

import blake3, hashlib, struct

def double_blake3(data: bytes) -> bytes:
    h1 = blake3.blake3(data).digest()     # first pass (32 bytes)
    return blake3.blake3(h1).digest()      # second pass (32 bytes)

def double_sha256(data: bytes) -> bytes:
    return hashlib.sha256(
        hashlib.sha256(data).digest()
    ).digest()

# Example: 80 zero-byte header
header = b'\x00' * 80
pow_hash  = double_blake3(header)   # used for PoW validation
id_hash   = double_sha256(header)   # used for block identity

5. Regtest Network Simulation #

regtest-simulation.sh launches a 3-node b3chain network on localhost, mines 2016 blocks (a full difficulty retarget period), and runs 19 automated checks covering consensus, wallet operations, and chain consistency.

What it tests

Usage

# From the repository root (requires compiled b3chaind)
bash contrib/testing/regtest-simulation.sh

# Or specify a custom build directory
BINDIR=/path/to/build/bin bash contrib/testing/regtest-simulation.sh

Expected output

============================================================
 B3Chain Regtest Simulation (2016 blocks, 3 nodes)
============================================================

[1/8] Setting up test environment...
  PASS: Node 0 started at height 0
  PASS: Node 1 started at height 0
  PASS: Node 2 started at height 0

[2/8] Creating wallets...
  Node 0 (miner):  b3rt1q...
  Node 1 (wallet): b3rt1q...
  Node 2 (wallet): b3rt1q...
  PASS: Address uses b3rt prefix

[3/8] Testing peer connectivity...
  PASS: Node 0 has 3 peer(s)

[4/8] Mining 2016 blocks (full retarget period)...
  Mined 500 / 2016 blocks...
  Mined 1000 / 2016 blocks...
  Mined 1500 / 2016 blocks...
  Mined 2000 / 2016 blocks...
  Mined 2016 / 2016 blocks...
  Mining took 44s
  PASS: Node 0 at height 2016
  Waiting for block propagation...
  PASS: Node 1 synced to 2016
  PASS: Node 2 synced to 2016
  PASS: All nodes agree on tip
  PASS: All nodes agree on tip (node2)

[5/8] Verifying mining rewards and subsidy...
  Miner balance: 14947.76611201 B3C
  PASS: Miner has positive balance
  PASS: Block 1 subsidy (50.00000000)

[6/8] Testing wallet send/receive...
  Sent 10.5 B3C to node 1
  Sent 5.25 B3C to node 2
  PASS: Node 1 received 10.5 B3C
  PASS: Node 2 received 5.25 B3C
  Node 1 sent 2.0 B3C to node 2
  Tx in miner mempool after 5s
  PASS: Cross-node send succeeded

[7/8] Verifying chain consistency...
  PASS: Chain work matches across nodes
  PASS: Genesis hash correct
  PASS: Block 1008 hash consistent

[8/8] Verifying UTXO set...
  PASS: UTXO hash matches across nodes

============================================================
 RESULTS: 19 passed, 0 failed
============================================================
 All tests passed!

Runtime is approximately 70 seconds on modern hardware. The script automatically cleans up all node processes on exit.

How to confirm you passed

The final line should read "19 passed, 0 failed" and the exit code should be 0. Any deviation indicates a problem — please report it.

6. Current Test Results #

Results from the most recent full test run on the development branch.

Skipped tests

Skips are intentional and documented. They fall into four categories:

• Tests requiring SHA-256d-mined blocks (incompatible with BLAKE3 PoW)
• Tests requiring assumeutxo checkpoints (not yet configured for b3chain)
• Tests requiring BDB wallet support (b3chain uses SQLite only)
• Tests requiring external tools not present in the build environment

7. Known Limitations #

• All tests run on regtest — a private, local network with minimal difficulty. Real-world network conditions are not simulated.
• Consensus parameters (block time, reward schedule, difficulty limits) are not frozen and may change.
• The BLAKE3 library is vendored from the official repository but has not undergone independent audit specific to this integration.
• SIMD-accelerated BLAKE3 paths (SSE2/AVX2/AVX-512) are enabled on x86-64 Linux. Other platforms use the portable C implementation.
• No mainnet exists. These tests do not prove that a production network works — they prove that the code produces correct results in isolation.

8. Reporting Issues #

If you find a bug in any test script or a discrepancy in the PoW verification, we want to hear about it.

9. Source Files #

All testing and verification tools live in the main repository under contrib/testing/.

Related C++ unit tests