DEV Community: Hiroshi Ichiyanagi

Don’t trust me, verify me: openunit, a unit of account you can recompute byte-for-byte

Hiroshi Ichiyanagi — Sat, 13 Jun 2026 23:37:25 +0000

The promise

Most numbers you read about the economy ask for your trust. A price index, an exchange rate, a “fair value” — you take the institution’s word for it, because you can’t recompute it yourself.

openunit is built the other way around. It’s a small, open reference implementation of a unit of account: a measuring stick for value. The entire design goal is that you don’t have to trust me. You clone the repo, run two commands, and get the exact same number I published — down to the last digit — along with the exact same SHA-256 hashes. Change a single byte of the inputs and the hash changes and verification fails.

Don’t trust me. Verify me.

That sentence is the whole project in five words. This post is about how the reproducibility actually works, and why a measuring stick should be built this way.

What it is (and what it isn’t)

openunit is a fixed-basket index — think of the IMF’s SDR, but with the basket weights chosen by population instead of by reserve-currency politics. At a low-frequency “vintage” it pins a fixed quantity of each currency, derived from how many people each economy has. The unit’s value is then read off market (or PPP) exchange rates.

It is not money. It issues no token, holds no reserves, settles no payments, and predicts no returns. It only measures. The value is quoted in a numeraire (US dollars) purely as a readable denomination; the unit itself is defined by the basket.

Why population?

Expressing value in a single national currency bakes in the politics of whoever issues it. openunit counts people equally instead — one person, one vote.

I want to be upfront: that is a value choice, not a neutral fact. Population-weighting favors populous economies; GDP-weighting favors large ones; PPP-weighting favors welfare comparisons. openunit doesn’t pretend its choice is objective. It fixes the choice, writes it down, and makes it contestable — the method is auditable, so the politics of the weighting can be argued in the open instead of hidden inside an opaque index. (There’s a whole section of the spec, “On fairness,” that says exactly this.)

The engineering is what makes that honesty enforceable. If the method weren’t reproducible, “it’s a transparent choice” would be an empty claim.

How the reproducibility works

The engine is a single standard-library Python module — no third-party dependencies, on purpose. Five rules make the output bit-for-bit identical on any machine, any OS, and every Python from 3.8 up (3.8–3.12 in CI):

Exact arithmetic. Every number is parsed from a string into decimal.Decimal at precision 50, rounding ROUND_HALF_EVEN, inside an isolated context. No floats, ever. Float math gives platform-dependent rounding — exactly what you can’t have if hashes must match.
No wall clock. The engine never imports or calls datetime/time. The result depends only on the inputs, never on when it runs.
Canonical JSON for hashing. json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False), encoded UTF-8. Sorted keys, no insignificant whitespace, the same bytes everywhere.
SHA-256, twice. input_digest = hash of the canonical spec. artifact_hash = hash of the canonical artifact minus the hash field itself.
Strings in, strings out. Every quantity in the published artifact is an exact decimal string, so there’s nothing to re-round on the way back in.

The interesting part is how this is enforced, not just promised. A determinism guard (standalone and in CI across 3.8–3.12) checks four invariants:

same input → same output, including a full JSON round-trip;
no wall-clock read — verified two ways: a source scan and monkey-patching time.* to throw at runtime, so any hidden clock call would crash the build;
tamper detection — flip one field and verification fails;
the pinned realized weights equal the population shares at precision 60.

That second one is my favorite: the test literally poisons time.time and friends, then builds an artifact. If the engine touched the clock, it would blow up. It doesn’t.

The artifacts

Two real, pinned vintages ship in the repo. Each is a spec.json (the hashed input), an artifact.json (the built, self-verifying result), and a SOURCES.md with full provenance.

v0.1 — real market data. One person, one vote, on UN World Population Prospects 2024 and ECB euro reference rates (baseline 2026-01-09, valuation 2026-05-15):

1 openunit = 0.985631 USD
artifact_hash: sha256:1e615cf7…9a3a

Population-pinned weights: India 39.08%, China 37.39%, United States 9.24%, euro area 9.20%, Japan 3.24%, United Kingdom 1.85%.

v0.2 — PPP-aware. Same weights, but the value leg reads purchasing-power-parity rates from the World Bank (PA.NUS.PPP, ICP 2024), so the unit is read in international dollars:

1 openunit = 2.848010 international dollars
artifact_hash: sha256:566c95c1…b97a

Reading the unit at PPP shifts realized weight toward lower-price economies: India moves from a 39.08% headcount share to a 64.48% realized weight, while the US falls from 9.24% to 3.24%.

A small honesty note from building v0.2: the World Bank publishes no single “Euro area” PPP figure — I checked both the CSV and the API, and the cell is empty. So the euro-area factor is a population-weighted blend of the 20 member states’ real World Bank values, using the same UN populations as the headcount basket. It came out to 0.642950 — lower than a GDP-weighted blend would give, because low-price members carry real per-person weight. That’s documented as a contestable choice, not smuggled in.

Verify it yourself

This is the part that matters. Clone it and check my numbers:

