STONK architecture

STONK uses the Olympus v3 Default Framework shape: a Kernel installs Modules and activates Policies. The lineage ends at the framework and rebasing mechanics; production price delivery is native Robinhood Chain and Chainlink infrastructure.

Trust boundaries

The deployer, automation accounts, and frontend backend have no steady-state roles. RolesAdmin is controlled by the Timelock. The Timelock is self-administered; no external account holds DEFAULT_ADMIN_ROLE.

Modules

• ROLES: validated bytes32 role membership.
• MINTR: sole STONK mint/burn path, active flag, and per-policy mint allowance.
• TRSRY: reserve custody, active flag, and per-policy/token withdrawal allowance.
• PRICE: asset registry and authenticated read-only valuation from Chainlink proxies. StonkPriceUnprotected is the explicit accepted initial module; strict StonkPrice adds sequencer status and recovery grace.

Module writes are callable only by active Policies holding exact Kernel selector permissions.

Oracle path

Each PRICEv2.AssetConfig stores:

getPrice() validates the Chainlink answer, nonzero round, preceding-round deviation, updatedAt, heartbeat, future timestamps, exact description, decimals, and Robinhood oraclePaused() state. Registry changes also require real ERC20 bytecode and valid token decimals. PRICE pins those token decimals and rejects live metadata drift; backing uses only the pinned value for scaling. tryGetPrice() returns zero for an invalid asset price so aggregate reserves remain conservative and liveness-safe. Strict bond-deposit valuation uses getPrice() and fails closed.

The initial mainnet module intentionally does not check L2 uptime because no canonical Robinhood Chain sequencer feed was found. Its immutable state reports protection disabled and zero feed/grace. Deployment requires an explicit accepted-risk mode, and the verifier rejects any mismatch. Strict StonkPrice requires a real uptime feed; for a later Kernel upgrade, its constructor accepts only the currently installed PRICE module as a migration source and validates/copies all registered assets before dependent policies are reconfigured. The full accepted failure mode is in docs/security/RISK-ACCEPTANCE-STK-001.md.

Equity feeds use a six-hour maximum age. Bond deposits therefore fail closed overnight, on weekends/holidays, and during a sustained active-session outage instead of treating a Friday close as current on Monday. USDG retains a 24-hour maximum age. The production service exports per-asset freshness and pause metrics.

Chainlink's Robinhood equity answer already includes the token UI multiplier. Applying uiMultiplier() again would double-adjust corporate actions and is prohibited.

There is no storePrice, pushPrices, offchain equity provider, price signer, or keeper oracle role.

Policies

• RolesAdmin: grants and revokes ROLES entries; admin is transferred directly to the Timelock contract during production deployment.
• OracleAdmin: adds, updates, and removes asset/feed configuration; oracle_admin is held only by the Timelock.
• BondDepository: creates fixed/decaying bond markets, values actual treasury balance deltas, enforces slippage and backing, mints vested notes.
• Distributor: computes min(rate reward, excess backing) and receives an exact transient mint approval.
• TreasuryCustodian: permits withdrawals only when post-withdrawal backing remains at or above STONK supply.
• Emergency: guardian shutdown is immediate; restart requires the separate emergency_restart role held by the Timelock.

Units and solvency

• STONK, sSTONK, payouts, and backing accounting: 9 decimals.
• Feed and bond prices: normalized to 18 decimals.
• gSTONK: 18 decimals.
• Reserve token decimals: pinned by PRICE at registration and revalidated on every price read.

usd18 = amount * price18 / 10^tokenDecimals
tokenValue9 = usd18 / 1e9, then volatile haircut
reservesValue9 = sum(configured treasury balances at valid prices)
excess9 = max(reservesValue9 - STONK.totalSupply, 0)

USDG upside is capped at $1. Every volatile asset has a timelocked absolute cap, a 20% maximum move from the preceding Chainlink round, and a 10% valuation haircut. Invalid aggregate prices contribute zero; invalid quote-token prices prevent deposits. Treasury withdrawals can never cross the backing floor.

Staking and automation

Staking.rebase() is public and processes at most 16 epochs per transaction. pendingEpochs() exposes backlog. Repeated calls safely catch up; stake and triggered unstake reject a backlog larger than one transaction can fully process, while untriggered unstake remains available as an exit.

Automation instances have no role. They use redundant RPC transports, transaction confirmation, bounded retries, health endpoints, and Prometheus metrics. A backlog beyond one cycle is reported and processed progressively instead of being treated as a keeper failure. Independent instances are intentionally redundant.

Governance clock

gSTONK implements ERC-6372 with mode=timestamp; Governor voting delay and period are seconds. Mainnet uses a one-day delay, five-day vote, and two-day Timelock. This is independent of Robinhood Chain block cadence.

Governance bootstrap

Production deployment pins Safe proxy and singleton code, validates both supplied multisigs with threshold >= 2, rejects a shared owner quorum, requires no guard or modules, and permits only a zero fallback handler or the pinned canonical Safe 1.4.1 compatibility handler. It then:

1. deploys and validates assets and feeds;
2. configures modules, policies, assets, and governance;
3. grants the Governor proposer/canceller access, the genesis Safe proposer-only access, and the guardian Safe cancel-only access;
4. opens Timelock execution;
5. renounces the deployer's Timelock admin;
6. transfers protocol administration and steady-state roles to the Timelock;
7. grants shutdown and queued-operation veto authority to the guardian Safe;
8. revokes every bootstrap deployer role and changes Kernel execution to the Timelock.

It does not create bond markets. Mainnet Distributor rate starts at zero. Market creation and any positive emission rate are separate delayed governance decisions subject to the security launch gates.

The genesis Safe cannot bypass the Timelock delay or cancel governance operations. Its proposer role is intended only to bootstrap markets and voting distribution, then be revoked by governance.