--- eip: 7865 title: Guidelines for Finalizing ERCs description: Tips for maximizing useful feedback and wide adoption for an ERC author: Bumblefudge (@bumblefudge) discussions-to: https://ethereum-magicians.org/t/new-erc-guidelines-for-writing-a-testable-adoptable-erc/22609 status: Draft type: Informational created: 2025-01-19 --- ## Abstract Unlike client EIPs which can be considered "final" when they are merged into the live network at a given fork, wallet and smart-contract ERCs have no definite structure for adoption, finality, or even interoperability testing. These notes describe concrete steps an ERC author can take to garner more confidence and interest from implementers, as well as collect more concrete feedback from them. If wallet and smart-contract communities-of-practice formalize into working groups or even explicit trustmark bodies, they may guide ERC authors through the considerations below or even administer conformance regimes and adoption timelines defined by them. Barring such formalization, however, this document overviews some practical steps any ERC author can take to narrow the gap between a "final" ERC and an adopted standard. ## 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. Most ERCs define new features, interfaces, or RPC messages at the level of wallet, browser, and/or smart contract; by definition, these specifications require no testable or normative behavioral changes on the part of Ethereum clients, or else they would EIPs. As such, the fork-based timelining and consensus mechanisms of the Ethereum clients working group (known informally as "AllCoreDevs") have no relationship to the EIP editors attributing "final" status to an ERC as they would on a `CORE` EIP. One could jump to the conclusion that wallet-based, browser-based, and smart-contract development should form 1 to 3 analogous working groups and gate "final" state similarly; However, at time or writing, there are 0 such formal working groups, and even if 3 arose tomorrow, it would be unwise to hand over all ERC decision-making to such formal bodies, and risky to assume they would operate continuously and healthily. Instead, best practices and git-based mechanisms for healthy and public coordination "above the client level" should be put into place as a function of the ERC process, regardless of whether these get managed by public working groups, by (invite-only) consortia of market players organized along ecosystem lines, or just by one or two authors of the ERC. These guidelines and mechanisms can be grouped into a few categories: ### Optimizing an ERC for adoption Many ERC "Motivation" sections are written in a happy-path vein, describing the use-cases for which this new solution or approach is the best or simplest solution. However, most evaluators walk away from an ERC not because it is a bad solution to the problem, but because it does not justify breakage, because its marginal utility or security could not be easily communicated to decision-makers (who leave it to languish on the product's backlog), or simply because alternate solutions are "good enough for now". The best way to write ERCs that get adopted is to first arrive at a complete draft, then go back and do a distinct pass of editing with a skeptical, breaking-change-averse, and multi-dimensional evaluator in mind. Some useful tips for putting yourself in such an evaluator's shoes include asking yourself: 1. Are targeted user stories clearly described in the "Motivation" section, and refered back to by any examples or "Test Cases"? If you enumerate multiple user stories, having one example of each helps, as evaluation is mostly (sometimes exclusively) focused on examples and diagrams rather than specification text. 2. Does the "Motivation" section reference existing solutions, including not just prior art but also partial or manual/"workaround" solutions observed in the wild? You may want to refer to them in the "Backwards Compatibility" section as well, or even include backwards-compatible fallback logic, e.g. as pseudocode. 3. Does the "Rationale" and/or the "Backwards Compatibility" section(s) outline the benefits of upgrading or bringing an existing solution to the same problem into conformance with your ERC, distinct from the benefits of implementing from scratch? 4. Does the "Rationale" section address trade-offs fairly? 5. Does the "Motivation" section address network effects and market dynamics objectively? Does it consider early adopters, or does it only describe the benefits of adopting _once critical mass of other actors_ have adopted it? ### Defining Conformance Many EIPs and ERCs limit themselves to describing a behavior simply, without fleshing out all the mandatory and recommended parsing behaviors it entails, the trust assumptions of each actor, and major or consequential corner cases. The best specifications are explicit and behavioral, including error-catching logic and consideration of failure flows and fallback flows. Even assuming a thorough specification with detailed behavioral expectations and crystal-clear flows, there are orthogonal, additional adoption benefits to adding "Conformance Considerations" after the Security and Privacy Considerations: * By precisely defining the desired behaviors of all roles involved in a flow or protocol interaction, it is easier to write test cases that cover all behaviors, including malicious and failure cases. * Such explicit conformance definitions expose side effects and obligations that aid thorough evaluation. * Furthermore, such actor-by-actor definition makes it easier for evaluators to map roles to their own business partners and understand what these counterparties would need to adopt or co-adopt the ERC's features. Good conformance considerations reduce as much ambiguity as possible when implementers self-assess their conformance to a given specification. In many cases, such ambiguity is harmless, but in high-stakes contexts like payments or privacy mechanisms, such "self-attested conformance claims" can be compounded by marketing or turn into ugly finger-pointing after security incidents. Highly testable conformance design can even enable an application or wallet to warn its users if a given counterparty is partially or dangerously inconformant. "Tiered" definitions of conformance ("full" versus "passive", for example, or "A/B/C" conformance) can forestall deceptive or confusing marketing, particularly combined with a "User Experience Considerations" or other mention of how to communicate capabilities to end-users. Since ERCs operate at the level of user-agents, browsers, [decentralized] applications, and deployed smart contracts, corner-cases multiply and runtime assumptions can be hard to verify with certainty. For this reason, we recommend looking for inspiration and guidance from the prior art and specification traditions of the Worldwide Web Consortium over those of the Internet Engineering Task Force, in particular the guidance on conformance in the 2005 [Quality Assurance Framework recommendation](https://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#specify-conformance). ### Permissionless Evaluation and Implementation Given the permissionless nature of Ethereum development, it is a mistake to interpret EIP participation on git forges, at Ethereum conferences, and on fora like Ethereum-Magicians as exhaustive or even representative of what developers are doing in regional markets, niche industries, and private networks. An ERC author cannot expect direct feedback from most implementers, nor can they expect to anticipate the unique contexts or pitfalls from those more distant implementers. The best way to ensure unknown implementers are producing software that is predictable and interoperable with known implementations is to publish (and publicize) implementation supports, ideally in the form of maintained git repositories. These can contain sample code, test vectors, test applications, test websites (stateless or stateful), test runners, configuration documents for RPC harnesses like Postman or browser runners like Selenium, etc. But most importantly, these repositories should contain a monitored issue tracker! The best way to design and iterate on such artefacts is, of course, in community, and the most efficient way of soliciting such input will be from stable, professional working groups. If these are not available, or the specific subject matter of an ERC is better served by an ad-hoc, one-off group of collaborators, the next best thing is to establish clear expectation between collaborators, and sooner than later transition from a closed conversation to a public one, where anonymous or unknown implementers and evaluators can contribute. Discoverability (both during the refinement process and long after its conclusion) are best served by a long-lived URL or organization on a public git repository. Posting this URL on the `discussions-to` link of the ERC is highly recommended, as well as anything else that helps evaluators and implementors the ERC find it easily. Note that URLs pointing to such materials are not allowed in the _text_ of ERCs and EIPs by the current links policy, but you MAY still refer in "Test Vectors" or "Conformance Implementation" to additional materials accessible from the `discussions-to` link. ## Rationale This informational document was inspired by the exemplary coordination process behind ERC-4361 and EIP-6963, EIPIP discussions with EIP editors, and discussions in the Chain Agnostic Standards Alliance. This informational document was inspired by the exemplary coordination process behind [ERC-4361](https://eips.ethereum.org/EIPS/eip-4361) and [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963), EIPIP discussions with EIP editors, and discussions in the Chain Agnostic Standards Alliance. TODO: update this section when exiting draft-PR stage to summarize additional conversations and influences ## Security Considerations Needs discussion. ## Copyright Copyright and related rights waived via [CC0](../LICENSE.md).