QRNG and entropy¶

WaveLedger requires every block to carry a verifiable attestation of unpredictable entropy. This is the "quantum-attested mining" rule that distinguishes WaveLedger from a generic PoW chain.

The rule¶

For a block to be valid:

1. The miner must fetch ≥ 64 bytes of entropy from an entropy source. The first 32 bytes are the seed (mixed into the block header for PoW); the last 32 are the proof (revealed for verification).
2. The miner must include an attestation envelope in the block (quantum_signature):
3. entropy_seed and entropy_proof (32-byte hex each)
4. commitment = SHA3-512(entropy_proof) so any node can reconstruct and check it
5. health snapshot (monobit ratio, Fano factor, pool size)
6. source — the registered source ID (see Source registry below)
7. device_id, proof_type, version
8. The seed must be incorporated into the block header that PoW hashes, so a miner cannot grind on different entropy after-the-fact.
9. Validators reject any block whose source is not in the registry, whose commitment doesn't match SHA3-512(entropy_proof), or whose health stats fall outside the configured statistical bounds. A source-side signature path (per-source registered public key verifying a signature over the commitment) is on the roadmap and will arrive with proof_type v2.

Why this matters¶

Generic PoW (Bitcoin, Litecoin, etc.) relies on the miner's secret nonce search being computationally hard. WaveLedger adds the constraint that the input to that search must be demonstrably unpredictable — a miner can't pre-mine blocks for the future because they don't know what entropy they'll have.

This makes the chain attractive to:

• Smart contracts that need on-chain randomness — instead of defrauding RANDAO-style schemes, contracts can read the attested entropy from the block header directly.
• Auditors — every block's randomness can be traced to a source and verified.
• Hardware-QRNG vendors — selling certified entropy as a service has a working consumer.

Source registry¶

The block's source field records which entropy provider produced this block's seed. Today the chain stores the field on every block as an audit trail but does not yet reject blocks whose source ID is unknown — verify_attestation only enforces a length bound on the string. Allow-listing the registered IDs and verifying a per-source signature are the next two enforcement steps (tracked in mining/attestation.py); see Crypto agility for the broader design.

Sources currently seen on testnet:

Planned (not deployed):

• fermi-qrng-v1 — Fermi shot-noise photodiode hardware
• iqr-server-v0 — ID Quantique reference hardware

Adding a new source will be governance-controlled once the registry ships; the design intent is BDFL-signed registration with a Timelock delay, but the on-chain hooks for either are not yet built.

The REST contract¶

A source must expose, on whatever port it likes:

GET /api/health
GET /api/random/bytes?n=<int>
GET /api/random/hex?n=<int>

Response from /api/health:

{
  "status": "running",
  "uptime_seconds": 12345.67,
  "pool": {
    "available_bytes": 65536,
    "capacity": 65536,
    "fill_percent": 100.0
  },
  "last_fill": {
    "source": "drand-default",
    "round": 4567890,
    "filled_at": "2026-05-28T20:00:00Z"
  },
  "source": "testnet-aggregator",
  "device": "WaveLedger Testnet Entropy Service"
}

Response from /api/random/bytes?n=64:

<raw bytes, Content-Type: application/octet-stream>

The aggregator pattern¶

The reference qrng_aggregator_service.py combines N upstream sources by XOR-mixing their outputs:

$$ \text{output}t = \bigoplus_i(t) $$}^{N} \text{source

As long as at least one source produces uniformly random bytes, the output is uniformly random. The min-quorum parameter says how many sources must respond successfully before the aggregator will serve any output — set high to fail closed, low to favor liveness.

The testnet aggregator currently runs with min_quorum = 1 and one source (drand). Production setups should run min-quorum 2-of-3 with a mix of drand, hardware QRNG, and a backup public service.

Why drand for the testnet¶

drand is the League of Entropy's federated beacon — a threshold BLS signature over a 30-second round number, contributed to by Cloudflare, EPFL, Kudelski Security, and others.

• Free
• 100% historical uptime (since 2019)
• Cryptographically verifiable (BLS signature in every round)
• Publicly auditable

It is not quantum random — drand uses classical entropy mixed across participants. The "quantum attested" framing on mainnet relies on swapping drand for QRNG hardware once it's deployed. The aggregator contract makes that a config change, not a fork.

No classical fallback¶

There is deliberately no "fall back to /dev/urandom if all sources fail" path. If every registered source is down, mining halts. This is the only way the entropy attestation has any meaning — if mining silently continues with software RNG when the verifiable source is gone, the whole property is decorative.

Operators have six tiers of degradation available:

1. Local QRNG hardware (preferred)
2. Local aggregator (multiple sources, XOR'd)
3. Remote aggregator on a separate VPS (testnet default)
4. Lowered difficulty target (continues mining at a reduced rate while waiting for entropy)
5. Emergency federated beacon (humans rotate keys + republish)
6. Halt

If none of those apply, the chain stops accepting new blocks.