RIP-7559: RIP Purpose and Guidelines

ATTENTION: The RIPs repository is in the startup phase, and so is undergoing many changes. This document is very much a work in progress. Both the process and how RIPs will be written and governed is still being worked on. Feedback encouraged on Ethereum Magicians.

What is an RIP?

RIP stands for Rollup Improvement Proposal. An RIP is a design document providing information to the greater Ethereum community, or describing a new feature for Ethereum Rollup/L2/EVM ecosystem. The RIP should provide a concise technical specification of the feature and a rationale for the feature.

RIP Header Preamble

Each RIP must begin with an RFC 822 style header preamble, preceded and followed by three hyphens (---). This header is also termed "front matter" by Jekyll. The headers must appear in the following order.

rip: RIP number

title: The RIP title is a few words, not a complete sentence

description: Description is one full (short) sentence

author: The list of the author's or authors' name(s) and/or username(s), or name(s) and email(s). Details are below.

discussions-to: The url pointing to the official discussion thread

status: TDB

type: One of Standards Track, Meta, or Informational

category: *One of Core, Networking, Interface

created: Date the RIP was created on

requires: RIP number(s) (Optional field)

withdrawal-reason: A sentence explaining why the RIP was withdrawn. (Optional field, only needed when status is Withdrawn)

Headers that permit lists must separate elements with commas.

Headers requiring dates will always do so in the format of ISO 8601 (yyyy-mm-dd).

author header

The author header lists the names, email addresses or usernames of the authors/owners of the RIP. Those who prefer anonymity may use a username only, or a first name and a username. The format of the author header value must be:

Random J. User <address@dom.ain>

or

Random J. User (@username)

or

Random J. User (@username) <address@dom.ain>

if the email address and/or GitHub username is included, and

Random J. User

if neither the email address nor the GitHub username are given.

At least one author must use a GitHub username, in order to get notified on change requests and have the capability to approve or reject them.

discussions-to header

While an RIP is a draft, a discussions-to header will indicate the URL where the RIP is being discussed.

The preferred discussion URL is a topic on Ethereum Magicians. The URL cannot point to Github pull requests, any URL which is ephemeral, and any URL which can get locked over time (i.e. Reddit topics).

type header

The type header specifies the type of RIP: Standards Track, Meta, or Informational. If the track is Standards please include the subcategory (core, networking, interface, or ERC).

category header

The category header specifies the RIP's category. This is required for standards-track RIPs only.

created header

The created header records the date that the RIP was assigned a number. Both headers should be in yyyy-mm-dd format, e.g. 2001-08-14.

requires header

RIPs may have a requires header, indicating the RIP numbers that this RIP depends on. If such a dependency exists, this field is required.

A requires dependency is created when the current RIP cannot be understood or implemented without a concept or technical element from another RIP. Merely mentioning another RIP does not necessarily create such a dependency.

Linking to External Resources

Other than the specific exceptions listed below, links to external resources SHOULD NOT be included. External resources may disappear, move, or change unexpectedly.

The process governing permitted external resources is described in RIP-5757.

Execution Client Specifications

Links to the Ethereum Execution Client Specifications may be included using normal markdown syntax, such as:

