How changes to Rootstock (RSK) are proposed, reviewed and adopted.
What an RSKIP is
Rootstock is a Bitcoin sidechain that runs EVM-compatible smart contracts. It's merge-mined with Bitcoin, so the same miners secure both chains with the same proof-of-work, and it has been running since 2018. Gas is paid in rBTC, which is pegged 1:1 to BTC through the PowPeg bridge. Because it's EVM-compatible, Solidity and the usual Ethereum tooling work on it.
An RSKIP (Rootstock Improvement Proposal) is a design document that describes a change to Rootstock's protocol, its processes or its environment. It should give a concise technical spec and the reasoning behind the change. The author is responsible for building consensus in the community and recording dissenting opinions.
RSKIPs are the main way to propose new features, collect community input on an issue and document the design decisions behind Rootstock. They live as text files in a versioned repo, so the revision history is the historical record of each proposal. For implementers, they're a simple way to track which proposals a client or library supports.
Lifecycle
RSKIP editors change a proposal's status. Solid arrows are the usual path. Dashed arrows only apply in some cases, such as when a hard or soft fork is needed.
What each status means
- Draft
- Open for consideration.
- Accepted
- Planned for immediate adoption, expected in the next reference client release.
- Active
- Implemented and accepted by the community, where no hard or soft fork is needed.
- Adopted
- Adopted in a previous reference client release.
- Testnet
- Adopted on Testnet. Listed in the RSKIP files as "Adopted (Testnet)".
- Deferred
- Not being considered for immediate adoption. Set when no progress is being made. An editor can move it back to Draft later.
- Rejected
- Turned down. It stays on record so the decision isn't lost.
- Withdrawn
- Withdrawn by its authors. This is final: the number can't be reused, and picking the idea up later means a new proposal.
- Superseded
- Made obsolete by a later RSKIP.
Status definitions come from the RSKIPs README. The diagram is from RSKIP-0, which calls Superseded "Replaced".
Submitting one
- Test the idea in public first. Ask whether it's original and whether it has a chance, before spending time writing it up. Start a thread on the Rootstock Research Forum or open an issue on GitHub, and tag the RSKIP editors.
- Keep it focused. One key proposal per RSKIP works best. A change to a single client doesn't need an RSKIP, but a change that affects several clients or sets a standard for apps does. If in doubt, split it up.
- Find a champion. Every RSKIP needs someone to write it, lead the discussion and build consensus around it.
- Open a draft as a pull request. Use the template, in Markdown. This lets you keep editing while people comment.
- Get a number. If the editors approve, the PR number becomes the RSKIP number. It's labelled Standards Track, Informational or Process and set to Draft, and the editors add its complexity and purpose. They won't refuse without a reason, such as duplicate work, technical problems, weak motivation or backward-compatibility issues.
- Implement it. A Standards Track RSKIP must include an implementation (code, a patch or a link to one) before it can be Accepted or Fork Pending.
- Get accepted. It needs to be a clear, complete description of a net improvement, and the implementation mustn't complicate the protocol unduly. Once the implementation is done and accepted, the status moves to Fork Pending if a fork is needed, or Active if not.
Reviewers are expected to give thoughtful, actionable feedback, not rejections without reasons. Where they can, they should point out a path that could lead to acceptance.
Types
- Standards Track
- Changes that affect most or all Rootstock implementations: network protocol, block or transaction validity rules, or anything that affects how apps on Rootstock work together. Split into categories: Core (consensus), Node (node interfaces such as RPC), Net (p2p networking), UI (user interface), 2nd (second-layer protocols such as payment channels) and DApp (dapp interfaces). Made of a design document, a reference implementation and, if needed, an update to the formal spec.
- Informational
- Describes a design issue or gives general guidance without proposing a feature. It doesn't necessarily reflect community consensus, so people are free to ignore it.
- Process
- Describes or changes a process around Rootstock, such as procedures, decision-making or development tools, rather than the protocol itself. Usually needs community consensus, and people generally can't ignore it.
Labels on this site
Purpose
What the RSKIP improves. It can have more than one. RSKIP files use the short codes; this site shows the full names.
- Sca Scalability
- Usa Usability
- Sec Security
- Fair Fairness
- ST Standard Track
Complexity
How hard it is to implement.
- 1 · Minimal
- 2 · Medium
- 3 · High
What to include
- Preamble
- Header metadata: number, a short title (44 characters max), authors and so on. See header fields below.
- Abstract
- A short description of the technical issue, around 200 words.
- Motivation
- Why the current protocol can't solve the problem. Critical for protocol changes. Proposals without enough motivation may be rejected outright.
- Specification
- The syntax and semantics of any new feature, detailed enough for competing, interoperable implementations.
- Rationale
- Why the design choices were made, what alternatives were considered, related work, evidence of consensus and the main objections raised.
- Backward compatibility
- Required if anything breaks: what, how badly and how the author plans to handle it.
- Implementations
- Must be finished before the RSKIP is final, but not before it's accepted. "Rough consensus and running code" still helps settle API details.
- Test cases
- Required for consensus changes. Optional links for everything else.
- Copyright waiver
- All RSKIPs must be public domain (CC0).
The final implementation must include test code and documentation.
Header fields
Each RSKIP starts with a header between two lines of three hyphens (---), in this order:
| RSKIP | Number, set by the editor |
|---|---|
| Title | RSKIP title |
| Author | Real names, optionally with email or GitHub user. One author per line. |
| Discussions-To | Where it's being discussed, if not privately or on the forum |
| Status | Draft, Active, Accepted, Deferred, Rejected, Withdrawn, Adopted or Superseded |
| Type | Standards Track (with category), Informational or Process |
| Created | Date the number was assigned, as yyyy-mm-dd |
| Replaces | RSKIP number this one makes obsolete |
| Superseded-By | RSKIP number that replaces this one |
| Resolution | Link to where the decision was announced. Standards Track only. |
RSKIPs can also have a Requires header listing the RSKIPs they depend on, and a Post-History header with the dates new versions were posted to the forum.
Files and ownership
Extra files such as diagrams go in a subfolder for that RSKIP and are named RSKIP-XXXX-Y.ext, where XXXX is the RSKIP number and Y is a serial number starting at 1.
Changing owner is fine when the original author no longer has time for it or can't be reached. Disagreeing with the direction isn't a good reason: write a competing RSKIP instead. To take one over, message both the original author and the editors. If the author doesn't reply promptly, the editors decide. Ideally the original author stays on as co-author.
Editors
Editors don't judge proposals. They handle the admin: checking each RSKIP is sound and complete, that the title fits and that the language and formatting are clean. If it isn't ready, they send it back with specific instructions. When it is, they add it to the repo, list it in the README and tell the author the next step.
RSKIP-0 is based on Ethereum's EIP-1 and Bitcoin's BIP-0001, which came from Python's PEP-0001. It's published under CC0.