# Technical Reference (Aligned to White Paper v1.5)
Revision: Feb 6, 2026 (clarifies supply partitions, issuance vs deposits, and redemption timing)

This document provides the formal math, constants, and flows referenced by `whitepaper.txt`. Section numbers map to the white paper.

---

## T0. Definitions and Precision (White Paper sections 1, 2)
- Share supply max (`SHARE_SUPPLY_MAX`): fixed at `600_000_000_000_000_000` shares (6e17) = 100% (immutable).
- USD-equivalent unit model (illustrative): `TOTAL_USD_EQUIV_UNITS = 600_000_000_000_000` (600T) and `DOLLAR_SHARES = 1_000`, so `SHARE_SUPPLY_MAX = TOTAL_USD_EQUIV_UNITS * DOLLAR_SHARES`.
- Supply partitions (all values in shares; sum always equals `SHARE_SUPPLY_MAX`):
  - `reserve_pool_shares`: protocol-owned, unissued shares. A portion may be time-locked as an operator unlock pool; the remainder may be used for deterministic issuance (genesis conversion and optional asset deposits).
  - `burned_shares`: shares in an irreversible burn sink (monotonically increasing; never reissued).
  - `circulating_shares = SHARE_SUPPLY_MAX - reserve_pool_shares - burned_shares`.
- Percent per share: `percent_per_share = 100 / SHARE_SUPPLY_MAX` (1 share = 1 / SHARE_SUPPLY_MAX of max supply).
- Labels (immutable UX aliases):
  - `PILLAR_SHARES = 1` share (atomic label; equals `MIN_SHARES`).
  - `DOLLAR_SHARES = 1_000` shares (exactly 1 unit in a 600T USD-equivalent unit model).
  - `PENNY_SHARES = 10` shares (exactly 0.01 label-dollar; 1/100 of `DOLLAR_SHARES`).
  - Extend via new labels only; never mutate existing label constants.
- Smallest transfer unit (`MIN_SHARES`): 1 share. Transfers below this floor revert.
- Rounding: floor to `MIN_SHARES` on all debits/credits; return dust to sender or reject the tx.

## T1. Monetary State and Invariants (White Paper sections 2, 7)
- State tuple: `(shares_balances, backing_amount, reserve_pool_shares, operator_unlock_pool_shares, burned_shares, yield_pool_shares)`.
- Invariants:
  - `SHARE_SUPPLY_MAX` is constant (fixed at genesis).
  - `reserve_pool_shares` may only decrease (issuance consumes reserve capacity; redemption does not replenish it).
  - `0 <= operator_unlock_pool_shares <= reserve_pool_shares`.
  - `burned_shares` may only increase (burn is irreversible).
  - `backing_amount` increases only via verified deposits into custody and decreases only via redemption out of custody.
  - `backing_amount` is the protocol-defined published backing anchor used for `vps` (and, when enabled, for issuance/redemption pricing). Its composition and valuation rules must be ratified and auditable.
  - Label-to-share constants are immutable.
- Value per share (for redemption/issuance pricing when enabled): `vps = backing_amount / circulating_shares`.

## T2. Transfers and Fees (White Paper sections 5, 6)
- Transfer amount: specified in shares (or label -> shares). Debit `sender_shares`, credit `receiver_shares` after fees.
- Usage fee (simple, non-compounding): `UsageFee_shares = shares_assigned * r_s * dt_seconds / seconds_per_year`, with `r_s` annualized (default 0.02). `r_s` may be fixed at genesis or computed deterministically from utilization within governance-bounded limits. Accrue linearly per epoch; floor each accrual to `MIN_SHARES`; carry accrued remainder across epochs to avoid drift.
- Base transaction fee (optional): `tx_fee_shares = max(MIN_SHARES, fee_rate * transfer_shares)`; floor to `MIN_SHARES`.
- Country transaction tax (sovereign policy, optional):
  - A Country Node may apply a jurisdictional tax up to `COUNTRY_TAX_CAP_PCT = 10%` in addition to network fees.
  - For a taxed transfer, `country_tax_shares = max(MIN_SHARES, floor(country_tax_rate * transfer_shares))`, where `country_tax_rate` is in `[0, 0.10]`.
  - Tax shares are credited to the sovereign treasury account; network fees are credited to protocol pools as defined elsewhere.
