protocol-report-spec-2026-04-25

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:

1. Joint authority. Proxy Admin Owner Safe, 2-of-2 between Foundation and Security Council. Required for all protocol upgrades.
2. Foundation unilateral. Fee parameters, gas limits, batcher identity, OP token minting, Governor admin, ProtocolVersions, L2ERC721Bridge upgrades. No co-signature required.
3. 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.

Failure-prevention checklist

• Start by writing down the protocol’s real authority lanes before drafting prose: upgrade authority, owner or operator authority, pause authority, treasury-spend authority, mint authority, and any delegated or revocable access path that can exercise one of those lanes indirectly.
• For every contract or wallet named in the report, capture both the formal controller and the practical controller. If one multisig owns the contract but another module, deputy role, emergency path, or signer overlap can still move the same surface, preserve both facts.
• Trace user-paid value all the way to its terminal recipient. Stop only when the flow reaches an address or mechanism that can actually choose what happens next.
• Treat signer overlap as a first-class control fact, not a footnote. A nominally separate committee structure is analytically weak if the same small signer cluster can satisfy thresholds across the sponsor’s core wallets.
• Separate autonomous program logic from entity discretion. If value, upgrades, fee routing, minting, or treasury deployment terminate at an entity-controlled wallet, say so plainly instead of letting contract architecture language imply decentralization that the terminal authority does not deserve.
• Record every hardcoded constant that matters operationally: recipients, threshold parameters, bridge endpoints, mint caps, fee split constants, and emergency toggles. Hardcoded values are still control surfaces when only an implementation upgrade can change them.
• Compare public governance narrative against the exact onchain rights inventory as of the report date. If the narrative says community governed but one sponsor-controlled path still owns key upgrades, fee settings, treasury addresses, or emergency powers, the mismatch belongs in the main findings.
• Preserve time anchoring rigorously. Token balances, thresholds, signer sets, implementations, and even role holders drift; the report should let a reader reconstruct what was true at one exact block height.

Audit prompts

• Which exact roles or wallets can unilaterally change protocol logic, economic parameters, treasury custody, or emergency behavior today, and which of those powers are only described publicly as if they were shared?
• Where do upgrade authority and operational authority split apart, and which side of that split can still produce the economically decisive change?
• Which contracts, modules, or wallets look peripheral in the protocol diagram but actually terminate the user-value flow or hold the live ability to redirect it?
• If two bodies are described as independent checks on one another, do signer overlap, delegated modules, revocation rights, or common operational custody collapse them back into one effective authority cluster?
• What public policies, council charters, decentralization claims, sale commitments, treasury-allocation caps, or governance promises can be tested directly against onchain state, and what is the measurable magnitude of any breach?
• Which constants are only changeable by full upgrade rather than owner action, and does the report clearly distinguish hardcoded but mutable via upgrade from truly immutable behavior?
• Where does protocol revenue stop being programmatic and start being discretionary? Is that handoff disclosed plainly enough for a reader to understand who really controls retained cash flows?
• What missing information would materially change the authority map: undisclosed signer identities, unlabeled treasury addresses, non-public revocation powers, unverified buyer identities, or governance approvals that were claimed but not located?

Lessons that should already be standard

• Governance analysis should be an authority inventory first and a narrative exercise second. The useful question is not how decentralized does this sound, but who can still make the consequential change without asking anyone else.
• Multisigs are not independent just because their names differ. Shared signers, shared operators, revocable deputies, and common custody providers can collapse multiple boxes into one real control surface.
• Value-flow analysis is inseparable from governance analysis. A fee path that ends at an entity-controlled wallet is a governance fact even if the upstream collection logic is fully onchain.
• Upgradeable is too coarse to be informative by itself. Healthy reporting distinguishes implementation control, parameter control, emergency control, and distribution control because protocols often decentralize one lane while retaining the others.
• Public decentralization milestones should be measured against exact residual rights, not celebrated at headline level. One retained unilateral path over upgrades, minting, treasury, or fee routing can matter more than a large amount of surrounding governance ceremony.
• Hardcoded constants deserve the same scrutiny as owner-set parameters. If changing the recipient, cap, or routing constant requires an upgrade, that constant is still governed by whoever controls the upgrade lane.
• Reports become durable when every important claim can be replayed from addresses, thresholds, block heights, balances, and transaction hashes rather than from institutional self-description.

What sound design looks like

• A strong protocol-control report should let a skeptical reader reconstruct the live authority map without trusting the sponsor’s narrative. That means every consequential power has an address, threshold, holder, scope description, and time anchor, with delegated or revocable paths made explicit rather than implied.
• Healthy reporting separates authority lanes instead of flattening them into the multisig controls it. Upgrade power, parameter power, emergency power, mint power, treasury-spend power, and value-receipt power should each be tracked as distinct surfaces, because protocols often decentralize one lane while quietly retaining another.
• The report should terminate value-flow analysis at the first place real discretion begins. If fees end in a sponsor-controlled wallet, that fact belongs in the same frame as upgrade keys and governance thresholds; if value continues programmatically to users or tokenholders, that autonomy should be preserved just as explicitly.
• Good specs make exception handling first-class. Off-pattern contracts, unlabeled treasury wallets, special bridges, router conveniences, deployer remnants, or one-off admin paths should not get buried as caveats; the format should force them to surface where readers will actually understand their weight.
• Durable analysis should be replayable. If another reviewer cannot reproduce the report’s major claims from the cited addresses, blocks, balances, thresholds, and transactions, the spec has encouraged story over evidence.
• The simplest success test is: after reading a finished report, can a careful outsider answer who can change the system, who can pause it, who receives its retained value, and which public claims do not match chain reality without doing fresh archaeology? If not, the framework is not yet strict enough.