ERC-8241: Protocol Control Disclosure

Discussion thread for ERC-8241 Protocol Control Disclosure

ERC-8241 defines a canonical machine-readable interface for structural protocol disclosure while intentionally separating verification, interpretation, and governance analysis into external systems.

eip: 8241

title: Protocol Control Disclosure

description: A canonical machine-readable interface for structural protocol disclosure covering protocol metadata, disclosure commitments, declared components, operational topology references, and retrieval semantics.

author: Chege Cjay ( @chegecjay-rgb )

discussions-to: https://ethereum-magicians.org/t/erc-8241-protocol-control-disclosure/28343

status: Draft

type: Standards Track

category: ERC

created: 2026-04-25

requires: ERC-165

Abstract

This ERC defines a minimal, canonical, machine-readable interface for structural protocol disclosure.

The ERC standardizes disclosure structure and metadata retrieval semantics while intentionally excluding verification logic, governance interpretation, operational judgment, economic safety analysis, and verifier policy.

ERC-8241 defines a declaration layer rather than a verification framework.

The mandatory core standardizes only structural disclosure primitives including:

  • protocol metadata

  • disclosure commitments

  • declared components

  • disclosure retrieval semantics

  • interface discoverability

  • machine-readable disclosure references

Verification systems, risk engines, scoring frameworks, governance analyzers, and transparency interpretation layers are intentionally externalized.

Motivation

Ethereum protocols increasingly rely on complex governance systems, execution surfaces, upgrade paths, operator roles, and interconnected infrastructure.

However, protocol disclosures currently lack:

  • standardized retrieval semantics

  • canonical machine-readable structure

  • interoperable disclosure interfaces

  • ecosystem-wide discoverability

  • consistent declaration formats

As a result:

  • wallets

  • auditors

  • governance systems

  • transparency tooling

  • monitoring infrastructure

  • analytics platforms

must rely on fragmented, inconsistent, or unverifiable disclosure methods.

ERC-8241 introduces a canonical disclosure surface that enables protocols to expose standardized structural declarations without imposing any particular governance philosophy, safety framework, or verification regime.

Specification

Core Scope

ERC-8241 standardizes:

  • disclosure structure

  • metadata retrieval

  • structural declarations

  • machine-readable disclosure references

  • ERC-165 discoverability

ERC-8241 does NOT standardize:

  • governance legitimacy

  • operational correctness

  • execution validity

  • verifier policy

  • economic safety

  • transparency scoring

  • risk interpretation

  • protocol trustworthiness

Canonical Layer Separation

The architecture is intentionally separated into independent layers:

Layer Responsibility
ERC-8241 Structural declaration
Proof of Operation (PoO) Execution disclosure
Ethereum Transparency Layer (ETL) Verification and interpretation

ERC-8241

ERC-8241 defines how protocols expose structural declarations and machine-readable metadata.

Proof of Operation (PoO)

PoO systems expose observable execution disclosures and operational event surfaces.

Ethereum Transparency Layer (ETL)

ETL systems consume ERC-8241 disclosures and execution evidence in order to perform:

  • verification

  • interpretation

  • risk analysis

  • governance analysis

  • policy enforcement

  • transparency scoring

Verification is intentionally externalized from ERC-8241.

Compliance

A contract is ERC-8241 compliant if it:

  1. Implements the core interface

  2. Supports ERC-165 discoverability

  3. Exposes required retrieval semantics

Compliance does NOT depend on:

  • verifier approval

  • governance models

  • extension support

  • ETL integration

  • risk scoring systems

  • external attestations

Extension Model

ERC-8241 supports OPTIONAL extension surfaces.

Extensions may expose additional metadata or ecosystem functionality without affecting compliance status.

Current extension categories include:

  • Discovery

  • Safety Interfaces

  • Audit Evidence

  • Profiles

Extensions are explicitly non-normative.

Rationale

The ERC intentionally separates:

  • disclosure

  • execution

  • verification

This separation:

  • prevents verifier centralization

  • avoids governance lock-in

  • enables competing transparency ecosystems

  • preserves protocol neutrality

  • allows independent ETL implementations

  • minimizes normative surface area

The ERC therefore remains lightweight, composable, and broadly interoperable across Ethereum infrastructure.

Repository

Canonical repository:

https://github.com/chegecjay-rgb/protocol-control-disclosure

Canonical specification surfaces:

  • ERC-8241.md

  • COMPLIANCE.md

  • core/

  • extensions/

  • docs/

Canonical documentation includes:

  • architecture.md

  • extensions.md

  • etl-integration.md

  • migration-history.md

1 Like

I’ve published the reference repository for the draft here:

The canonical draft is at the repo root as protocol-control-disclosure/erc-draft_protocol_control_disclosure_core.md at main · chegecjay-rgb/protocol-control-disclosure · GitHub

