SKIP TO CONTENT
ETHEREUM STANDARDS6 minStandards That Ship / Ep. 1 · Stage 1-2

ERC Proposals: What Reviewers Need in the Document

A reviewer opens your ERC proposal. What must she find before she can test it, and what makes her wait?

XIN
Pixel-art illustration of a glowing proposal card riding a track of light through a graveyard of stalled proposals toward a lit gate.

IN 30 SECONDS

An ERC document is the written spec that reviewers test: an exact interface, a rationale and security considerations, with optional tests and code. This stage shows what goes in it and what helps or hurts review.

KEY TAKEAWAYS · 3

  • The interface is the heart of an ERC, so it has to be exact.
  • Keep the scope narrow. Ship several focused ERCs, not one that tries to do everything.
  • EIP-1 makes the reference implementation optional. Working code still makes the interface testable.
On this page

What goes in the ERC document

IN SHORT The document records the design; the discussion and the code test whether others can use it.

WORDS TO KNOW

Interface
The list of functions and events a contract must offer, so other code knows exactly how to call it.
Reference implementation
Example code that shows the rules of a proposal working. EIP-1 makes it optional.
Allowance
The amount of your tokens that another address may spend.

The Interface The list of functions and events a contract must offer, so other code knows exactly how to call it. See the glossary is the heart of an ERC. It’s the part other teams will write code against, so it has to be exact.

STEP BY STEP

Layered stack diagram: 7 layers, top to bottomLayered stack diagram: 7 layers, top to bottom. Layer 1, Abstract: Expected. Layer 2, Motivation: Optional. Layer 3, Specification: Expected. Layer 4, Rationale: Expected. Layer 5, Test cases: Optional. Layer 6, Reference implementation: Optional. Layer 7, Security Considerations: Required.ABSTRACTExpectedMOTIVATIONOptionalSPECIFICATIONExpectedRATIONALEExpectedTEST CASESOptionalREFERENCE IMPLEMENTATIONOptionalSECURITY CONSIDERATIONSRequired

Step 1. Abstract. State the real interface and scope. Don’t promise anything the spec never defines. The optional Motivation names the concrete pain point.

Pick a step to see it move
  1. Abstract State the real interface and scope. Don’t promise anything the spec never defines. The optional Motivation names the concrete pain point.
  2. Specification Function signatures (each function’s name and inputs) and events, exact enough to write code against.
  3. Rationale The tradeoff you took and the one you rejected. Answered objections live here.
  4. Tests and code Both optional for an ERC. Without test cases, I read a spec as one nobody has run.
  5. Security Required. EIP-1 rejects a proposal without a Security Considerations section.
The main parts EIP-1 says each EIP should have. Some are optional, Security Considerations is mandatory; the notes are my advice.

IN PLAIN WORDS

A Reference implementation Example code that shows the rules of a proposal working. EIP-1 makes it optional. See the glossary is optional in EIP-1. It turns an abstract text into something a reviewer can run.

Coming up next: So what does a reviewable proposal look like next to one that isn’t?

A worked example: one focused proposal, one kitchen sink

IN SHORT A reviewer can test a narrow interface, and can only wait on one that promises everything.

WATCH OUT

Both sketches are teaching examples, and the scenario is made up. They aren’t complete standards or tested reference code, and the first isn’t ERC-7410’s real interface. The second shows an illustrative broad scope, not a real proposal or a measured outcome.

The focused sketch solves one problem: adjusting an existing Allowance The amount of your tokens that another address may spend. See the glossary. The kitchen sink tries to cover identity, payments and disputes at once.

A WORKED EXAMPLE

Illustrative numbers

PASSA focused proposal: adjust an allowance

INPUT

Scope
one problem: change an existing allowance
Interface
3 functions
Working code
yes, with tests (assumed)

WHAT HAPPENS

  1. A reviewer reads the whole interface quickly.
  2. She asks one precise question: what happens if the decrease is larger than the allowance?
  3. The author answers in the thread and writes the edge case into the rationale.

OUTPUT

Verdict
reviewable: post it

SPLITA kitchen-sink proposal: one interface for everything

INPUT

Scope
identity, cross-chain checks, payments, keys, disputes
Interface
6 functions shown, 6 more promised
Working code
none

WHAT HAPPENS

  1. A reviewer can’t tell what each function must do, so she can’t test it.
  2. Each topic draws its own objections, from a different group of experts.
  3. Editors and reviewers wait for the author to define it.
IAgentEverything.sol (kitchen sink)
// Teaching sketch. One interface trying to be a whole platform.
// Illustrative broad scope, not a real proposal or measured outcome.
interface IAgentEverything {
    function authenticate(bytes calldata proof) external returns (bool);
    function verifyAcrossChains(uint256 chainId, bytes calldata data) external returns (bool);
    function settlePayment(address to, uint256 amount, bytes calldata terms) external;
    function registerIdentity(address agent, bytes calldata credential) external;
    function rotateQuantumKey(bytes calldata newKey) external;
    function resolveDispute(bytes32 txId, bytes calldata evidence) external returns (bytes32);
    // ...and six more the abstract promised
}

OUTPUT

Verdict
split it

ITEM GET

One ERC, one problem

Ship several focused ERCs, not one that tries to do everything. In my experience, each extra problem multiplies objections.

What makes a proposal easy or hard to review

IN SHORT A useful proposal lets a builder spot the problem, test the interface and raise a precise objection.

Scope
Solves one thing. Defines an interface, not the software that runs it.
Kitchen sink: each extra problem multiplies objections.
Spec and code
Working code makes the interface testable.
No signatures, no events, no test cases: reviewers assume you haven’t built it.
Author
Tracks and answers substantive comments.
No engagement after posting: the fastest way to get ghosted.
Problem
The motivation names a concrete pain point.
A buzzword-heavy title with no interface: editors wait for you to fill it in.
Co-authors
Catch blind spots on a proposal that spans several domains.
A solo author on a complex proposal.

Forum activity alone doesn’t prove quality or adoption. A quiet thread is a signal to investigate, not proof that an idea or an author has failed.

A long forum thread can mean a good idea, or a confused one.

So ask whether the problem is clear and whether the right builders have seen it.

Source: EIP-1.

FAQ

No. EIP-1 makes the reference implementation section optional. I recommend working code anyway: it exposes vague parts of the interface and gives reviewers something to test. It doesn’t guarantee acceptance.

STAGE CLEAR

What you now know

  • You can list the main sections EIP-1 says an ERC should have, and which ones are optional.
  • You can explain why a reviewer can test a narrow interface but can only wait on one that promises everything.

Check yourself

Tap or click a question to see the answer.

A proposal covers token transfers and cross-chain identity in one interface. What would a reviewer suggest?

Most likely to split it. In my experience, each topic draws its own objections from different experts, so each part may deserve its own ERC.

Next stage:How do you answer objections and get an ERC through community review?6 min
Adam Boudjemaa
Adam Boudjemaa

Former CTO of Integra. Named author (1 of 5) of ERC-3643, first author of ERC-6960, co-author of ERC-7410, and co-author of ERC-8203, which is still a draft. Building production AI and regulated Web3 systems.

Have a project to ship or a role to fill?

Discuss your project or role
LinkedInTwitterGitHub
Follow the engineering notes

Get new articles on production AI and smart contracts by email.