git clone https://github.com/Hiroshi-Ichiyanagi/openunit
cd openunit
python3 test_determinism_guard.py     # 4/4 determinism checks
python3 make_vintages.py --verify     # vintages reproduce, byte-for-byte

You should see:

4/4 PASS
PASS  v0.1-2026-05-15 reproduces  hash=sha256:1e615cf7…9a3a
PASS  v0.2-ppp-2026-05-15 reproduces  hash=sha256:566c95c1…b97a
2/2 vintages reproduce

If your machine produces those exact hashes, you’ve independently confirmed the published values. If it doesn’t, something is wrong — and you’ll know. Nothing to install; it’s standard library only. There’s also a CLI (openunit build / verify / show) so you can verify someone else’s published artifact from just their spec.json and artifact.json. And for the strongest check, verify_independent.py is a second implementation written from the spec alone — it shares no code with the engine, yet recomputes the same hash. When two independent implementations agree, the number no longer rests on trusting my code.

Tamper-evidence

A measuring stick should also be hard to silently revise. openunit has an optional, offline, keyless hash-chain anchor: it commits an artifact_hash into an append-only record, so a publisher can show an artifact existed by some point and hasn’t been quietly changed. A local chain proves integrity and order, not time — so the record carries an external_proof slot (outside the commitment) for a public timestamp, and attaching one never changes any hash.

Both shipped vintages already carry one. Each artifact.json has an OpenTimestamps proof committed to the Bitcoin blockchain — BitcoinBlockHeaderAttestations at block heights 953507 / 953528 / 953536. So you don’t have to take 2026-05-15 on faith either: ots verify data/v0.1-2026-05-15/artifact.json.ots checks the artifact against the Bitcoin chain itself.

Where it’s going

v0.1 and v0.2 are real and pinned; the determinism guard is green across Python 3.8–3.12; an engine-independent verifier and Bitcoin-anchored timestamps already ship. Next: more real vintages as the dates roll forward, tightening the input domain (rejecting negative populations — currently disclosed and pinned by test, slated for v0.3), and writing the artifact format up as a standalone spec. It’s early — an alpha — and the point is precisely that you can check every claim above rather than take my word for it.

If you think population-weighting is the wrong value choice, good — that’s a real argument, and the method is fixed and auditable so we can actually have it. If you find a way to make the build non-deterministic, that’s a bug I want to know about.

Repo: https://github.com/Hiroshi-Ichiyanagi/openunit (Apache-2.0).

Don’t trust me. Verify me.

openreserve: offline-verifiable proof-of-reserves for the off-chain world

Hiroshi Ichiyanagi — Sun, 07 Jun 2026 11:45:22 +0000

"Are the reserves actually there?" has become a recurring, expensive question. A string of high-profile failures — where customer funds turned out not to fully back the liabilities — has made verifiable reserves a live concern rather than a back-office footnote. In parallel, there's a broader drift toward periodic, independently-checkable reserve attestation for some classes of issuers and custodians.

