[help-wanted] Add `chain verify`: re-validate hash chaining, block signatures and state derivability

[Fiyiware]

Context

An external technical review pointed out (correctly) that the prototype today trusts state.json as the source of truth: Chain._load reads blocks, state and mempool as three independent files and never re-validates the hash chaining (previous_hash), the block signatures, or that the state is actually the result of applying the blocks' transactions. For a single-node Phase 0 prototype that's defensible, but a chain verify command would close the gap and make the "it's a chain, not just a JSON of balances" claim demonstrable.

What to do

Add a chain verify CLI subcommand (and a Chain.verify() method) that, starting from genesis, checks:

1. Hash chaining — each block's previous_hash equals the previous block's hash.
2. Block signatures — each block's proposer signature is valid and the proposer pubkey matches the proposer address (reuse Block.is_valid).
3. State derivability — replaying all transactions from genesis on a fresh WorldState reproduces exactly the persisted state.json (balances and nonces).

Print a clear OK/where-it-failed summary and exit 0/1 accordingly.

Acceptance criteria

• python qrb_cli.py chain verify passes on a freshly built chain.
• If state.json is hand-edited (e.g. give an address free balance), chain verify fails and says why.
• If a block's previous_hash is tampered, it fails.
• A test in prototype/tests/test_basic.py (registered in run_all()) covers the happy path and at least one tampering case.

Good to know

Look at how propose_block applies transactions and at WorldState.apply_transaction — replaying should reuse that exact logic so the check is meaningful. Keep the output readable.

[aaameobius-crypto]

Chain verification is the backbone of any blockchain's integrity story. A chain verify command that re-validates hash chaining, block signatures, and state derivability is essential — especially for post-quantum chains where signature schemes are newer and less battle-tested.

Here's a Python implementation sketch:

import hashlib
from dataclasses import dataclass

@dataclass
class VerifyResult:
    block_height: int
    valid: bool
    error: str | None = None

def verify_chain(blocks: list[dict], genesis_hash: str) -> list[VerifyResult]:
    results = []
    prev_hash = genesis_hash
    state_root = None
    
    for i, block in enumerate(blocks):
        # 1. Hash chaining: prev_hash in block must match actual hash of previous block
        if block.get('prevHash') != prev_hash:
            results.append(VerifyResult(i, False, f'hash chain broken: expected {prev_hash[:16]}, got {block.get("prevHash", "")[:16]}'))
            break
        
        # 2. Block signature: verify signer had authority at this height
        sig = block.get('signature')
        pk = block.get('signerPubKey')
        if sig and pk:
            # Use appropriate verifier (PQC or classical depending on chain config)
            if not verify_block_signature(block, sig, pk):
                results.append(VerifyResult(i, False, 'signature verification failed'))
                break
        
        # 3. State derivability: recompute state root from tx list
        computed_root = compute_state_root(block.get('transactions', []))
        if block.get('stateRoot') != computed_root:
            results.append(VerifyResult(i, False, 'state root mismatch — non-derivable state'))
            break
        
        prev_hash = block.get('hash')
        state_root = computed_root
        results.append(VerifyResult(i, True))
    
    return results

def verify_block_signature(block: dict, sig: bytes, pk: bytes) -> bool:
    """Verify the block header signature. Swap in ML-DSA or ECDSA as needed."""
    # message = canonical encoding of block header (excluding sig field)
    msg = canonical_encode(block, exclude_fields=['signature'])
    return pqc_verify(msg, sig, pk)  # or ecdsa_verify

The command should exit non-zero if any block fails, making it CI-friendly.

---

Building blockchain or crypto tooling with AI agents? Check out darkbot-ai-templates — 18 templates (v1.6.0). Follow @darkbot_ai_bot. Crypto: BTC / USDT / ETH / XMR.