🎲 qrng

Quantum RNG — 5-source provider registry · CURBy + ANU + NIST Beacon + hardware + audit · NIST SP 800-22 tier-1+ audit

quantum · entropy · CURBy · ANU · NIST Beacon · hardware QRNG · NIST SP 800-22 · audit · provider registry · n=6 · dancinlab

---

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.

Note

Sister package of qmirror (quantum mirror substrate · consumer-side HMAC-DRBG amplifier), and member of the dancinlab HEXA family (parent: dancinlab/echoes). Provider/consumer boundary deliberate — zero code overlap, struct-shape compatible. See §"Boundary: qrng (provider) vs qmirror.qrng (consumer)".

At a glance

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 backends shipped 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.

Status

• 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.
• v1.0.0 (2026-05-04) — initial standalone release; 5 backends + 4 abstraction modules; tests scaffolded fresh; dual-home boundary doc published.
• 5 backends (T0/T1×3/T3) · 4 abstraction modules · 1 integrated audit
• Pure HEXA — raw9 strict; no .py in the runnable surface
• 6 external consumers (anima / anima-physics / anima-eeg / nexus stub) refactor staged
• Parent: dancinlab/echoes (HEXA family canonical)

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.

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. 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.

Install

# 1. Install hexa-lang (gives you `hexa` + `hx` package manager)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/dancinlab/hexa-lang/main/install.sh)"

# 2. Install qrng
hx install qrng

System deps (assumed present on macOS / Linux): curl, xxd, shasum/sha256sum, timeout. The mock_qrng backend (CI default) needs none of these.

Run

qrng status                                          # registry table + tier coverage
qrng collect [--bytes=N] [--seed=S] [--source=NAME]  # pull random bytes via router fallback
qrng selftest                                        # full provider sweep (12 sentinels: 9 backends + 3 abstraction)
qrng chain                                           # show resolved router fallback chain
qrng meta --backend=NAME                             # print backend metadata
qrng --version                                       # show version
qrng --help                                          # full usage

# integrated audit (entropy + NIST SP 800-22 + verdict in one call):
hexa run audit/module/audit.hexa
QRNG_LIVE=1 hexa run audit/module/audit.hexa         # +ANU legacy live exercise

# examples (examples/):
hexa run examples/01_quick_collect.hexa              # pull bytes via default router chain
hexa run examples/02_qrng_for_ml_seed.hexa           # quantum-seeded ML training pattern
hexa run examples/03_router_fallback_demo.hexa       # show router attempt/reason chain

Env vars:

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)

Repo layout

qrng/
├── README.md                              # this file
├── LICENSE                                # Apache-2.0
├── CHANGELOG.md
├── CITATION.cff
├── AGENTS.tape                            # identity + governance (.tape v1.2)
├── CLAUDE.md                              # → AGENTS.tape (Claude Code auto-discovery)
├── hexa.toml                              # package manifest
├── install.hexa                           # hx install hook (system dep check + selftest)
├── 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 (dual_home_boundary.md, logo.svg)
└── state/                                 # gitignored runtime markers

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

Caveats

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.

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.1.0	https://github.com/dancinlab/qrng	5-source QRNG provider registry (this)

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

License

Apache-2.0 — 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

Optional Python aux deps (none today) would ship under their own licenses; in-process safe (no copyleft). qrng core stays Apache-2.0 under FSF MereAggregation.