GLOBAL GOLD · ENGINEERING RECORD · MODULE B1

B1 — GOLDN Utility Layer
System Specification

Status: Living document — v1.0 spec lock 2026-05-05 · BUILD-SPEC-FROZEN under R14⁗ APPROVED 2026-05-13
Amendments: annotation-only edits under "do not delete, just annotate" directive; no normative ABI / storage-layout change without ECO
Module: B1 (GOLDN omnichain utility layer)  ·  Owner: CWO (architecture) · AI pair (implementation)
Findings ledger: every audit finding indexed & status-tracked in B1_AUDIT_FINDINGS_LEDGER.md — the single source of truth for "what is open"
TABLE OF CONTENTS
§0Revision history — 30+ amendment rows (ECO process)2
§1Scope40
1.1What B1 is · What B1 is NOT · three protocol fee streams42
§2System boundary — inputs · outputs · one-way trust seams79
§3State machines118
3.1Sub-Lock · 3.2 Pool · 3.3 Reward epoch lifecycle120
§4Contract decomposition — 12 concrete + 13 interfaces272
§5Data model315
5.aUnits · constants (HARDCODED) · multiplier curve (B-D-02)317
5.cPer-contract storage blocks (locker · gauge · rewards · fees)576
§5.5Trading fee + emissions mechanism1680
§6Roles & access control — timelock topology (ECO-12)2914
§7Lifecycle flows, plain English — Flows A through N3125
§8Invariants — I1 … I49 + post-split families3730
§9Open architectural questions — Q1–Q26, all RESOLVED3942
§10Build sequence4408
§11Test list (system level) — unit · fuzz · invariant rows4434
PUBLIC EXCERPT — addresses, keys, economic parameter values and exploit-relevant mechanics are redacted. Structure, section index, invariant IDs and status stamps are shown as recorded.
BUILD-SPEC-FROZEN
R14⁗ APPROVED · 2026-05-13 PM
B1_SYSTEM_SPEC.md≈4,980 lines · v1.0 spec lock

§8 — Invariants (excerpt)

These are the system properties that must hold at all times. They become the basis of invariant tests.
I1
Σ(subLocks[user][i].amount) over all users == GOLDN.balanceOf(veLocker), per chain. Custody integrity. No phantom locks; no missing GOLDN.
I3
For every user: voteAllocationSum[user] ≤ userVeGOLDN(user). Hard cap enforced at write time; auto-trim on veGOLDN decrease. Users cannot allocate more votes than veGOLDN.
I4
Per-pool: poolGaugeWeight[p] == Σ voteAllocation[u][p]. Global Fubini identity: Σ_p poolGaugeWeight == Σ_u voteAllocationSum == chainTotalAllocatedVeGOLDN. Sum-of-rows = sum-of-columns; checkable in O(1) via running counter.
I8
For every trade: of fee → LPs, of fee → GGFeeDistributor — atomic; no path skips the protocol cut. Fee correctness per B-D-07. Split values redacted.
I23
Voluntary vote decreases require block.timestamp ≥ voteAllocationLockedUntil[u][p]; increases reset the cooldown, per (user, pool) pair. Curve-style hard-lock defense against snap-and-revert gauge gaming (B-D-21).
I26
Sleeping veGOLDN earns no rewards in any stream: voteAllocationSum == 0 ⇒ zero accrual across system pool, per-pool fees, and emissions — structurally, by multiplication by zero. Delegation-not-locking principle, in code form.
I27
When poolTotalQualifiedWeight == 0 over [t_a, t_b], the cumulative reward index does NOT advance; the would-have-flowed emissions are forfeited, never back-paid. Per-call index advance hard-capped at . Conservation-clean forfeit; closes the JIT vector and the L2-outage inflation primitive (ECO-15).
I-Pending-
Voter-Cap-1
poolPendingVoters[poolId].length ≤ at all times; enforced at the sole append site. Bounds the activatePool sweep — no actor can brick activation by Sybil registration (ECO-C5).
I-CEI-8
Every externally-callable function that mutates B1 storage or makes a non-view external call MUST carry nonReentrant (OZ v5) — enforced at build time by a Yul-walker over every impl artifact.
§8 of 11 · invariant registerexcerpt · values redacted