qrng — Quantum Random Number Generator (provider registry)

5-source quantum random byte registry with config-driven router fallback. CURBy (NIST + CU Boulder Bell-test verified) + ANU (vacuum-fluctuation REST)

• NIST Beacon 2.0 (ECDSA-signed mixed entropy) + hardware QRNG (PCIe/USB serial, mock-default) + deterministic LCG (CI safety net). Tier coverage T0..T3. Pure-hexa (raw#9 STRICT — zero Python deps).

v1.1.0 (2026-05-07): integrated NIST SP 800-22 tier-1+ statistical audit via single-stage qrng_audited_bytes(n_bytes, audit_level, vendor) API (Boltz-2 paradigm absorption — entropy + audit + verdict in one call). Five tests: monobit, frequency-block, runs, longest-run, DFT spectral. See audit/module/audit.hexa.

Canonical: https://github.com/dancinlab/qrng

---

What is qrng?

qrng is a provider-side registry of quantum random byte sources. It does not itself amplify entropy (no HMAC-DRBG, no NIST SP 800-90A constructions — those belong to consumer packages). It returns raw bytes from one of 5 backends with a uniform QrngBytes struct + provenance message.

The five backends ship today:

Tier	Name	Vendor	is_quantum	is_local	Cost	Throughput
T0	mock_qrng	deterministic LCG	0	1	$0	1 GB/s
T1	curby	NIST + CU Boulder (Bell-test)	1	0	$0	8.5 bps (60s/pulse)
T1	anu	qrng.anu.edu.au	1	0	$0	1 KB/s (1 req/min throttled)
T1	nist_beacon	NIST (ECDSA-signed mixed entropy)	0	0	$0	8.5 bps (60s/pulse)
T3	hardware_qrng	IDQ Quantis PCIe / ESP32 serial	1	1	$5000 (PCIe) / $10 (ESP32)	240 MB/s (PCIe)

Honest C3 note: nist_beacon is is_quantum=0 because it's vendor- classified as mixed entropy (HSM + multiple RNGs, possibly QRNG-augmented). Use as US sovereign sibling to ANU (AU) when geographic diversity matters. hardware_qrng is is_quantum=1 by vendor assertion (IDQ's NIST SP 800-90B health checks + ESP32 ADC noise) — independent NIST validation NOT performed by this package.

---

Installation

Via hx (recommended)

hx install qrng              # global, pulls latest from registry
hx install qrng@1.0.0        # pin specific version
qrng --version               # → 1.0.0

qrng is registered as the 26th entry in the hexa-lang package registry (hexa-lang/tool/pkg/registry.tsv L26). hx install qrng pulls from https://github.com/dancinlab/qrng and installs the standalone CLI under $HX_HOME/bin/qrng.

Via git clone

git clone https://github.com/dancinlab/qrng.git ~/.qrng
export QRNG_ROOT=~/.qrng
export PATH="$QRNG_ROOT/cli:$PATH"

hexa run $QRNG_ROOT/cli/qrng.hexa selftest

Runtime deps

ZERO Python deps. raw#9 STRICT — all 9 modules are pure hexa.

System deps (assumed present on macOS / Linux):

• curl — live CURBy / ANU / NIST Beacon REST calls
• xxd — hex encode/decode round-trip
• shasum (macOS) or sha256sum (Linux) — byte audit
• timeout (macOS coreutils) — block-bound for hardware_qrng live serial reads

The mock_qrng backend (CI default) needs none of these — pure LCG arithmetic.

---

Quick Start

1. Pull random bytes via router fallback

qrng collect --bytes 16

Default chain: curby → anu → nist_beacon → hardware_qrng → mock_qrng — each gated source FAILs without QRNG_LIVE=1, so the chain falls through to mock_qrng (always-OK terminal). Output includes attempts + reasons per backend.

2. Pin a single backend

QRNG_SOURCE=mock_qrng qrng collect --bytes 32 --seed 42
QRNG_LIVE=1 QRNG_SOURCE=curby qrng collect --bytes 16

3. Run the full selftest

qrng selftest

Output: __QRNG_SELFTEST__ PASS on 8/8 sentinels green (5 backends + 3 abstraction modules + main aggregator).