- Yield distribution per epoch `e`:
  - Let `eligible_shares = circulating_shares - yield_pool_shares` (exclude protocol-owned pools and burned/unissued shares from the payout base).
  - `holder_weight = holder_shares / eligible_shares`.
  - `payout_h = floor(yield_pool_shares * holder_weight, MIN_SHARES)`.
  - Deduct paid-out shares from `yield_pool_shares`.
- Conformance (rounding): if `transfer_shares=15`, `fee_rate=0.01`, `MIN_SHARES=1`, then `tx_fee_shares=1`, receiver gets 14.

## T3. Allocation Model (White Paper section 5)
- Assigning liquidity:
  - Allocator escrows `alloc_shares` from balance.
  - Usage fees accrue as in T2; at close, debit fees to `yield_pool_shares`, release principal (shares) back to allocator.
  - Allocator fee (risk/service): an optional allocator-specific spread `r_a` (bounded by governance) may accrue on `alloc_shares` over time; allocator fees are credited to the allocator and are distinct from the global `r_s` usage fee.
- Default handling:
  - If end-borrower defaults, slash from `alloc_shares` escrow up to loss; losses are borne entirely by allocator; nothing socialized.

## T4. Issuance and Redemption (White Paper section 7)
- Deposit flow (optional; disabled if `issuance_pool_shares == 0`):
  - Input: verified physical asset.
  - Pricing: let `vps_pre = backing_amount / circulating_shares` at request time.
  - Action:
    - Increase `backing_amount` by `asset_in`.
    - Issue `issue_shares = floor(asset_in / vps_pre, MIN_SHARES)` from `issuance_pool_shares` to the depositor (bounded by remaining `issuance_pool_shares`).
  - Effect: depositors receive shares at a deterministic price; `vps` is approximately stable (subject to rounding).
- Redemption flow (enabled only if backing is redeemable under the ratified custody/valuation rules):
  - Input: `redeem_shares` from holder.
  - Pricing: `asset_out = redeem_shares * vps_at_request`, where `vps_at_request = backing_amount / circulating_shares`.
  - Action: move `redeem_shares` to burn sink (increase `burned_shares`); decrease `backing_amount` by `asset_out`.
  - Effect: `vps` is approximately stable (redeemers withdraw at the same per-share price used for accounting).
- Scheduling:
  - Minimum redemption: `MIN_REDEMPTION_SHARES` enforced; requests below reject.
  - Cap per redemption window (length = `REDEMPTION_WINDOW_SECONDS`, not per settlement epoch): `REDEMPTION_CAP_BACKING_PCT` of backing per window; queue FIFO by request time.
  - Publish queue state, per-window cap, and expected `asset_out`; no discretionary prioritization.
- Edge cases:
  - DA impairment: if fragments missing, pause processing for affected epochs until recovered; keep queue order and publish status.

## T5. Ledger, Settlement, and Consensus (White Paper section 4)
- Batches: per epoch `e`, each Country Node emits batch `B_i^e` with hash `h_i^e = H(B_i^e)` containing share moves, fee events, issuance/redemption events.
- Global root: `R^e = MerkleRoot(h_1^e, h_2^e, ..., h_N^e)`; finality requires stake-weighted signatures >= 66% of eligible stake and signatures from at least `MIN_SOVEREIGNS` distinct sovereigns.
- StakeWeight: `SW_i = min(STAKE_CAP, Base_i * UptimeFactor_i * CorrectnessFactor_i)`; factors decay with faults/offline events with half-life `DECAY_HALFLIFE = 7 days`; requalification requires meeting uptime/correctness thresholds for a probation window `PROBATION_DAYS = 7`.
- Proposer/attestor rotation: deterministic randomness selects proposers/attestors per epoch; no proposer repeats consecutively if alternates exist.
- Slashing: double-signing a root or DA non-attestation when selected incurs `SLASH_FRACTION` of eligible stake (e.g., 5-10%) and exclusion until requalified after probation window.
- Anti-collusion: conflicting signatures slash stake weight and suppress future participation until requalified.

