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 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 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 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.

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.

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:

https://marketplace.visualstudio.com/items?itemName=pandapip1.eip-author-pack

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.

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.

eip: <to be assigned>

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

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

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.

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.

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.

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…

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

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

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.

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:

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:

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.

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:

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!

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.

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:

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

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

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!

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

https://ethereum-magicians.org/

Put that link into your discussions-to URL:

Commit and push, and you’re done!

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!

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 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 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 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.

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.

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:

https://marketplace.visualstudio.com/items?itemName=pandapip1.eip-author-pack

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.

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.

eip: <to be assigned>

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

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

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.

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.

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.

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…

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

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

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.

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:

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:

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.

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:

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!

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.

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:

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

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

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!

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

https://ethereum-magicians.org/

Put that link into your discussions-to URL:

Commit and push, and you’re done!

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!