The repository also includes the Solidity reference implementation, supporting architecture/spec notes, and active Foundry test suites for the current narrowed core + integration surface.

Quick update: the ERC PR is now live and all automated checks are passing.

PR: https://github.com/ethereum/ERCs/pull/1706

At this point the submission is waiting on reviewer/code-owner review in the normal ERC process.

I wrote a follow-up post on why I think the Aave rsETH incident is a useful real-world example of the problem this ERC is trying to solve.

The point is not to blame Aave, Kelp, LayerZero, or any specific team. The deeper issue is that DeFi still lacks a common machine-readable way to inspect the control and dependency surface behind assets, protocols, bridges, custodians, oracles, and privileged upgrade paths.

That becomes more important as wallets, risk engines, explorers, auditors, and AI agents make more automated decisions.

That is also why I think the core standard should stay narrow: raw protocol control facts only — metadata, scope commitments, components, nodes, powers, edges, lookup rules, and freshness semantics.

Summaries, profiles, claims, diagnostics, and audit evidence can still be valuable, but they should remain optional and secondary.

Post here:
https://paragraph.com/@0x0afe5e054249b19ae29075540d9e6951c66e49b7/why-the-aave-rseth-incident-shows-we-need-protocol-control-disclosure-now-1

I wrote a brief follow-up on why I think ERC-8241 is worth taking seriously now:

https://paragraph.com/@0x0afe5e054249b19ae29075540d9e6951c66e49b7/making-the-case-for-erc-8241-protocol-control-disclosure?referrer=0x0AFe5E054249b19aE29075540D9E6951C66E49B7

Would appreciate feedback on whether the current draft is disciplined enough on that point.

Repository architecture and specification structure for ERC-8241 have been significantly refined to better separate normative disclosure semantics from verification infrastructure.

The repository now clearly distinguishes:

  • ERC-8241 → structural disclosure layer

  • Proof of Operation (PoO) → execution disclosure layer

  • Ethereum Transparency Layer (ETL) → verification and interpretation layer

Recent updates include:

  • canonicalization of the ERC-8241 core surface

  • formal compliance definition

  • clarification that extensions are OPTIONAL

  • separation of ETL verification concerns from ERC semantics

  • archival of historical research and experimental material

  • normalization of repository architecture for standards-track maturity

The repository now presents a cleaner standards-oriented structure centered around:

  • ERC-8241.md

  • COMPLIANCE.md

  • core/

  • extensions/

  • canonical documentation under docs/

Historical and experimental materials were preserved under research/legacy/ and research/drafts/ to maintain transparency and architectural continuity without affecting normative interpretation.

Canonical repository:

https://github.com/chegecjay-rgb/protocol-control-disclosure

Canonical documentation:

  • /docs/architecture.md

  • /docs/extensions.md

  • /docs/etl-integration.md

  • /COMPLIANCE.md

The goal of this restructuring was to transition ERC-8241 from an exploratory research repository toward a clearer standards-track architecture suitable for broader ecosystem implementation and review.

Some field data that may help scope the core, from the observed side rather than the declared side. I’ve been resolving control paths on-chain across a few hundred contracts: proxy admin, owner(), AccessControl holders, Safe signers and timelock delays.

1. The most common gaps are the ones a declaration layer would fix. Of the 34 largest stablecoins on Ethereum, 6 expose no standard admin pattern at all. They use custom controllers, old LogNote-style auth with no enumerable events, or immutables. Another 7 end at a contract no generic tool recognises. For those 13, nothing observable says who can change them. A disclosure with nodes and powers would be the only machine-readable source.

2. Declarations need an observable anchor per power, or they drift. For the powers that are observable, the primitives are well defined:

  • the EIP-1967 slots, plus the legacy ZeppelinOS slots, which USDC still uses;
  • owner();
  • AccessControl holders, rebuilt from RoleGranted events and confirmed with hasRole(), since most deployments aren’t Enumerable;
  • Maker wards;
  • Safe getThreshold/getOwners/modules/guard;
  • timelock getMinDelay/delay;
  • Aave-style immutable admins reached via ADDRESSES_PROVIDER().owner().

It might be worth letting each declared power carry an optional “observable at” reference (slot, selector or event), so a verifier can diff declared vs observed without guessing.

3. Signer type matters more than holder address. The same “owner is 0x…” means very different things for an EOA, a 1-of-1 Safe whose owner is an EOA, a 4-of-7 Safe, and a 72h timelock. In Morpho’s listed vaults, every vault discloses its timelock. None discloses whether the curator key is an EOA, and 22 of 122 resolve to a single EOA on-chain. A signerType and threshold field on nodes, plus a freshness block number, would cover most of what depositors actually ask.

