The Protocol Wiki is an open and collaborative project. Whether you are part of the Study Group or not, we welcome your contributions! Help us to build the documentation and improve availability of learning resources on Ethereum core R&D.
We are not aiming to rewrite other existing Ethereum documentation but rather create a cohesive collection of technical resources for aspiring core developers and researchers.
When creating contributions, consider whether it doesn't exist in another form elsewhere. Use it and reference it in your text but do not copy its content. Focus on adding it into a big picture, connecting it with related topics.
Write contributions based on what you learned about the protocol along the way, what experience you gathered and missing pieces that slowed you down. Consider it as explaining to your peers, reflect on your own journey as a core developer/researcher.
Before you start with editing, please read the code of conduct, following guide and make yourself familiar with the overall wiki structure.
The wiki source is hosted in Github repository at github.com/eth-protocol-fellows/protocol-studies. Github repo is the main coordination and hosting platform but wiki source is also mirrored on radicle and independent centralized host.
The wiki is served from
wiki-pagesbranch which is regularly updated frommain. When contributing, open a PR to a branch related to the change ormainfor smaller quick fixes. PRs from other branches are reviewed before merging tomainand collected updates are then pushed to update thewiki-pages.
Explore existing issues or open a new one for missing content, suggest improving existing content or wiki frontend features. If you identify missing or unfinished content, feel free to open a PR. First, check existing PRs or branches to make sure your work is not redundant.
We are not aiming to recreate other existing wikis. If the same content is well explained elsewhere, just link it and provide additional context.
The scope of this wiki is limited to technical resources of the Ethereum core protocol infrastructure. This means its specifications, implementations, testing, research or related tooling.
It does not cover onchain protocols/dapps, layer 2s/rollups or any other tools which are not dependencies of core infrastructure. In other words, stuff which would be covered by EIPs, not ERCs.
The wiki is supposed to cover all important parts of Ethereum core protocol and its development. The protocol architecture and related topics is reflected in the wiki format. The whole wiki lives under /docs/wiki and the /docs/_sidebar.md defines the main documentation structure.
High level areas are abstracted to directories which include all subtopics. Focus your contributions to wiki itself. Week pages in eps directory are meant for weekly presentations information, not main place for resources.
For contributors, we recommend focusing on specific topics contained in corresponding documents. It's best to own a single topic and work out all the details. Create a new document and add the topic to the sidebar if it's not there yet. Join the discord server, let others know what you are working on in the group channel and collaborate with other contributors writing about related topics. If you are working with multiple people on a significant piece of content, you can have a dedicated branch in the repo for easier coordination.
The wiki is a collection of regular markdown files which can be edited directly using github interface or your favorite markdown editor. When making commits and opening PRs, please provide a commentary explaining your contribution.
The web docs version is generated by Docsify. Learn about its config and features options. The configuration and web design is also open to improvements or suggestions.
For more extensive edits or changes to configuration, use Docsify to preview the web locally. You just need git and node.js.
Install docsify, clone the repository and host it locally.
npm i docsify-cli -g
git clone https://github.com/eth-protocol-fellows/protocol-studies.git
cd protocol-studies
docsify serve ./docs
Wiki pages follow standard Markdown which can be rendered by Github or Docsify. For details on using it, look into the Markdown guide.
The audience of this wiki is technical and the content should reflect that. There are many guides on technical and documentation writing you can learn from, for example you can check this lecture to get started.
Here are main guidelines to follow when writing this wiki:
- Write in an objective, clear and explanatory tone
- Avoid unnecessary simplifications, describe the technical reality
- Avoid using too long and complex sentences or paragraphs
- Use concise and clear statements
- Break down your text using blockquotes, bullet points or images
- Always link your resources and verify them
- Use bullet points or tables for topics which require enumerating
- Highlight keywords to support scanning and skimming through the article
- Provide visualizations to explain the topic better
- When using acronyms or a technical jargon, make sure to introduce it first
- Ethereum is changing fast, write the content to be as much future proof as possible
- Don't use LLMs to generate the text
- We don't accept texts fully generated by AI, however we recommend using it to fix grammar or phrasing
- Consider creating tutorials and hands-on guides documenting technical steps
- Add recommended reading at the top, point to topics which are dependencies of yours
- For mathematical notations, you can use Katex
- You can use mermaid diagrams for visualizations
Goal is to produce a credible neutral text which is formal, well-structured, and maintains a clear progression of ideas. The content should be purely technical and shouldn't waste space on introducing high level/well known concepts. Introductory topics are necessary and can use comparisons, historical anecdotes, and concrete examples to make complex concepts more accessible.
The wiki uses American English over British spelling. Terminology, capitalization and nomenclature should match across all pages. Use Ethereum.org guide for the reference.
Usage of images and visualizations is encouraged. If you are using an image created by a third party, make sure its license allows it and provide link to the original. For creating your own visualizations, we suggest excalidraw.com.
Feel free to use emojis or icons where it fits, for example in blockquotes.
When adding an external link, you can use it directly in the text or on the bottom of the page in "Resources" section.
When linking resources use descriptive names, such as inevitableeth.com instead of generic phrases like this wiki.
Don't overwhelm reader with too many resources within the text.
When linking a page within this wiki, use a relative path and if it references specific topic within the page, use a link to heading IDs.
For other important links, add a section on the bottom of the page with list of resources. Resources should have a name or short description with a link and alternative link to its archived mirror. We strongly suggest adding a link to the latest snapshot from archive.org. Example of a link in a resource section:
JSON-RPC API reference, archived
We use blockquote notices at the top of the page to provide readers with appropriate context regarding the content of the page.
Wiki pages that are subject to future updates, i.e. pages covering active research topics require a notice to be added on top of the pages:
* Warning message artifact using the following format:
> [!WARNING]
> This document covers an active area of research, may be outdated at time of reading and subject to future updates, as the design space around evolves.
To help user navigate across research topics, we are using a roadmap tracker with the following format:
| Upgrade | URGE | Track | Topic | Cross-references |
|:-------:|:-----------:|:---------:|:---------------------------------:|:-----------------------------------------------------------------------------------------:|
| ePBS | the Scourge | MEV track | Endgame block production pipeline | intersection with: [ET](/wiki/research/ET.md), [PEPC](), [IL]() |
Ideally, references point to a local wiki pages.
Pages with minimal content which need more work to cover the topic need to include a notice:
> :warning: This article is a [stub](https://en.wikipedia.org/wiki/Wikipedia:Stub), help the wiki by [contributing](/contributing.md) and expanding it.
This page is also opened for contributors! Suggest improvements to our style and guidelines in the github repo.