Most of the tooling people reach for here is on-chain: oracle-style proof-of-reserve systems (Chainlink's Proof of Reserve is the well-known example) designed for on-chain assets and smart-contract consumers. That's a real and useful domain — but it's not the one a payment processor, e-money issuer, wallet, or custodian lives in. Their ledger is in a normal database; their auditors and regulators are off-chain; an on-chain oracle is the wrong shape. openreserve is a small attempt at the off-chain gap.

What it is

openreserve is a dependency-free Python library (standard library only); install it with pip install openreserve. Given a ledger state — an append-only, double-entry ledger — and an explicit point in time, it produces and verifies:

Proof of Reserves — a Merkle tree over user-account balances plus reserve-account totals, with a solvency check (reserves >= liabilities). A user can verify their own balance is included via a Merkle proof, without the operator revealing other users' balances.
Proof of Solvency — per-currency proof-of-reserves aggregated with the audit chain's commitment hash.
Audit chain — a hash-linked event log (prev_hash → event_hash) with a verify_chain() that detects any tampering with past entries.
Reserve / deposit calculation — point-in-time required-reserve computation (settled balances plus in-flight obligations; negative balances excluded).

The artifacts are plain data. A proof's public summary is a JSON-serializable dict, so you can publish it at a static URL and a third party can fetch it and re-verify it offline using the same library primitives. openreserve does not ship an HTTP serving layer — exposing an endpoint is the integrator's job.

Proof of Reserves vs Proof of Solvency

These two are often conflated, so to be precise:

Proof of Reserves — evidence that the assets (reserves) actually exist / are held.
Proof of Solvency — evidence that assets ≥ liabilities: the reserves actually cover what is owed.

openreserve does both: a Merkle-committed reserve proof, plus a per-currency solvency check (reserves >= liabilities). The solvency claim is only as complete as the liabilities you include — see Limitations.

Who it's for

The common shape is an operator whose balances are an off-chain liability in a normal database, and whose auditors, counterparties, or regulators are off-chain:

E-money / prepaid-balance issuers — customer balances are liabilities that must be backed.
Payment processors / PSPs holding client or settlement funds.
Custodians, including the off-chain customer-balance ledger of a crypto exchange (the familiar "CEX proof-of-reserves" case).
Stablecoin issuers attesting the off-chain reserve backing (the reserve side, held in banks/custody — not the on-chain token).
Loyalty-point / closed-loop wallet operators — outstanding points are an off-chain liability.

In every case the question is the same: can a third party verify the reserves cover the off-chain liabilities, without trusting a dashboard?

The core property: determinism

The reason any of this is worth doing is that the proofs are deterministic. Proof generation takes the as-of / event time as an explicit, required input and never reads the wall clock. The same ledger state and the same timestamp produce a byte-identical Merkle root and audit hash.

This is the difference between "trust our dashboard" and "verify our proof." If the output depended on datetime.now(), no outsider could reproduce it. Because it doesn't, a regulator, auditor, or counterparty can take a published proof and check it themselves.

Don't trust me, verify me

The verification loop is one-directional — the operator publishes, anyone re-checks offline:

OPERATOR SIDE
  ledger state + explicit as-of time
        |
        v
  generate proof            (deterministic: same state + time -> same hashes)
        |
        v
  publish proof as JSON     (static URL or file)
        |
========|=====================================================
        v
VERIFIER SIDE  (auditor / user / regulator -- offline, no trust in operator)
  fetch proof JSON
        |
        +--> recompute Merkle root
        +--> verify audit chain   (prev_hash -> event_hash)
        +--> check solvency       (reserves >= liabilities)
        +--> (a user) verify own balance is included via Merkle proof

The repo ships a determinism guard you can run yourself (clone the repo and run the test suite):

python -m pytest tests/test_determinism_guard.py

It asserts (a) the same ledger state + same snapshot_at reproduces the same Merkle root and audit hash, and (b) with datetime.now patched to raise, generation with an explicit time still succeeds — i.e. the wall clock is genuinely never touched.

A minimal end-to-end example (after pip install openreserve):

from datetime import datetime, timezone
from openreserve import (
    Currency, Ledger, Money, OwnerType,
    ProofOfReservesGenerator, SQLiteLedgerStorage, TransactionBuilder,
)

T = datetime(2026, 1, 1, tzinfo=timezone.utc)  # explicit time — no wall clock
ledger = Ledger(SQLiteLedgerStorage(":memory:"))
platform = ledger.open_account(OwnerType.PLATFORM, Currency.JPY, "platform")
reserve = ledger.open_account(OwnerType.RESERVE, Currency.JPY, "reserve")
alice = ledger.open_account(OwnerType.USER, Currency.JPY, "alice")

def fund(src, dst, units):
    b = TransactionBuilder("FUND", "ops", initiated_at=T)
    b.transfer(src.account_id, dst.account_id, Money.from_units(units, Currency.JPY))
    ledger.post(b.build()); ledger.settle(b.transaction_id, settled_at=T)

fund(platform, reserve, 1_000_000)
fund(platform, alice, 300_000)

proof, _ = ProofOfReservesGenerator(ledger).generate(currency=Currency.JPY, snapshot_at=T)
print(proof.is_solvent, proof.user_liabilities_total_cents, proof.reserve_assets_total_cents)
# True 300000 1000000

Limitations

Being precise about what is and isn't guaranteed:

Determinism is on the time axis. Account and transaction identifiers are UUID-based, so two ledgers rebuilt independently won't share identifiers or hashes; identifier stability is not claimed. What is claimed: a given ledger state, at a given time, is reproducibly provable, and any published proof is independently verifiable. (Content-addressed, rebuild-stable identifiers are on the roadmap.)
Liabilities completeness. Like all proof-of-reserves, it proves assets cover the liabilities you include; it can't force you to include every liability. Per-user Merkle inclusion raises the cost of silently omitting someone, but it is not a substitute for an attestation of completeness.
No HTTP / serving layer. Publishing a proof at an endpoint is the integrator's job; the library only produces and verifies the artifacts.
No on-chain anchoring. A proof isn't committed to a blockchain today (it could be layered on top); the core stays off-chain.
Early and unproven. v0.1.1, no production adoption, APIs may change.

What it is not

Not on-chain, and not a replacement for or competitor to oracle-style PoR. Different domain, different consumers.
Not a compliance product. It makes no claim to satisfy any specific regulation, and nothing here is legal or financial advice. The regulatory climate is context, not an endorsement.
Not novel cryptography. It's a clean integration of standard primitives (Merkle trees, hash chains) with a determinism discipline — the value is in the assembly and the verifiability, not in inventing new math.

Status & roadmap

The determinism guarantee is on the time axis; UUID identifiers are the obvious next thing to make deterministic if cross-rebuild reproducibility is needed. There's no HTTP/serving layer and no on-chain anchoring (both could be layered on top). CI runs the suite on Python 3.11–3.13 plus a packaging check.

Apache-2.0. On PyPI (pip install openreserve); repo and issues: https://github.com/Hiroshi-Ichiyanagi/openreserve