Guidelines on How to write EIP
Do's and Don'ts including examples
Writing and EIP is not easy, and people make mistakes when writing EIP. In this article I would like to touchdown, how to write a good EIP and give you tips before you publish your EIP and even list examples of perfect EIP.
I hope this article will help you master your EIP, and be a helpful guide on the common mistakes EIP authors make so you won't make the same mistake but rather create a great EIP.
EIP Intro
EIP stands for Ethereum Improvement Proposal, it is a part of the Ethereum core governance process which works in order to improve the Ethereum platform, including core protocol specifications, client APIs and contract standards.
EIPs are separated into a number of types and each has its own category. Core, Networking, Interface, ERC, Meta, Informational.
ERC stands for Ethereum Request (for) Comments, it is one of few categories of EIPs. These are application layer standards including token standards, name registries, URI schemes, library/package formats and wallet formats. This is the most popular category, which has more than 5000 EIPs in and counting.
Full EIP process, on how to write an EIP is described in EIP-1.
Do’s
Do read EIP-1
It is your manual on how to write an EIP, it defines everything that the EIP needs to include, how to write it, the process and all that.
Do add Tests to your EIP
In order for your EIP to have a higher success rate, have a bigger chance to be popular and used, you should definitely add tests to your EIP/ERC.
Do ask for community feedback
Post your EIP on Eth Magicians forum for community feedback. Make sure to engage with other posts, and give feedback to your peers too. This step is important as EIP Editors rely on community feedback in order to approve EIP that users like. It's highly recommended to add link to the Eth Magicians discussion thread to your EIP Draft.
Do add Abstract to your EIP
Abstract is an overview of your EIP, it provides the user the reason to use your EIP.
Do keep your initial EIP drafts short (small)
And keep it as short as possible even as it moves through Review and Last Call. Providing too much Motivation, or having an excessively large Test Cases section only means that you’re more likely to make errors that will block your EIP from being merged or moving forward. Keep it short.
Use the latest eip-template.md
Please. You won’t believe the amount of EIPs we have to refactor because they’ve used something like EIP-1155 or EIP-20 as a template instead of the file that is designed to be a template
Don’ts
Don’t overcomplicate and over-engineer your EIP
Keep the EIP simple but also writing and EIP for single use is not useful either.
Don’t submit an EIP Immediately after writing it
Take your time to proofread it, make sure to get grammar checked before publishing your EIP.
Don’t standardise the interface for gaming contracts
It may not be interoperable across the network. There’s no need to write interface EIP for contracts if it won’t be used across the network by more projects across more contracts. Unless other contracts need to be interoperable with your contract with the same interface. You may want to standardise this for your own purposes but it doesn’t benefit the whole community
Don’t write an EIP to make protocol more complex
A common mistake that people think is that people want to add EIPs to add a lot of complexity to the protocol. The reality is opposite, Core Devs and people working on the Core protocol layer are trying to keep things as simple as they can.
Don’t update the community on a DAO you created via EIP repository
It’s not providing utility to the community as a whole to provide this information. Use whatever channels you use to build your own community like blog posts, twitter or other social media.
Don’t abandon your work
There has been a handful of EIPs where authors put work into writing a quality EIP. But they actually never merged it in and came back, interacting with the feedback from the community and EIP editors.
Great EIP examples:
EIP-5313- It was proofread/grammar checked before submitting, and just as large as it needed to be.
And please please please PLEASE read EIP-1 before submitting an EIP 🙏
Further reading:
What the heck is EIP and how can I create one — EIP FAQs
EIPs All Blockchain Developers Should Know
Further watching:
Writing an EIP with Matt Garnett
EIP Editing with Matt Garnett
Thank you to EIP Editor Pandapip1 and Ethereum Cat Herder Pooja Ranjan for providing resource material for this article!
