System architecture

STONK uses the Olympus Default Framework shape: a Kernel installs capability Modules and activates Policies. The token architecture is independent of the historical Olympus staking stack.

Components

Layer	Components	Responsibility
Tokens	STONK, StonkVault	liquid balances, vault custody, shares, and votes
Modules	ROLES, MINTR, TRSRY, PRICE	reusable protocol capabilities
Policies	RolesAdmin, OracleAdmin, BondDepository, TreasuryCustodian, Emergency	governed workflows combining Modules
Governance	StonkGovernor, StonkTimelock	voting and delayed execution
Clients	static frontend	public reads and user transaction construction

Trust boundaries

Chainlink feeds ----> PRICE ----> MINTR ----> STONK issuance
Robinhood tokens ------^             ^
       |                              |
       +----------> TRSRY <---- BondDepository

STONK <----> StonkVault ----> delegated votes ----> Governor ----> Timelock
                                                               |        |
guardian Safe ---- containment + cancellation only ------------+        +--> Kernel/policies

The frontend has no custody or authority. No offchain service writes prices or advances token accounting.

Vault accounting

StonkVault is OpenZeppelin ERC-4626 over STONK and uses the asset's 9 decimals. Shares are fixed-balance ERC20Votes tokens. totalAssets() equals STONK held by the vault. Conversion rounds according to ERC-4626 rules and includes OpenZeppelin's virtual-share defense.

Direct STONK transfers are permissionless donations and increase assets per share. This is the intended primitive for protocol revenue, but production revenue routing must identify the payer, accounting policy, and governance authorization. Donations do not mint STONK or stSTONK.

Timestamp checkpoints implement ERC-6372. Share transfer, mint, and burn update votes through ERC20Votes.

Issuance path

user quote asset
  -> BondDepository validates market and payout
  -> TRSRY receives reserve asset
  -> MINTR evaluates conservative backing
  -> vested STONK note

The deployment creates zero production markets. Market templates in configuration are not active authorization.

Price path

PRICE stores a bounded asset registry. Each read validates the expected feed, feed decimals and description, round completeness, timestamps, heartbeat, cap, deviation, asset decimals, category, and optional Robinhood pause status. Invalid data reverts rather than using a stale fallback.

There is no storePrice, signed price payload, offchain writer, or price key.

Governance path

delegated stSTONK -> propose -> vote -> queue -> Timelock delay -> execute

The Timelock is Kernel executor, Authority governor/policy, and RolesAdmin administrator in production. The genesis Safe is a temporary proposer. The guardian Safe can cancel and contain but cannot execute or restart. The deployer retains no role after handoff.

Units

Value	Unit
STONK, stSTONK, bond capacity and payout	9 decimals
PRICE and backing values	18-decimal USD
Quote deposits	quote token native decimals
Haircuts, market bump, slippage	basis points
Voting delay, voting period, Timelock delay	seconds

Clients must never mix USD18, token9, or native quote units.

Bounded state

The candidate bounds asset count, market count, per-user note slots, price movement, feed caps, bond payout, capacity, and governance delay parameters. ERC-4626 operations are constant-size and have no account iteration.

Deployment topology

Testnet and Anvil use mocks where canonical assets are unavailable and may seed demonstration markets. Mainnet resolves canonical addresses from config/chains.json, validates code and metadata, creates no market, and requires two independently controlled Safe proxies.

Deploy.s.sol writes a chain-specific manifest containing addresses, configuration, accepted sequencer mode, and runtime code hashes. VerifyDeployment.s.sol binds live state to that manifest from an independent RPC.