4. Separate control powers from operational ones. Pauser, minter and burner roles held by hot EOAs are often deliberate. Treating them like the upgrade path made timelocked tokens look like single-key tokens in my first pass. A small power-class enum (upgrade/admin vs operational) in the core would stop verifiers from making the same mistake.

If useful as a test case for the verification layer, I’m happy to map the JSON my observer produces (nodes = holders with signer type; edges = role → holder → signer) onto the ERC’s components/nodes/powers/edges and post the mapping here. Disclosure: I built that observer (OneKeyAway).

How should a consumer distinguish “no additional control paths exist” from “no additional control paths were disclosed”?

A protocol could accurately disclose its timelocked upgrade path while omitting an emergency bypass. Every declared entry could pass verification and the overall picture would still be misleading.

Could the core require an explicit completeness claim within a defined scope? Verification could remain external but consumers would at least know whether an omitted power means “absent” or “unknown”.

1 Like

The PR draft describes graph records and freshness, while the repository’s canonical interface exposes only disclosureURI(). It would help to clarify how these two surfaces relate.

For the graph-based model, what does manifestHash commit to? Would this transition be valid under the draft?

nonce = N:     manifestHash = H(M1), Power P -> controller A
nonce = N + 1: manifestHash = H(M1), Power P -> controller B

If the hash commits only to an external manifest, the spec should explain its relationship to the graph and what “manifest inclusion” guarantees. If it commits to the current graph or specific fields within it, consumers need a defined commitment domain and canonical encoding/root construction, including its relationship to the nonce, so they can reproduce the commitment. I don’t have a strong preference between these models, but the guarantees should be explicit.

For implementations using a disclosure nonce, should this also be normative?

Any change to the disclosed core state MUST strictly increase the disclosure nonce as part of the same atomic update.

That would support this pseudocode read pattern:

n1 = disclosureNonce()
read metadata / scope / components / nodes / powers / edges
n2 = disclosureNonce()
accept only if n1 == n2

This assumes sequential reads on one chain branch at nondecreasing block heights. Consumers can also pin all on-chain reads to one block hash independently of the nonce rule. Without the invariant, matching nonces would not establish that the records belong to the same version.

This is separate from completeness: even a disclosure claiming complete coverage needs a way for consumers to establish that they retrieved one consistent version.

1 Like

I maintain ownerwatch, an open-source monitor for admin changes on EVM contracts. Since the draft says it standardizes disclosure, not truth, and that independent verification remains necessary, I built the verification side against it and wanted to share it here.

ownerwatch disclosure check reads a disclosure (a JSON rendering of the core records: protocol metadata, scope, components, nodes, powers, edges, nonce) and checks every record at one pinned block, reporting the block hash: ok, mismatch, or unverifiable. It settles node types, Safe thresholds and signer counts, timelock delays, upgradeability, implementations, upgrade admins, owner(), AccessControl roles (every holder, replayed from RoleGranted/RoleRevoked logs up to the pinned block), and OWNER_OF / UPGRADE_ADMIN_OF edges. Power kinds that chain state cannot settle are reported unverifiable, never ok. ownerwatch disclosure draft produces a starting disclosure from chain state. Docs and the JSON mapping: ownerwatch/docs/erc-8241.md at main · imal1ice/ownerwatch · GitHub

On the question in #8 (how a consumer tells “no other paths exist” from “none were disclosed”): after checking what is declared, the checker lists control it observes on the declared components that no power declares. That makes a completeness claim scoped to the declared components mechanically falsifiable for upgrade admins, owner() and every AccessControl role holder. I’d suggest the spec make such a scoped completeness claim explicit, so “not disclosed” and “not present” stop looking the same.

On #9 (what manifestHash commits to, and the nonce): the checker defines manifestHash as keccak256 of the canonical JSON with the hash field left out, and pins all reads to one block. It would help if the draft fixed both: what exactly is hashed, and whether the nonce is normative.

Worked example on Aave V3’s Ethereum core, drafted from chain state: the disclosure shows the real governance loop (the PayloadsController, a timelock with a 1-day delay, owns Executor Lvl 1, which owns the PoolAddressesProvider, the Pool’s upgrade admin) and the 25 role holders on the ACLManager, and checks clean (89 records). Two edited copies in the repo show what the checker catches: stale timelock delays and a false “not upgradeable” (3 mismatches), and an omitted ACLManager admin and emergency admin (2 undisclosed powers).

One question for @chegecjay-rgb: the PR text describes on-chain graph records while the reference repo exposes disclosureURI() pointing at JSON. Which surface is canonical? I’d like the checker to target it, and I’m happy to contribute fixtures (accurate, stale, omission) as a Test Cases section.