Spec: Comprehensive Protocol Analysis (Optimism Collective format)
This spec generalizes the analytical framework used in the Optimism Collective report. It is intended to be applied to any on-chain protocol and its sponsoring entity. Where the reference instance (Optimism) used specific proper nouns, generic language is used here, with illustrative examples drawn from Optimism in italics.
Report identity
Subject. A single on-chain protocol and its sponsoring entity or entities. The sponsor is whatever legal or quasi-legal structure administers the protocol’s treasury and publishes its official positions. Reference instance: Optimism Collective + Optimism Foundation.
Framing block at the top of every report. Publisher, current block height for every chain the protocol operates on, the protocol’s native token price at report date, report date itself. These anchor every number in the report to a verifiable point in time.
Structure. Five sections, each self-contained and readable in isolation: Protocol, Governance, Token Economics, Revenue & Treasury, Grants. The Grants section is conditional; if the protocol runs no grant program, omit it.
Central analytical thesis
Every section is in service of one question: where does discretionary authority sit, and is the stated governance narrative consistent with what is on-chain.
The report answers this by first identifying the distinct authority holders in the protocol, then classifying each one by whether it acts alone or requires co-signature, then classifying every control path, fee parameter, token flow, and treasury movement against that taxonomy. The implicit verdict emerges from the distribution: how much surface area falls under unilateral discretion of a single entity versus joint or independent control.
Illustrative example from the reference instance. Optimism’s taxonomy resolved into three lanes:
- Joint authority. Proxy Admin Owner Safe, 2-of-2 between Foundation and Security Council. Required for all protocol upgrades.
- Foundation unilateral. Fee parameters, gas limits, batcher identity, OP token minting, Governor admin, ProtocolVersions, L2ERC721Bridge upgrades. No co-signature required.
- Security Council unilateral. Emergency pause, dispute game blacklist, revocation of Foundation’s delegated Guardian access. Narrow scope.
For a different protocol, the lanes will not be the same. A protocol with a foundation, a security council, a DAO, and a technical committee might resolve into four or five lanes. A protocol with a single multisig and no independent parties resolves into one. The spec is the classification move, not the particular lanes.
Section 1: Protocol
Purpose. Catalogue every contract that constitutes the protocol across every chain it touches, identify who can upgrade or configure each one, and flag any exception to the standard control pattern.
Required per-contract fields.
- Name, functional category (e.g., core logic, bridge, fee collection, withdrawal security, governance token, messaging, registry), deployment pattern (upgradeable proxy, immutable contract, predeploy, etc.), and the specific proxy type if one is used.
- Deployed address and implementation address (when a proxy is in use).
- Function. What the contract does in plain language. For contracts that hold live configurable values (fee parameters, thresholds, gas limits), include the current values as of the report date.
- Reference Architecture. Upstream dependencies (what this contract reads from) and downstream consumers (what reads from it). This is what lets the control analysis compose.
- Control. The authority that can upgrade the implementation, plus any separate owner or admin roles with state-level authority (e.g., a config contract where one party can upgrade the implementation but another controls the stored parameters). Call out bifurcated authority explicitly when it exists.
Required coverage.
- Every contract on every chain the protocol operates across. Group by chain. Reference instance: Optimism covered L1 contracts on Ethereum mainnet (ProxyAdmin, SuperchainConfig, SystemConfig, OptimismPortal, bridges, dispute game contracts, etc.) and L2 predeploys on OP Mainnet (L2 ProxyAdmin, messaging predeploys, fee vaults, governance token, etc.).
- Exception contracts. Any contract that deviates from the standard admin pattern gets flagged. Reference instance: L2ERC721Bridge was administered by the Foundation directly rather than the standard L2 ProxyAdmin, giving the Foundation unilateral upgrade authority over one specific contract.
Required narrative callouts after the catalogue.
- Upgradeability summary. Is there any immutable programmatic core, or is the entire protocol mutable by the upgrade authority.
- Control history. When did the current control structure take effect, and what preceded it.
- Fee mechanics or equivalent economic parameters. How they decompose, who sets them, and whether the setting authority is the same as or distinct from the upgrade authority.
- Bifurcated authority. Every case where upgrade authority and operational/owner authority diverge.
- Pause or emergency authority. Who formally holds it, whether any delegated or revocable access path exists for another party to exercise it.
Section 2: Governance
Purpose. Show the full control dependency chain, enumerate governance bodies and their budgets, classify every authority by who can exercise it, and surface internal control weaknesses.
Required components.
Control dependency diagram. One lane per authority type identified in the central thesis. For each lane: which multisigs or contracts sit on it, what they control, and any cross-lane relationships (e.g., a delegated-and-revocable capability granting one party access to another party’s role). Reference instance: joint lane (Proxy Admin Owner Safe), Foundation unilateral lane (SystemConfig owner, MintManager owner, OP Governor admin, batcher, fee recipient), Security Council unilateral lane (Guardian Safe) with a DeputyGuardianModule relationship letting the Foundation reach Guardian functions through the Council’s Safe.
Governance bodies catalogue. For each body: type (elected council, sponsor entity, advisory board, technical committee), composition rules, address if it operates a multisig, functional description, and budget per operating period. Reference instance: Security Council, Optimism Foundation Multisig, Grants Council, Milestones & Metrics Council, Budget Board, Developer Advisory Board.
Authority cards. One card per authority, grouped by lane. Each card carries: threshold (m-of-n), name, address, description, and a scope tag strip listing the specific powers.
Signer overlap analysis. A matrix mapping known signer addresses across every multisig the sponsor entity controls. Flag any address appearing in multiple wallets. Compute whether a small coordinated group can meet thresholds across the entire treasury. Reference instance: Optimism had two addresses appearing across all four Foundation multisigs, and three addresses that could meet 3-of-n thresholds across the Allocated Budget, Approved Budget, and Grants Wallet.
Governance thresholds table. For each proposal type recognized by the protocol’s formal governance: quorum, approval percentage, veto threshold, veto rights holder. Plus narrative on how proposals are submitted, any gating requirements (e.g., delegate approvals before a vote), any exemptions that let specific parties bypass gates, and any distinct paths for specific proposal types.
Internal controls and risk register. Flag concrete weaknesses observable in policy or on-chain behavior. Categories to consider: grant misuse reporting thresholds that create safe harbors; circular funding risks (grantees self-delegating or self-funding); enforcement fragmentation across multiple bodies; centralization risks including proposal submission concentration; any policy breach observable on-chain.
Communications and transparency. Document events where the sponsor entity’s public communications diverge from observed on-chain activity, or where material information is withheld despite community requests.
Section 3: Token Economics
Purpose. Account for every token from genesis forward. Show what the sponsor entity still controls, what it has distributed, and how disclosure gaps manifest.
Required components.
Initial allocation. Total genesis supply, then each allocation category with percent and absolute amount. Include a rounding reconciliation note if categories do not sum exactly to the total. Reference instance: Ecosystem Fund, RetroPGF, User Airdrops, Core Contributors, Investors.
Sub-fund breakdown. For any allocation category that is itself subdivided, list the sub-allocations with amounts and percentages.
Programmatic distribution rounds. For any recurring distribution program tied to the token (retroactive funding, public goods funding, airdrop waves): round number, date, amount distributed.
Sponsor treasury current holdings. Total tokens held, native token USD value at report date, percent of total supply. Then one card per treasury wallet: threshold (m-of-n), name, address, balance in tokens and USD, and any non-treasury roles attached to the wallet. Reference instance: three Foundation multisigs, one of which also held the MintManager Owner role controlling token inflation, and another of which held the OP Governor admin role.
OTC or private sales. Every private sale with date, amount, proceeds, implied price, lockup terms, buyer identity if disclosed. Narrative on sponsor statements about future sales and subsequent behavior.
Distribution history. Year-by-year breakdown, split into “against sponsor budget” and “not against sponsor budget” (e.g., airdrops, OTC sales, programmatic grants that do not draw from the sponsor’s own allocation). Show totals per year and each line item.
Cumulative budget spend. Original sponsor budget, cumulative spend, utilization percentage, retained holdings. Close with a bottom-line classification stating the magnitude of retained control in specific numbers.
Section 4: Revenue & Treasury
Purpose. Trace every flow of value from users into protocol-controlled addresses, identify where that value stops being autonomous, and document treasury operations.
Required components.
Fee architecture flow. Trace user payments from the point of entry to their terminal address. Identify every intermediate contract, every split point, every hardcoded constant. Reference instance: user transaction fees decompose into three predeploy vaults (priority fees to SequencerFeeVault, base fees to BaseFeeVault, L1 data fees to L1FeeVault), all three withdraw() to a single hardcoded L1 RECIPIENT which is a BitGo WalletSimple multisig.
Terminal recipient card. Address, contract type (Gnosis Safe vs alternative multisig format vs EOA), lifetime volume per upstream source, signer discretion scope.
Revenue breakdown across chains. If the protocol spans multiple chains or has a revenue-sharing arrangement with partner chains: total fees in native token, historical USD value, concentration percentage. Per-chain table of lifetime fees and percent of total. Pricing note distinguishing historical USD from current-price USD. Narrative on any revenue-sharing formula, including how the formula reconciles to sponsor-stated percentages. Reference instance: OP Mainnet and Base together accounted for 97.8% of all Superchain revenue; the revenue-share formula was max(2.5% of gross, 15% of net).
Upcoming revenue model. If a new revenue mechanism is planned or in rollout, diagram the flow and note whether it routes through configurable addresses or autonomous paths. Reference instance: the Isthmus FeeSplitter adding a revenue share layer on top of existing fee vault architecture.
Treasury and staking. Total native-asset treasury position, staked amount per custodian, estimated yield, non-staked amounts on each chain, operational reserves. Compare actual allocation against any stated treasury policy. Flag breaches with magnitude. Reference instance: staking policy capped counterparty exposure at 20%; actual allocation ran approximately 30% each to BitGo and Coinbase.
Projected treasury plan. Forward-looking allocation across custody strategies (institutional staking, liquid staking, unstaked reserve).
Unresolved items. Any on-chain movement the sponsor entity has not publicly authorized through governance. Each gets its own card with transaction hashes, block numbers, amounts, recipient address and labeling status, and the open question. Reference instance: a 6,400 ETH deposit from a Foundation EOA into EtherFi with no located governor proposal; a 180 ETH outflow to an unlabeled recipient.
Revenue classification summary. Close with a one-paragraph verdict on whether any autonomous programmatic distribution exists, or whether every value flow terminates at an entity-controlled address.
Section 5: Grants
Purpose. Quantify the grant program’s lifetime deployment, compare outcomes across funding cycles, and surface delivery-rate trends.
Omit this section if the protocol runs no formal grant program.
Required components.
Overview stats. Total grant fund, total distributed, operating budget (council/board overhead), remaining unallocated. Plus an allocation visualization showing the split.
Per-cycle dashboard. One card per funding cycle with: cycle name and phase designation, percent of total fund, total distributed, date range, governance model in effect for that cycle, proposal count, passed count, delivery rate percentage. Reference instance: eight seasons from Apr 2022 through present, spanning direct Token House votes, Grants Council review, Mission Requests, Intents framework, and Budget Board phases.
Program evolution. A flow describing how the program structure changed across cycles. Who makes decisions, what filters get added, what selection criteria come into play.
Key observations. Four or five pointed observations drawn from the cycle data. Typical categories: dominance of any single cycle in total distributions; delivery rate variance across cycles; proposal volume inflation decoupled from approval rate; remaining capacity expressed in forward-cycle runway.
Cross-cutting analytical patterns
The report applies the same analytical moves in every section. These are the patterns to preserve when applying this spec to another protocol.
Separate authority axes. Upgrade authority, owner/operational authority, and pause/emergency authority are three different things that need to be tracked independently. A contract can be jointly upgradeable but unilaterally configurable.
Classify every multisig. For every multisig mentioned: threshold (m-of-n), contract type (Gnosis Safe, alternative multisig implementations such as BitGo WalletSimple, or custom), address, signer count, whether signer identities are public, what roles it holds beyond fund custody.
Compare stated policy to on-chain reality. Every public policy or commitment from the sponsor entity gets measured against observable on-chain behavior. Deviations are findings, with magnitude quantified.
Identify every hardcoded value. Any constant baked into an implementation contract that is not itself configurable through an owner interface. Flag it and note that changing it requires a full implementation upgrade, not an owner action. Reference instance: fee vault RECIPIENT addresses hardcoded in the vault implementations.
Trace delegated and revocable capabilities. Where formal authority sits with one party but operational access is granted to another via a revocable mechanism. Distinguish this from direct authority. Reference instance: the DeputyGuardianModule pattern, where Guardian authority formally belongs to the Security Council but the Foundation accesses it through a revocable module.
Follow the value flow to its terminal address. Every fee, grant, and treasury movement ends somewhere. Report the terminal address, its contract type, its signers, and whether any programmatic constraint governs disposition.
Surface disclosure gaps as findings. Unauthorized-looking on-chain movements, undisclosed buyer identities, non-public signer lists, and missing governance authorizations are all first-class findings, not footnotes.
Anchor every quantitative claim. Block numbers for state observations, transaction hashes for specific events, dates and native-token prices for dollar figures.