[Ethereum Execution Client Specifications](https://github.com/ethereum/execution-specs/blob/9a1f22311f517401fed6c939a159b55600c454af/README.md)

Which renders to:

Ethereum Execution Client Specifications

Permitted Execution Client Specifications URLs must anchor to a specific commit, and so must match this regular expression:

^(https://github.com/ethereum/execution-specs/(blob|commit)/[0-9a-f]{40}/.*|https://github.com/ethereum/execution-specs/tree/[0-9a-f]{40}/.*)$

Consensus Layer Specifications

Links to specific commits of files within the Ethereum Consensus Layer Specifications may be included using normal markdown syntax, such as:

[Beacon Chain](https://github.com/ethereum/consensus-specs/blob/26695a9fdb747ecbe4f0bb9812fedbc402e5e18c/specs/sharding/beacon-chain.md)

Which renders to:

Beacon Chain

Permitted Consensus Layer Specifications URLs must anchor to a specific commit, and so must match this regular expression:

^https://github.com/ethereum/consensus-specs/(blob|commit)/[0-9a-f]{40}/.*$

Networking Specifications

Links to specific commits of files within the Ethereum Networking Specifications may be included using normal markdown syntax, such as:

[Ethereum Wire Protocol](https://github.com/ethereum/devp2p/blob/40ab248bf7e017e83cc9812a4e048446709623e8/caps/eth.md)

Which renders as:

Ethereum Wire Protocol

Permitted Networking Specifications URLs must anchor to a specific commit, and so must match this regular expression:

^https://github.com/ethereum/devp2p/(blob|commit)/[0-9a-f]{40}/.*$

World Wide Web Consortium (W3C)

Links to a W3C "Recommendation" status specification may be included using normal markdown syntax. For example, the following link would be allowed:

[Secure Contexts](https://www.w3.org/TR/2021/CRD-secure-contexts-20210918/)

Which renders as:

Secure Contexts

Permitted W3C recommendation URLs MUST anchor to a specification in the technical reports namespace with a date, and so MUST match this regular expression:

^https://www\.w3\.org/TR/[0-9][0-9][0-9][0-9]/.*$

Web Hypertext Application Technology Working Group (WHATWG)

Links to WHATWG specifications may be included using normal markdown syntax, such as:

[HTML](https://html.spec.whatwg.org/commit-snapshots/578def68a9735a1e36610a6789245ddfc13d24e0/)

Which renders as:

HTML

Permitted WHATWG specification URLs must anchor to a specification defined in the spec subdomain (idea specifications are not allowed) and to a commit snapshot, and so must match this regular expression:

^https:\/\/[a-z]*\.spec\.whatwg\.org/commit-snapshots/[0-9a-f]{40}/$

Although not recommended by WHATWG, RIPs must anchor to a particular commit so that future readers can refer to the exact version of the living standard that existed at the time the RIP was finalized. This gives readers sufficient information to maintain compatibility, if they so choose, with the version referenced by the RIP and the current living standard.

Internet Engineering Task Force (IETF)

Links to an IETF Request For Comment (RFC) specification may be included using normal markdown syntax, such as:

[RFC 8446](https://www.rfc-editor.org/rfc/rfc8446)

Which renders as:

RFC 8446

Permitted IETF specification URLs MUST anchor to a specification with an assigned RFC number (meaning cannot reference internet drafts), and so MUST match this regular expression:

^https:\/\/www.rfc-editor.org\/rfc\/.*$

Bitcoin Improvement Proposal

Links to Bitcoin Improvement Proposals may be included using normal markdown syntax, such as:

[BIP 38](https://github.com/bitcoin/bips/blob/3db736243cd01389a4dfd98738204df1856dc5b9/bip-0038.mediawiki)

Which renders to:

BIP 38

Permitted Bitcoin Improvement Proposal URLs must anchor to a specific commit, and so must match this regular expression:

^(https://github.com/bitcoin/bips/blob/[0-9a-f]{40}/bip-[0-9]+\.mediawiki)$

National Vulnerability Database (NVD)

Links to the Common Vulnerabilities and Exposures (CVE) system as published by the National Institute of Standards and Technology (NIST) may be included, provided they are qualified by the date of the most recent change, using the following syntax:

[CVE-2023-29638 (2023-10-17T10:14:15)](https://nvd.nist.gov/vuln/detail/CVE-2023-29638)

Which renders to:

CVE-2023-29638 (2023-10-17T10:14:15)

Ethereum Yellow Paper

Links to the Ethereum Yellow Paper may be included using normal markdown syntax, such as:

[Ethereum Yellow Paper](https://github.com/ethereum/yellowpaper/blob/9c601d6a58c44928d4f2b837c0350cec9d9259ed/paper.pdf)

Which renders to:

Ethereum Yellow Paper

Permitted Yellow Paper URLs must anchor to a specific commit, and so must match this regular expression:

^(https://github\.com/ethereum/yellowpaper/blob/[0-9a-f]{40}/paper\.pdf)$

Digital Object Identifier System

Links qualified with a Digital Object Identifier (DOI) may be included using the following syntax:

This is a sentence with a footnote.[^1]

[^1]:
    ```csl-json
    {
      "type": "article",
      "id": 1,
      "author": [
        {
          "family": "Jameson",
          "given": "Hudson"
        }
      ],
      "DOI": "00.0000/a00000-000-0000-y",
      "title": "An Interesting Article",
      "original-date": {
        "date-parts": [
          [2022, 12, 31]
        ]
      },
      "URL": "https://sly-hub.invalid/00.0000/a00000-000-0000-y",
      "custom": {
        "additional-urls": [
          "https://example.com/an-interesting-article.pdf"
        ]
      }
    }
    ```

Which renders to:

This is a sentence with a footnote.¹

See the Citation Style Language Schema for the supported fields. In addition to passing validation against that schema, references must include a DOI and at least one URL.

The top-level URL field must resolve to a copy of the referenced document which can be viewed at zero cost. Values under additional-urls must also resolve to a copy of the referenced document, but may charge a fee.

Linking to other RIPs

References to other RIPs should follow the format RIP-N where N is the RIP number you are referring to. Each RIP that is referenced in an RIP MUST be accompanied by a relative markdown link the first time it is referenced, and MAY be accompanied by a link on subsequent references. The link MUST always be done via relative paths so that the links work in this GitHub repository, forks of this repository, the main RIPs site, mirrors of the main RIP site, etc. For example, you would link to this RIP as ./rip-1.md.

Auxiliary Files

Images, diagrams and auxiliary files should be included in a subdirectory of the assets folder for that RIP as follows: assets/rip-N (where N is to be replaced with the RIP number). When linking to an image in the RIP, use relative links such as ../assets/rip-1/image.png.

Style Guide

Titles

The title field in the preamble:

• Should not include the word "standard" or any variation thereof; and
• Should not include the RIP's number.

Descriptions

The description field in the preamble:

• Should not include the word "standard" or any variation thereof; and
• Should not include the RIP's number.

RFC 2119 and RFC 8174

RIPs are encouraged to follow RFC 2119 and RFC 8174 for terminology and to insert the following at the beginning of the Specification section:

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.

Copyright

Copyright and related rights waived via CC0.