## T6. Data Availability (White Paper section 4)
- Erasure coding: split batch/state into `k` fragments; encode to `n > k`; distribute across Country + Processing Nodes.
- Availability attestations: require `m` independent attestations per epoch; sample `S` fragments uniformly at random; non-availability triggers penalties and exclusion from finality for that epoch.
- Attestation format: `{epoch, batch_id, fragment_ids, attestor_pubkey, signature}`.
- Parameters `(k, n, m, S)` set at genesis; changes require an upgrade while preserving monetary invariants.
- Processing nodes may serve as attestors; non-attestation when selected is penalized.
- DA penalty parameter (illustrative): `DA_MISS_PENALTY = 0.01` of eligible stake for missed attestation when selected.

## T7. Labels, Pricing, and Precision (White Paper section 10)
- Label mapping is static: `PILLAR_SHARES = 1`; `DOLLAR_SHARES = 1_000`; `PENNY_SHARES = 10`; extend via new labels only (never mutate existing labels).
- Minimum transfer: `MIN_SHARES` (and optionally per-label minima). Reject or batch sub-minimum transfers.
- Rounding: floor to `MIN_SHARES` on all computations; return excess (dust) to sender.
- UI: show balances in labels and in percent-of-supply; show backing and published `vps` (used for issuance/redemption pricing when enabled).

## T8. Privacy and Identity (White Paper section 8, optional)
- Base protocol: bearer shares; no identity required.
- Optional two-key model:
  - `spend_key` for transactions; `attest_key` for generating off-chain attestations/credit signals.
  - Attestations can be revealed selectively without linking spend history on-chain.
- Any KYC/credit signaling is off-chain and opt-in; protocol math is identity-agnostic.

## T9. Stress Scenarios and Checks (White Paper sections 6-10)
- Low activity: `yield_pool_shares` can trend to zero; no inflationary make-up. Confirm allocator solvency under fee droughts; simulate fee=0 for multiple epochs.
- Redemption cascades: enforce minimum redemption, redemption-window caps, and publish queue; maintain DA proofs; monitor backing and queue health; publish transparency data.
- Precision limits: enforce `MIN_SHARES`; monitor rounding loss; adjust labels only via new wrappers, never by mutating constants.
- DA loss: test m-of-n recovery; exclude non-attesting nodes from finality until recovery; verify reconstruction with `(k,n)` parameters.
- Adversarial tests: double-sign detection, censorship attempts (missing tx inclusion proofs), non-attestation penalties, fee accrual rounding over long intervals.

## T10. Genesis Conversion and Reserve Unlock (White Paper sections 1, 6)
- Genesis conversion (assumption): all participating commercial banks and central banks convert legacy deposits and debt obligations into Pillar accounts and allocation contracts under a ratified legal mechanism. For accounting, all legacy currencies are converted to USD-equivalent at a ratified FX snapshot; after genesis, FX is UI-only and does not affect monetary state.
- Genesis mapping (illustrative):
  - Convert each legacy balance `X_ccy` to USD-equivalent units at the snapshot: `X_usd = FX(ccy->USD)_snapshot * X_ccy`.
  - Map to shares deterministically: `shares = floor(X_usd * DOLLAR_SHARES)`.
- Illustrative genesis anchors:
  - Converted global monetary debt supply: 300 trillion USD-equivalent units.
  - Time-locked operator reserve pool: 300 trillion USD-equivalent units worth of shares, unlocking at 1-2% annually.
- Reserve unlock (operator subsidy, optional):
  - A designated sub-pool of `reserve_pool_shares` is time-locked as `operator_unlock_pool_shares`.
  - Define `issuance_pool_shares = reserve_pool_shares - operator_unlock_pool_shares`. Asset-deposit issuance draws only from `issuance_pool_shares` (operator-locked shares are not used for deposits).
  - Unlock schedule (deterministic): per epoch `e`, unlock `unlock_shares_e = floor(operator_unlock_pool_shares * reserve_unlock_pct_annual * epoch_seconds / seconds_per_year, MIN_SHARES)` with remainder carry to avoid drift.
  - Exponential decay: since `unlock_shares_e` is proportional to the remaining `operator_unlock_pool_shares`, the pool decays exponentially over time.
  - Distribution (anti-spam): distribute `unlock_shares_e` to eligible Country Nodes proportional to fee volume processed (not raw tx count). Zero-fee transactions do not increase rewards.
  - Eligibility: only nodes meeting finality + DA participation requirements for the epoch receive unlock distributions.
  - Accounting: decrement both `operator_unlock_pool_shares` and `reserve_pool_shares` by `unlock_shares_e` and credit the recipients' balances (increasing `circulating_shares`).

