Introduction

So you want to write an EIP. Maybe you have an idea that will make EIP-20 tokens much more developer-friendly (EIP-1363). Maybe you were inspired to make a modular DAO system (EIP-5005). Maybe you have built a system to support meta-transactions (EIP-2771). In all these cases, you have a great idea, but there’s an obstacle in the way: the EIP Process.

This article assumes you know how to use GitHub, Git, Solidity, Markdown, and Visual Studio Code. If you don’t, STOP RIGHT NOW, learn them, and then come back.

The EIP Process

The EIP process exists in order to make sure that standards meet a minimum quality requirement. In essence, it ensures that if you want to implement a final EIP, then you can be confident that it has been adequately discussed, proofread, checked for typos, audited, and tested. It’s like a maximum height warning light by a bridge. If you can’t get the EIP through the EIP process (the light is flashing), then it probably wasn’t going to see a lot of mainstream adoption (your truck would have crashed into the top of the bridge).

EIP-1

EIP-1 sets out the rules mentioned above. Read it before you start writing your EIP. Try to understand as much as you can. Reread it as you are writing your EIP. Some parts will begin to make a bit more sense. When you have a draft you want to submit, read it again. It will save you time in the long run.

EIP Editors

EIP editors are volunteers who give their time in order to review your EIPs and make sure they pass the quality checks. They are there to point out the issues in your EIP so that it can be merged. It’s important to note that the EIP editors are on your side. We want to see your EIP move forward, and we’re here to make it as smooth as possible. If an EIP editor tells you that you must do something, to save time, accept the change and then ask questions. (NOTE: At the same time, do feel free to ask questions and offer feedback vis a vis the rules. It’s part of the way we make sure that our rules are perfectly fair.)

Some EIP editors (like me) edit almost daily and try to provide very detailed feedback. Most of them are constrained by time and edit once a week or less. This means that the shorter your EIP, the more likely it will be accepted. Short EIPs take less time to review and are less likely to contain mistakes that will block your EIP from being merged.

Continuous Integration

We have a bunch of checks that make sure that your EIP is okay to merge. If one of those checks fails, investigate it, and fix the error in the moment. It will save a lot of back and forth with EIP editors.

Writing the EIP

Setup

It can be tempting to use the GitHub built-in editor. I can disrecommend that for a few reasons. First of all, it’s a pain to use, doesn’t autosave, pollutes your commit history, and doesn’t have syntax highlighting. Secondly, there’s a much better alternative: Visual Studio Code, with my extension pack custom-built for authoring EIPs:

Fork the ethereum/EIPs repository, clone the fork, and open your local EIPs repository in VSCode. Make a new branch for your EIP and switch to it. Now you’re ready to actually start writing the EIP.

Configure the template

In the top-level folder, there will be a file called eip-template.md. Copy it to the EIPS directory. That copy will be your EIP. Open that file. You’ll see a lot of red lines.

This section will focus on this part:

---
eip: <to be assigned>
title: <The EIP title is a few words, not a complete sentence>
description: <Description is one full (short) sentence>
author: <a comma separated list of the author's or authors' name + GitHub username (in parenthesis), or name and email (in angle brackets).  Example, FirstName LastName (@GitHubUsername), FirstName LastName <foo@bar.com>, FirstName (@GitHubUsername) and GitHubUsername (@GitHubUsername)>
discussions-to: <URL>
status: Draft
type: <Standards Track, Meta, or Informational>
category (*only required for Standards Track): <Core, Networking, Interface, or ERC>
created: <date created on, in ISO 8601 (yyyy-mm-dd) format>
requires (*optional): <EIP number(s)>
---

Let’s go step by step through this.

Preamble: eip

eip: <to be assigned>

Ignore this. Your friendly neighborhood EIP editor will give you your number once you submit the PR.

Preamble: title

title: <The EIP title is a few words, not a complete sentence>

This is the title of your EIP. It shouldn’t contain the word standard. It’s an EIP. Everyone knows it’s a standard. Also, it should be descriptive. Here are some examples of good titles:

• Light Contract Ownership

  • This EIP is going to provide a lightweight standard for contract ownership

• EIP-20 Metadata Extension

  • This EIP is going to provide an extension to EIP-20 that will allow DApps to show additional properties of EIP-20 tokens

Here are some less good titles:

• SIWE CapGrok Extension

  • What is SIWE? What is CapGrok? Only use well-known acronyms in your title, or define them in your title.

• Zodiac Avatar Accounts

  • Same issue as the other title. What is Zodiac? What is an Avatar?

• Smart Non Fungible Token (SmartNFT)

  • This is too vague, and the title anthropomorphizes NFTs

Preamble: description

description: <Description is one full (short) sentence>

This is almost never a full sentence. Don’t sweat this.

