Governance guide

STONK governance combines delegated gSTONK voting, an OpenZeppelin Governor, and delayed execution through StonkTimelock. Emergency authority is intentionally separate and strictly narrower.

Authority model

The Timelock is self-administered after deployment. No external account should retain DEFAULT_ADMIN_ROLE. Its executor role is open, which means execution liveness does not depend on one operator; execution still requires an operation that was validly scheduled and has finished its delay.

From staking to votes

1. Stake STONK to receive sSTONK.
2. Approve gSTONK to transfer sSTONK.
3. Wrap sSTONK at the current index.
4. Delegate gSTONK votes to an address, including yourself.

Wrapping does not create additional economic exposure. gSTONK locks sSTONK and represents it in a non-rebasing unit suitable for vote checkpoints. Unwrapping burns gSTONK and returns the corresponding current sSTONK amount.

Voting power is checkpointed. Acquiring gSTONK without delegation does not create active voting power for proposal snapshots.

Proposal lifecycle

Draft → Pending → Active → Succeeded → Queued → Executed
                    └──────► Defeated
          └────────────────► Canceled
                                Queued ─► Canceled by guardian veto

1. Review

Before submission, publish:

• a plain-language objective and motivation;
• exact target addresses, ETH values, and calldata;
• decoded function calls and parameters;
• changes to roles, modules, policies, assets, markets, or risk limits;
• executable simulation results against a current fork;
• rollback or emergency response where applicable; and
• the description text whose hash will bind the onchain proposal.

2. Propose

The proposer must have enough delegated voting power at the relevant checkpoint. A proposal is identified by its targets, values, calldatas, and description hash. Changing any of these creates a different proposal identifier.

3. Voting delay

The proposal remains Pending for the configured delay. This gives delegates time to inspect calldata and organize before voting opens.

4. Vote

During the Active period, delegates vote Against, For, or Abstain. The proposal must satisfy quorum and receive more For than Against votes under GovernorCountingSimple.

5. Queue

A successful proposal is scheduled through StonkTimelock. Queueing starts the execution delay and exposes the exact operation for monitoring. The guardian can cancel during this window.

6. Execute

After the Timelock delay, any account can execute the ready operation. The Timelock becomes msg.sender to the target contracts, which is why it holds protocol administration roles.

Mainnet launch parameters

The committed mainnet deployment input currently specifies:

These are deployment inputs, not a guarantee about a live instance. Deploy.s.sol creates no markets. The nine equity entries in config/mainnet.json are proposal templates totaling 4,500,000 STONK of possible payout capacity, not approved or active capacity. Integrators must query Governor, Timelock, Distributor, and BondDepository onchain.

Governed surfaces

Governance through the Timelock controls:

• Kernel module installation, upgrades, policy activation and deactivation, and executor changes;
• PRICE asset/feed registration through OracleAdmin;
• bond market creation and closure through bond_admin;
• Distributor rate through distributor_admin;
• TreasuryCustodian withdrawals through treasury_custodian;
• role grants and revocations through RolesAdmin;
• governance-only restart after emergency shutdown;
• Staking distributor replacement through Authority governor access; and
• Timelock and Governor parameters supported by their implementations.

Every proposal should name the narrowest affected surface and document its post-execution invariants.

Risk-change checklist

For oracle or asset changes, verify:

• token and feed bytecode on the target chain;
• token decimals and feed decimals;
• exact feed description and description hash;
• heartbeat, cap, haircut, category, pause awareness, and maximum deviation;
• current and preceding completed rounds;
• effect on total risk-adjusted reserves and backing per STONK; and
• behavior while the source market is closed or paused.

For bond markets, verify quote asset, start and floor price, decay, bump, capacity, maximum payout, vesting, conclusion, expected backing contribution, and unused mint allowance recovery. Also calculate aggregate active unsold capacity after execution; this is the maximum additional STONK all live markets may mint. It must fit the signed loss budget and STK-001 exposure ceiling.

For treasury withdrawals, simulate the exact post-withdrawal balances and prices. TreasuryCustodian enforces the backing floor, but governance should also assess concentration, liquidity, operational purpose, and oracle failure scenarios.

For module upgrades, compare storage layout and module version, enumerate every dependent policy, check requested selector permissions, test reconfiguration, and simulate upgrade and rollback.

Sequencer-protected PRICE upgrade

The initial mainnet PRICE module is explicitly unprotected under STK-001. When a canonical feed becomes available, the proposal should:

1. verify the uptime feed's official identity, bytecode, zero decimals, answer semantics, current status, and recovery timestamp;
2. deploy strict StonkPrice with the installed PRICE address as migrationSource and a reviewed grace period;
3. compare the complete copied asset registry and current strict prices on a current fork;
4. execute a single Kernel UpgradeModule action so all dependent policies reconfigure atomically; and
5. run the independent verifier after execution before retiring the public risk warning.

Cancel on any registry, feed, price, or policy-wiring mismatch. Do not replace the current module with a strict module whose registry was populated through a separate unreviewed sequence.

Guardian response

The guardian is a threshold Safe validated during deployment. It has two independent defensive capabilities:

• call Emergency shutdown functions to deactivate MINTR and/or TRSRY; and
• cancel a queued Timelock operation.

Shutdown is immediate because waiting for governance would defeat emergency response. Restart is deliberately excluded from the guardian and must travel through governance delay. The guardian should never be added as proposer, executor, oracle admin, bond admin, distributor admin, treasury custodian, or emergency restart authority.

Bootstrap phase

Production deployment gives a genesis Safe temporary proposer-only access so initial markets and voting distribution can be established before token governance is self-sufficient. It does not receive execution or cancellation authority. Once quorum and proposal creation are demonstrably live, governance should revoke the genesis proposer role.

Bootstrap is not complete until:

1. deployed source and manifests are verified;
2. roles match the production authority matrix;
3. voting power is distributed and delegated;
4. a non-critical proposal completes the full lifecycle;
5. guardian shutdown and governance restart are rehearsed; and
6. genesis proposer authority is revoked.

Proposal verification

Never vote from a title alone. Independently reconstruct the proposal ID and decode each action. Confirm:

• chain ID and deployed contract addresses;
• proposal state and snapshot/deadline;
• target code and implementation identity;
• calldata selector and decoded parameters;
• native value sent with each call;
• description hash;
• Timelock operation ID, predecessor, salt, readiness and cancellation state;
• expected role and state changes after execution; and
• whether any action introduces authority not disclosed in the description.

Use the application for discovery and transaction UX, but use RPC reads and an independent decoder for high-impact proposals.