- `SHARE_SUPPLY_MAX = 600_000_000_000_000_000` (6e17)
- Labels: `PILLAR_SHARES = 1`; `DOLLAR_SHARES = 1_000`; `PENNY_SHARES = 10` (extend with new labels if needed).
- `MIN_SHARES = 1`
- Usage fee rate: `r_s = 0.02` (simple annually); `seconds_per_year = 31_536_000`
- Data availability: `k = 10`, `n = 16`, `m = 12`, `S = 8`
- Epoch length: 2 seconds
- Stake caps/decay: cap any single operator at 10% of eligible stake; correctness/uptime decay half-life `DECAY_HALFLIFE = 7 days`; `PROBATION_DAYS = 7`; `SLASH_FRACTION = 0.05` (illustrative).
- Redemption floor: `MIN_REDEMPTION_SHARES = 1_000` (~ one label-dollar); redemption window: `REDEMPTION_WINDOW_SECONDS = 86_400`; max redemption per window: `REDEMPTION_CAP_BACKING_PCT = 0.5%`
- Reserve unlock: `reserve_unlock_pct_annual = 0.01` (illustrative; bounded in governance).
- Country tax cap: `COUNTRY_TAX_CAP_PCT = 10%` (plus network fees).
- Governance change process: immutable items (share supply max, label table, burn policy) cannot change. Upgradable items (DA params, epoch length, caps/decay, redemption cap/window, reserve unlock bounds, fee rate bounds) require sovereign quorum >= 80% by weight and diversity >= `MIN_SOVEREIGNS`, plus a public time lock (e.g., 14 days) before activation.

## T11. Fairness and Participation Parameters (White Paper section 9)
- Diversity threshold: signatures from at least `MIN_SOVEREIGNS = 7` distinct sovereigns per epoch in addition to the 66% weight requirement.
- Weight cap: any single sovereign's eligible stake weight capped at 10% (immutable post-genesis).
- Proposer/attestor rotation: deterministic randomness for proposer/attestor selection each epoch; no sovereign may propose twice consecutively if alternates are available.
- DA attestors: include processing nodes in the `m` attestations; non-attestation triggers exclusion and penalty.
- Participation gating: eligibility for fee/yield share requires meeting availability/finality participation for the epoch.
- Requalification: after slashing or exclusion, re-entry requires meeting uptime/correctness thresholds for a probation window (e.g., 7 days).
- Audit cadence: custody attestations posted on-chain at least monthly; missing attestation excludes a Country Node from finality until posted; repeated misses subject to slashing as per governance.

## T12. Conformance Checks and Test Vectors
- Label mapping:
  - `PILLAR_SHARES / SHARE_SUPPLY_MAX = 1 / 600_000_000_000_000_000 = 1.6666666666666667e-18 of max supply` (percent = 1.6666666666666667e-16%).
  - `DOLLAR_SHARES / SHARE_SUPPLY_MAX = 1_000 / 600_000_000_000_000_000 = 1/600_000_000_000_000 = 1.6666666666666667e-15 of max supply` (percent = 1.6666666666666667e-13%).
  - `PENNY_SHARES / SHARE_SUPPLY_MAX = 10 / 600_000_000_000_000_000 = 1/60_000_000_000_000_000 = 1.6666666666666667e-17 of max supply` (percent = 1.6666666666666667e-15%).
- Fee rounding: `shares_assigned=500_000`, `dt=2s`, `r_s=0.02` -> accrual per epoch = floor(500_000 * 0.02 * 2 / 31_536_000) = 0 shares; after 1 day (~43,200s), accrual ~= floor(500_000 * 0.02 * 43,200 / 31_536_000) = 13 shares.
- Yield distribution (batched): `yield_pool_shares=100_000_000`, `holder_shares=1_000_000_000_000`, `eligible_shares ~= 6e17` -> payout ~= floor(100_000_000 * 1_000_000_000_000 / eligible_shares, MIN_SHARES) ~= 166 shares; shows non-zero distribution when pool is batched.
- Redemption cap: backing = 6e14 USD-equivalent units (600T), per-window cap at 0.5% -> max `asset_out` per window = 3e12 USD-equivalent units.

## T13. References
- White Paper sections: 1-16 in `whitepaper.txt` (v1.5).