Try not to repeat your title. It’s hard sometimes, but if you’re having trouble, it’s probably because your title is actually too descriptive.

Don’t use the word standard. Yes, we already know it’s a standard.

Preamble: author

author: <a comma separated list of the author's or authors' name + GitHub username (in parenthesis), or name and email (in angle brackets).  Example, FirstName LastName (@GitHubUsername), FirstName LastName <foo@bar.com>, FirstName (@GitHubUsername) and GitHubUsername (@GitHubUsername)>

People get this wrong a lot. If you’re an individual author, this is all you need to do:

author: Your Name/Pseudonym (@YourGitHub)

So, for me, it’s:

author: Pandapip1 (@Pandapip1)

It can’t be more straightforward.

Preamble: discussions-to

discussions-to: <URL>

Ignore this for now. You’ll fill this in when you submit a PR.

status: Draft

Don’t change this. It’s fine as-is.

Preamble: type & category

type: <Standards Track, Meta, or Informational>
category (*only required for Standards Track): <Core, Networking, Interface, or ERC>

It’s often hard to know what category your EIP should be in. So for now, just choose ERC (unless you’re making an opcode, in which case choose Core):

type: Standards Track
category: ERC

Moving on…

Preamble: created

created: <date created on, in ISO 8601 (yyyy-mm-dd) format>

Put today’s date. For example, 2022-09-02.

Preamble: requires

requires: <EIP number(s)>

If you’re extending another EIP, then put the number in like so:

requires: 20

If you’re extending multiple ones, put them in like so:

requires: 721, 1155

Otherwise, just delete it.

The placeholder text

This is the suggested template for new EIPs.

Note that an EIP number will be assigned by an editor. When opening a pull request to submit your EIP, please use an abbreviated title in the filename, `eip-draft_title_abbrev.md`.

The title should be 44 characters or less. It should not repeat the EIP number in title, irrespective of the category. 

Just delete this:

The Abstract

Don’t be intimidated by the name. This is basically a one-paragraph summary of your EIP. Describe your EIP in a sentence. Explain the motivation (why did you make this EIP?) in another sentence, and describe your specification as you would to a lay person, in an additional 2-3 sentences.

Don’t use first or second person. Use 3rd person passive voice. That means no I, we, or you. If you want to say I made a cool thing, say A cool thing was made instead. If you want to say You could do something else, say One could do something else instead. It’s a bit weird at first, but you’ll get used to it.

If you reference an EIP, make sure to link to it the first time you reference it:

The Motivation

If you’re new to writing an EIP, I recommend that you just skip this section. If it’s an issue, an EIP editor will prompt you to recreate the section.

The Specification

This is the fun part for most coders. If you’ve already made a solidity interface, just slap NatSpec on it, and there you have it!

Make sure that you set your SPDX-License-Identifier to CC0-1.0 if you include it. MIT, GPL-3.0, APACHE-2, etc… are NOT acceptable.

In addition, DON’T link to libraries like OpenZeppelin. Just assume that things like IERC20 exist:

Rationale

This is the most frequently misunderstood section. This isn’t asking why you made your EIP. It’s asking why you made certain decisions while making your EIP. Placeholders ARE acceptable while an EIP is in Draft, so for new authors I highly recommend just putting TBD as the entire content:

If you feel more confident, you can try actually writing a Rationale. Remember to use 3rd person passive!

Backwards Compatibility

This is one of those sections that people try to overdo. If you extend another EIP, then it’s assumed that this EIP will be compatible with the other EIP. You don’t need to re-state that. For now, just put the following:

No backward compatibility issues were found.

Test Cases and Reference Implementation

Before you dive in and make an excellent implementation of your EIP, with complete test cases using a fully-featured testing library like HardHat, remember something I said earlier:

Short EIPs take less time to review and are less likely to contain mistakes that will block your EIP from being merged.

Don’t spend time writing a complete set of test cases. Don’t spend time writing a complete Reference Implementation. Keep your EIP minimal, and delete those two sections:

Security Considerations

Placeholders are acceptable for this section. I recommend you use the following placeholder text:

Needs discussion.

Copyright

EIPs MUST be licensed under Creative Commons Zero v1.0. Add a blank line between the header and the text, if you want:

Submitting your EIP

Commit your changes and push

This should be familiar to anyone who has used Git before. Commit your changes, and use a descriptive message:

Then, push the new branch to your fork:

Now, go to ethereum/EIPs. You should be prompted to make a PR:

Click Compare & pull request, and fill out the fields. Once you’re done, submit that PR!

Discussions URL

This is the last step. Go to the following website and create a new topic for your EIP.

Put that link into your discussions-to URL:

Commit and push, and you’re done!

Next Steps

An EIP editor will eventually assign you an EIP number and provide you with other feedback. Just follow the directions they give you, and good luck!