eip: XXXX
title: Protocol Control Disclosure Core
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
discussions-to:https://ethereum-magicians.org/c/ercs/
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 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
Core compliance
A compliant implementation:
- MUST implement ERC-165
- MUST implement
IProtocolSafetyCore - MAY implement optional extensions such as:
IProtocolSafetySummaryIProtocolSafetyClaimsIProtocolSafetyProfilesIProtocolSafetyAuditEvidence
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
- optional manifest URI
- optional 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
PowerKindwhere 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.
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.