---

Registered backends

curby — Bell-test verified (NIST + CU Boulder)

Twine-blockchain anchored Bell-inequality-violation pulses (loophole-free Bell test protocol). Free, no auth, 8.5 bps sustained (512 bits per 60-second pulse). twine_anchor field MUST be non-empty on live pulses (falsifier F_CURBY_03).

QRNG_LIVE=1 qrng collect --source curby --bytes 64

anu — vacuum-fluctuation photodetector (Australian National University)

Public REST (https://qrng.anu.edu.au/API/jsonI.php) returning uint8 arrays sampled from quantum vacuum fluctuations. Free legacy tier 1 req/min; chunks > 1024 bytes require pacing (use qrng collect with chained chunks).

QRNG_LIVE=1 qrng collect --source anu --bytes 128

nist_beacon — Beacon 2.0 (ECDSA P-384 signed pulses)

NIST Randomness Beacon 2.0 (beacon.nist.gov/beacon/2.0/pulse/last). Mixed-entropy (HSM + RNG composite, possibly QRNG-augmented — vendor self-classifies). Use as US sovereignty mirror to ANU when geographic diversity proof is required. ECDSA signature MUST be present (F_NIST_03).

hardware_qrng — local PCIe/USB-serial

Probes /dev/quantis* (IDQ Quantis PCIe/USB SDK), then /dev/cu.usbmodem* / /dev/cu.usbserial* (ESP32 / FTDI bridges). Live path requires QRNG_HW_LIVE=1; default is mock-mode (deterministic LCG byte- identical to mock_qrng).

mock_qrng — deterministic LCG

s = (1664525 × s + 1013904223) mod 2^32. Same --seed → same bytes byte-identical across runs. CI default; safety net for the router chain.

---

Integrated audit — qrng_audited_bytes()

Single-stage API that pulls entropy + runs NIST SP 800-22 tier-1+ statistical audit + returns ok/fail in one call (Boltz-2 paradigm absorption). Eliminates the "did the caller actually audit?" failure mode.

let r = qrng_audited_bytes(1024, "tier1+", "anu_legacy")
// r.ok                       : 0/1
// r.bytes_hex                : hex string
// r.audit_pass               : 0/1 (1 iff every non-skipped test passed)
// r.tests_run                : [AuditTestResult] — 5 entries (name, p_value, passed, skipped, note)
// r.audit_level_requested    : "tier1+" | "none"
// r.audit_level_delivered    : "tier1+" | "tier1-partial" | "tier1-none" | "none"
// r.tier                     : "T0" | "T1" | "T3" | ...
// r.vendor                   : resolved backend label
// r.alpha                    : 0.01 (NIST default)
// r.message                  : provenance string

Five tests (NIST SP 800-22 §2.1, §2.2, §2.3, §2.4, §2.6):

Test	Min bits	Notes
monobit	100	frequency / proportion of ones
frequency_block	2560	M=128 N>=20; chi-square upper tail
runs	100	gated by monobit pre-check
longest_run	6272	M=128 K=5 N=49; class boundaries [<=4..>=9]
dft_spectral	1000	O(n^2) DFT, capped at 1024 bits (FFT deferred — see caveat 3)

Audit downgrade is automatic and labelled: a 64-byte (512-bit) pull with audit_level="tier1+" returns audit_level_delivered="tier1-partial" with monobit + runs running and the other three tests skipped with reason notes. audit_pass aggregates only the tests that actually ran (alpha=0.01).

hexa run audit/module/audit.hexa
QRNG_LIVE=1 hexa run audit/module/audit.hexa   # +ANU legacy live exercise

Selftest evidence:

• pathological all-zeros fixture: audit FAIL (monobit p ≈ 0; distinction proof)
• mock LCG (n=128 bytes = 1024 bits): audit PASS (3/5 tests run; LCGs are statistically OK on short windows — caveat 4)
• ANU legacy live (n=64 bytes = 512 bits): audit PASS (monobit + runs run)

---

Boundary: qrng (provider) vs qmirror.qrng (consumer drop-in)

Two repositories share the qrng name across different roles. Zero code overlap, but the API surface is dual-homed.

Repo	Surface	Role
qrng (this)	<feature>/module/<feature>.hexa for {anu,curby,nist_beacon,hardware_qrng,mock_qrng} + abstraction triplet {source,registry,router,qrng_main}	Provider registry — 5 backends + dispatch + router
qmirror	modules/qrng.hexa (single file)	Consumer drop-in — HMAC-DRBG amplifier exposed as qmirror qrng <bits>

They share the QrngBytes and QrngSourceMeta struct shapes by convention (both packages declare them locally; no shared import). Sentinel namespaces are disjoint (__QRNG_* vs __QMIRROR_QRNG__). Env var namespaces are disjoint (QRNG_* / NEXUS_QRNG_* vs QMIRROR_* / NEXUS_QMIRROR_*).

Future qmirror v3.0.0 may declare qrng = "^1.0.0" as a runtime dependency to consolidate the entropy pipeline; until then, each operates independently. Full rationale + falsifiers in docs/dual_home_boundary.md.

---

Architecture — 4-abstraction + 5-backend split

The nexus/core/qrng/ Option D split is preserved verbatim:

qrng/
├── source/module/source.hexa             # abstract interface contract (QrngBytes / QrngSourceMeta)
├── registry/module/registry.hexa         # 5-backend dispatch table + canonical names
├── router/module/router.hexa             # config-driven backend selection + fallback chain
├── qrng_main/module/qrng_main.hexa       # aggregator + selftest entry-point
├── audit/module/audit.hexa               # NIST SP 800-22 tier-1+ statistical audit + qrng_audited_bytes()
├── mock_qrng/module/mock_qrng.hexa       # T0 deterministic LCG
├── anu/module/anu.hexa                   # T1 ANU vacuum-fluctuation REST
├── curby/module/                          # T1 NIST + CU Boulder Bell-test
│   ├── curby.hexa
│   └── fixtures/curby_pulse_sample.json
├── nist_beacon/module/                    # T1 NIST Beacon 2.0 ECDSA-signed
│   ├── nist_beacon.hexa
│   └── fixtures/nist_beacon_pulse_sample.json
├── hardware_qrng/module/hardware_qrng.hexa  # T3 IDQ Quantis / ESP32 serial
├── cli/qrng.hexa           # CLI router (5 subcmds)
├── tests/                  # 7 smoke tests (one per backend + router + registry)
├── examples/               # 3 example scripts
├── docs/                   # cross-cutting docs (e.g., dual_home_boundary.md)
├── install.hexa            # hx install hook (system dep check + selftest)
├── hexa.toml               # package manifest
├── LICENSE                 # Apache-2.0
├── CHANGELOG.md
└── README.md               # this file

# Layout: feature-grouped triplet — each <feature>/ has {core?, module/, doc/} (singular).
# core/ is optional and absent for module-only features.

The router resolution order (default chain curby → anu → nist_beacon → hardware_qrng → mock_qrng) is overridable via env:

• QRNG_SOURCE=<name> — pin to single backend
• QRNG_FALLBACK_CHAIN=a,b,c — comma-sep custom chain

Both legacy (NEXUS_QRNG_*) and forward (QRNG_*) env namespaces are honoured; legacy is load-bearing for backward compat with the upstream nexus origin.

---

CLI reference

qrng <subcmd> [flags...]

subcommands:
  status                                  registry table + tier coverage
  collect [--bytes=N] [--seed=S] [--source=NAME]
                                          pull random bytes via router fallback
  selftest                                full provider sweep (8 sentinels)
  chain                                   show resolved router fallback chain
  meta --backend=NAME                     print backend metadata

global flags:
  --version  show version
  --json     machine-parseable JSON tail
  --help,-h  this help

env:
  QRNG_ROOT             override repo root (default: inferred from $0)
  QRNG_LIVE             1 → enable live network paths (default: gated mock)
  QRNG_MOCK             1 → force mock LCG fixture (CI-safe)
  QRNG_SOURCE           pin to single backend (skips fallback chain)
  QRNG_FALLBACK_CHAIN   comma-sep custom fallback chain
  QRNG_HW_LIVE          1 → hardware_qrng live serial/PCIe path
  QRNG_HW_MOCK          1 → hardware_qrng mock fixture
  QRNG_HW_TIMEOUT_S     serial read timeout in seconds (default 5)

  legacy aliases (load-bearing):
    NEXUS_QRNG_LIVE / NEXUS_QRNG_MOCK / NEXUS_QRNG_SOURCE
    NEXUS_QRNG_FALLBACK_CHAIN / NEXUS_QRNG_HW_*
    ANIMA_QRNG_MOCK   (anima-side consumer alias)

---

Examples

See examples/:

• 01_quick_collect.hexa — pull bytes via default router chain
• 02_qrng_for_ml_seed.hexa — quantum-seeded ML training pattern
• 03_router_fallback_demo.hexa — show router attempt/reason chain

hexa run examples/01_quick_collect.hexa

---

Sister packages (HEXA family)

qrng is the 6th publishable HEXA-family package. The full set:

Package	Version	Repo	Description
qmirror	2.0.0	https://github.com/dancinlab/qmirror	Quantum mirror substrate (CHSH/IIT/NIST)
sim-universe	1.0.0	https://github.com/dancinlab/sim-universe	Virtual universe runtime + Bostrom test
hexa-bio	1.0.0	https://github.com/dancinlab/hexa-bio	Molecular toolkit on n=6 lattice
honesty-monitor	1.0.0	https://github.com/dancinlab/honesty-monitor	AI honesty-bit falsifier
anima-agent	1.0.0	https://github.com/dancinlab/anima-agent	Φ-gated autonomous agent runtime
qrng	1.0.0	https://github.com/dancinlab/qrng	5-source QRNG provider registry (this)

---

Caveats (raw#10 honest C3)

1. Dual-home boundary risk with qmirror.qrng — qmirror's modules/qrng.hexa is a consumer-side HMAC-DRBG amplifier API drop-in (NO code overlap) while THIS package is the 5-source provider registry. Future qmirror v3+ may declare qrng as a runtime dependency to unify entropy sourcing. See docs/dual_home_boundary.md.
2. 6 external consumers (anima/.roadmap.qrng + 3 anima-physics files + anima-eeg + nexus/core/qrng provider stub) require refactor to point at standalone path; refactor staged for user review (NOT auto-applied).
3. Tests scaffolded fresh at extraction — phase 2 audit found NO tests/ subdir in nexus origin (modularity 2→1 demotion). Coverage is tier 1 (sentinel-pass per backend); deeper property-based tests deferred.
4. ANU rate-limit + ToS evolution — public REST is throttled to 1 req/min on T1.a legacy tier; ToS / redistribution terms may evolve. Mock LCG fallback always available with QRNG_MOCK=1.
5. License audit deferred to follow-up cycle — qrng core is Apache-2.0 (clean), but per-vendor data-rights for ANU / CURBy / NIST Beacon byte redistribution NOT formally audited. This package returns bytes to the caller; it does not redistribute. Callers re-publishing returned bytes should consult vendor ToS independently.

---

License & attribution

qrng core: Apache-2.0 (see LICENSE). Copyright 2026 박민우 nerve011235@gmail.com.

Per-vendor entropy sources carry their own data-rights regimes:

Backend	Data rights	Notes
mock_qrng	Apache-2.0 (qrng core)	LCG arithmetic — no third-party data
anu	ANU ToS	Free public REST; user-of-record is the caller
curby	NIST + CU Boulder ToS	Bell-test pulses; Twine anchors public
nist_beacon	NIST public domain	US-government work; ECDSA-signed
hardware_qrng	Vendor SDK terms (IDQ libQuantis)	Local hardware; no redistribution

Provenance

Extracted from the nexus repo on 2026-05-04 after phase 2 audit verdict extract_standalone_qrng_repo_with_caveats (rank 7, score 7). Upstream provenance:

• nexus/modules/qrng/ (5 backends, 1047 LoC)
• nexus/core/qrng/ (4 abstraction modules, 546 LoC)
• Total: 1593 LoC migrated

---

Status

• v1.0.0 (2026-05-04) — initial standalone release; 5 backends + 4 abstraction modules; tests scaffolded fresh; dual-home boundary doc published.