---
eip: 8241
title: Protocol Control Disclosure
description: A canonical machine-readable interface for raw protocol control disclosure covering metadata, scope commitments, components, nodes, powers, edges, and freshness boundaries.
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: 165
---

## Abstract

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

The ERC core standardizes raw protocol control disclosure, while summaries, claims, profiles, diagnostics, and audit evidence are optional extension surfaces or verifier-side interpretations.

The mandatory core standardizes only raw structural facts:

- protocol metadata
- disclosure scope commitments
- declared components
- graph nodes
- privileged powers
- control edges
- canonical identifiers
- lookup / ordering / zero-value semantics
- freshness boundaries
- ERC-165 discovery

This ERC does not standardize safety ratings, trust scores, criticality labels, policy conclusions, or canonical risk taxonomies.

## Motivation

Wallets, explorers, scanners, auditors, AI agents, and users need a common way to retrieve raw machine-readable facts about protocol control.

Today, the most important control information is often fragmented across:

- documentation
- audit PDFs
- repositories
- dashboards
- frontends
- project-specific schemas

That makes comparison brittle, independent verification expensive, and downstream integrations inconsistent.

What is missing is not another rating system. What is missing is a thin canonical layer for raw protocol control disclosure.

## Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.

### Core compliance

A compliant implementation:

- MUST implement ERC-165
- MUST implement `IProtocolSafetyCore`
- MAY implement optional extensions such as:

  - `IProtocolSafetySummary`
  - `IProtocolSafetyClaims`
  - `IProtocolSafetyProfiles`
  - `IProtocolSafetyAuditEvidence`

Optional extensions are not required for base compliance.

### Core records

The mandatory core consists of raw machine-retrievable records:

#### ProtocolMetadata

The core MUST expose:

- protocol name
- claimed `standardVersion`
- chain ID
- manifest hash

The core MAY additionally expose:

- manifest URI
- metadata URI

#### DisclosureScope

The core MUST expose current scope commitments including:

- covered components
- covered assets
- exclusions
- assumptions
- scope-related declarations

#### Component

A `Component` MUST identify:

- component address
- associated `nodeId`
- declared type
- manifest inclusion status
- upgradeability status where applicable
- implementation address where applicable
- admin/controller node ID where applicable
- metadata commitment hash where applicable

#### GraphNode

A `GraphNode` MUST identify:

- canonical `nodeId`
- declared node type
- optional address binding
- manifest inclusion status
- metadata commitment hash where applicable

#### PowerDescriptor

A `PowerDescriptor` MUST identify:

- canonical `powerId`
- declared `PowerKind`
- enabled status
- target
- controller node ID
- raw execution parameters where modeled, such as threshold, controller count, delay, or bypass flags
- scope / notes commitment hashes where applicable

#### GraphEdge

A `GraphEdge` MUST identify:

- canonical `edgeId`
- declared `EdgeKind`
- related `PowerKind` where applicable
- source node ID
- destination node ID
- raw relationship flags such as directness where modeled
- notes commitment hash where applicable

#### Freshness

The core MUST expose a freshness boundary for current-state disclosure, such as:

- a monotonic disclosure nonce
- update events for core-state changes

### Canonical identity model

`nodeId` is the canonical identity for authorities and system-relevant nodes.

Address bindings are optional compatibility helpers and MUST NOT be treated as sufficient to represent every real authority structure.

### Lookup behavior

For declared-record lookup functions, undeclared records MUST revert unless a specific existence helper explicitly defines another behavior.

Missing-record behavior MUST NOT be inferred from zero-value structs.

### Ordering behavior

Where index-based enumeration exists, ordering MUST be deterministic.

Consumers SHOULD prefer canonical IDs over numeric indices.

### Zero/default semantics

Unless a stricter field-specific rule is defined:

- zero values mean unset, undeclared, unbound, or no stronger claim made
- zero values MUST NOT be interpreted as affirmative safety guarantees

### Declared facts only

Core outputs are declared facts about the implementation’s current disclosure state.

They do not, by themselves, prove:

- safety
- completeness
- honesty
- live-system equivalence
- absence of undeclared dependencies

## Rationale

Protocol control is not flat.

Real authority often propagates through:

- proxy admins
- timelocks
- multisigs
- governance executors
- modules
- guards
- bridge adapters
- multi-hop execution paths

A graph-native disclosure layer is therefore more useful than a flat checklist.

The core is deliberately narrow so consensus can form around what raw facts are disclosed, rather than around one universal risk or review taxonomy.

## Backwards Compatibility

This ERC is additive.

It does not change token behavior, governance semantics, proxy mechanics, or custody mechanics. It defines a machine-readable disclosure surface over existing deployments.

## Security Considerations

This ERC standardizes disclosure, not truth.

A malicious implementation can still omit dependencies, under-report powers, misstate scope, or publish misleading helper layers.

Independent verification remains necessary.

## Test Cases

Foundry test coverage for the reference implementation is maintained in the public repository. The active public suite currently covers the registry and integration surfaces of the narrowed core.

## Reference Implementation

A reference implementation exists in this repository, centered on:

- `IProtocolSafetyCore`
- graph-native disclosure records
- freshness / nonce boundaries
- optional extension surfaces for secondary outputs

The reference implementation is not a substitute for independent verification.

## Copyright

Copyright and related rights waived via CC0.