| CHIP Number | 0001 |
|---|---|
| Title | CHia Improvement Proposal (CHIP) process |
| Description | A living document to outline the CHIP process, from Idea to Final. |
| Author | Daniel Perry |
| Status | Living |
| Category | Process |
| Sub-Category | Procedural |
| Created | 2021-11-24 |
| Updated | 2024-02-29 |
Contents:
- Video Tutorial
- What is a CHIP?
- CHIP categories and sub-categories
- CHIP workflow
- Style Guide
- History
- Copyright
If you are a visual learner, we have created a video tutorial for how to create a CHIP.
A CHIP is a formal design document. It uses a standard format, which will be laid out in this document. CHIPs are the primary mechanism for community members to propose three broad categories of changes to Chia's ecosystem:
- New features or changes that affect one or more of Chia's protocols
- New features or changes that exist outside of Chia's protocols
- General guidelines that do not propose new features or changes
Each of these CHIP categories will be discussed in more detail in the next section.
Most ideas to improve Chia should not be CHIPs. For example, some proposals, including (but not limited to) patches to particular pieces of software and certain additions to existing code, do not require a CHIP. Some good questions to ask while deciding whether to write a CHIP:
- If my proposal is implemented, will it require standardization between multiple projects?
- Will my proposal affect Chia's community or ecosystem in general (as opposed to only affecting one small part of it)?
- Does my proposal focus on a single modification or new idea?
If you answered "no" to either of the first two questions, a CHIP is probably not needed. In this case a simple GitHub pull request with your proposed changes will probably suffice.
If you answered "no" to the third question, you should break your proposal into multiple pieces and consider submitting more than one CHIP. The more focused your CHIP, the greater its chance of success.
CHIPs need to include your rationale for proposing the new feature or guideline. They also need to include concise technical details of the feature or guideline being proposed. The CHIP author is responsible for building a consensus within the community to add the new proposal, as well as for documenting any dissenting opinions.
Each CHIP will be recorded publicly, as text files on a versioned repository. This repository will be the historical record for all CHIPs. It will also give authors, as well as end users, a convenient way to ascertain the current status of any given CHIP.
Standards Track CHIPs propose new features or changes that will affect one or more of Chia's protocols, and all Chia implementations. Any change that affects Chia application standards or conventions, as well as the interoperability of applications using Chia will fall into this category.
Standards Track CHIPs consist of three parts:
- A design document
- A reference implementation
- An update to the existing formal specification
Sub-categories of Standards Track CHIPs include:
- Core -- Changes to the block structure, transaction validity rules (including digital signatures), VDF implementation, plot sizes or structure, etc. Some, but not all, Core CHIPs will require a code fork. Therefore, these are the most difficult CHIPs for which to gain consensus acceptance from the community.
- Network -- Changes to the peer-to-peer network protocol. For example, additional specifications for sending messages or storing data.
- Interface -- Changes to the JSON or RPC specifications, as well as changes to method-level naming standards.
- Chialisp -- Includes any changes to the Chialisp language, and any implementations thereof. Proposals to add new operators, modify libraries, and modify package formats would each fit into this sub-category. Note that new Chialisp puzzles (with the exception of those that propose new primitives) typically fit under the Informational category.
- Primitive -- Proposals of new primitives on Chia's blockchain. Primitives in this context are base-level standards (not derived from existing standards). Typically, primitives provide a technical foundation upon which applications may be developed. Examples in Chia include Singletons, CATs, and Offers.
Process CHIPs propose new features or changes that exist outside of Chia's protocols. These CHIPs typically, but not always, require consensus from the community. A design document is required to be included in the proposal. Sometimes, these CHIPs also require a reference implementation and an update to existing formal specifications.
Sub-categories of Process CHIPs include:
- Procedural -- A modification to the way in which processes are implemented or decisions are made regarding anything Chia-related.
- Tooling -- Changes to any tool outside of Chia's protocols.
- Environment -- Any changes to the environment used in Chia's development or implementation.
- Other -- Changes that don't fit into the other sub-categories.
Informational CHIPs are general guidelines that do not propose new features or changes. These CHIPs do not require consensus from the community, so users are free to ignore them.
Sub-categories of Informational CHIPs include:
- Design -- Changes to any naming conventions or semantics used within Chia's ecosystem. For example, renaming Coloured Coins to CATs.
- Guideline -- Recommendations to Chia's broader community regarding the development process.
- Informative -- Additional information related to Chia's processes or procedures.
- Chialisp Puzzle -- New Chialisp puzzles that are intended to be shared among the community, but which do not propose a new primitive.
- Other -- Changes that don't fit into the other sub-categories.
There are three parties involved with creating and approving each CHIP:
- You -- Also referred to in this document as the CHIP's Author and/or its main Advocate.
- Editor -- Someone who guides the CHIP's Author through the approval process (see CHIP Editor responsibilities and workflow for more info).
- Chia core developers and management -- They will be granted heavy weight in the decision-making process.
Regardless of category and sub-category, each CHIP must follow the same workflow, laid out in this diagram:
The status of each CHIP will therefore fall into one of the following categories:
A formal proposal has yet to be written, so it is not being tracked in the CHIP repository. All CHIPs start as Ideas.
In this stage of development, you should vet your idea in the #chips channel on our Discord. Be sure to gain general agreement from the community that your idea is:
- Original -- It has not been implemented or rejected previously.
- Valuable -- It would help Chia's community and/or ecosystem (and not just the author) if it were implemented.
- Narrow -- It focuses on a single key proposal.
- Feasible -- It is technically sound.
- Compatible -- It doesn't introduce any breaking changes to previous versions.
- Non-complicating -- It doesn't introduce any unnecessary complexities.
- Congruent -- It is harmonious with all of Chia's community guidelines, located in the chia-blockchain repository.
If any of these conditions is not met, your CHIP likely will be rejected. To avoid wasting your (or anyone else's) time, be sure to vet your idea with the community before moving forward with a formal proposal.
Only after your idea has met these conditions within the community, you may proceed to the next phase.
When you are ready for your proposal to be moved into Draft, you should fill out the standard template and submit it as a pull request in the CHIPs GitHub repository. Your CHIP file should be formatted in markdown, and it should be named using this convention: chip-<your name>-<your proposal>.
Be as thorough as possible when filling out the template. Additional details may be added as the review moves forward, but to give your proposal the highest chance of success, it's important to include all relevant information from the beginning. Upon receiving your pull request, a CHIP Editor will make an initial assessment. If you do not hear from an Editor within one week of submitting your pull request, please post a message in the #chips channel of Chia's Discord.
If your proposal contains all of the necessary material, the Editor will assign it a number.
Note that you should not attempt to assign a number to your own CHIP.
At this point, your CHIP is a Draft. You'll need to present it to the community, using the aforementioned Discord for less formal discussion, and your pull request for more formal comments. It is your responsibility to invite editors, developers, and other interested parties to review your draft, make comments, request changes, and give general feedback.
You will also need to gauge interest in your proposal, as well as figure out how broad the impact will be on Chia's ecosystem if it is implemented. In general, the larger your CHIP's impact (in both breadth and depth), the higher the threshold to gaining approval.
Any negative feedback will be taken into account when deciding whether to move your CHIP to the next phase. Additionally, there is no minimum or maximum time for a CHIP to remain in Draft, other than the fact that after six months of inactivity, CHIPs in Draft will automatically be moved to Stagnant.
If you feel that your CHIP is ready to be moved to Review, it is up to you to ask your CHIP's Editor to do so. The Editor's role is to assess your CHIP's status at any given point, but it is not up to them to bring the community to consensus regarding the status of your CHIP.
After a sufficient period in Draft (which can vary significantly between CHIPs), when consensus has been reached and all dissenting opinions have been fully addressed, you may request your CHIP's Editor to move your CHIP into Review.
At this point, you must ask your peers to review your CHIP. Note that it is entirely up to you, as the Chip's author, to solicit these reviews. A lack of reviews will not be taken as a consensus agreement of your proposal. In fact, if your CHIP does not receive any reviews, this is an indication that it will not achieve broad adoption within the community, and therefore is not yet ready to be finalized. If your CHIP receives a sufficient number of negative reviews such that the Editor believes that a broad swath of the community disagrees with it, the Editor will move it back into Draft. Additionally, if you make any significant changes to your CHIP during this period (anything beyond spelling/grammatical corrections or minor clarifications), the Editor will also move it back into Draft.
The minimum time for a CHIP to be in Review is two weeks, but there is no maximum time (other than the fact that after six months of inactivity, CHIPs in Review will automatically become Stagnant). Some CHIPs may require more than two weeks to receive a sufficient number of reviews, while others may simply not have broad community interest. In these cases, your options include pushing for more reviews from the community, asking the Editor to move the CHIP back into Draft, and withdrawing the CHIP altogether.
Bear in mind that the decision of whether a CHIP is ready to be finalized is subjective. If you and your CHIP's Editor disagree, feel free to solicit more feedback from the community. If you and the Editor still cannot come to an agreement, a new Editor could potentially be assigned to your CHIP. However, this depends on the situation and is not guaranteed.
If there is general consensus during this phase, the CHIP's Editor will move the proposal into Last Call.
A limited number of CHIPs may be allowed to pass directly from Idea to Review (Fast Track). This phase will be used for proposals that have already received widespread consensus within the community.
NOTE: As of early 2022, many changes are being implemented quite rapidly. Therefore, this phase is needed to allow for quick iteration and implementation of new ideas. In the future, once Chia and its ecosystem have matured, fast-tracking may be undertaken less often. It could also be completely removed as an option.
Please get permission from a CHIP Editor before attempting to move your CHIP to this phase. After you have obtained this permission, fill out the standard template and submit it as a pull request in the CHIPs GitHub repository. Your CHIP file should be formatted in markdown, and it should be named using this convention: chip-<your name>-<your proposal>.
Upon receiving your pull request, a CHIP Editor will make an initial assessment. If your proposal contains all of the necessary material, the Editor will assign it a number.
At this point, you must ask your peers to review your CHIP. A lack of reviews will not be taken as a consensus agreement of your proposal. If your CHIP is rejected, the Editor will move it into Draft. Because this CHIP has been fast-tracked, you may make some changes to the CHIP without requiring it to be moved into Draft. Be sure to ask your peers to review your CHIP after you have made any significant changes (anything beyond spelling/grammatical corrections or minor clarifications).
The minimum time for a CHIP to be in Review (Fast Track) is one week. If there is general consensus during this phase, the CHIP's Editor will move the proposal into Last Call.
Your CHIP is now ready to be finalized and has entered a waiting period, the deadline of which will be assigned by the CHIP Editor (typically two weeks). During this period, Chia developers and management, as well as community members, may submit their objections to your CHIP being finalized. If any changes are required to be made to the CHIP in this phase, it will be moved back to Review. If the deadline is reached with no serious objections and no modifications being made, then it automatically will be moved to Final.
This CHIP has been finalized and can no longer be modified, other than by adding errata. Note that just because a CHIP has reached Final status, it is not binding. Developers still need to decide whether to implement the CHIP. Additionally, everyone needs to decide for themselves which software to run on their own computers, and ultimately what they consider to be Chia.
If no modifications have been made to a CHIP that is in Draft or Review for six months, then it is automatically moved to Stagnant. The author may petition the Editor to move the CHIP back into its prior state at any point in the future.
You can withdraw your CHIP at any point. Once a CHIP reaches this status, it can no longer be modified. You can propose the same idea once again in a new CHIP, but you may not re-use this one.
If a CHIP with Final status must be replaced, then it will be considered Obsolete. All Obsolete CHIPs must include the Superseded-By field.
A small number of CHIPs will never be finalized because changes will occasionally need to be made. These CHIPs are considered Living, and include CHIP-0001.
All CHIP authors must fill out a template. Please be as thorough as possible; only high-quality submissions will be considered.
If a CHIP requires any additional files, you should add them to the pull request as they become available. They must be included in a subfolder of the assets folder, named for that CHIP.
Occasionally, it may be necessary to for a new owner to take over an in-progress CHIP. Ideally, the original author will agree to be retained as a co-author, but that's not always possible.
If the original owner has fallen out of contact for a significant period of time (the definition of which will be determined by the CHIP's Editor), and you want to take over ownership of said CHIP, please send a message to the current owner, any existing co-authors, and the Editor, asking for a transferal of ownership to yourself. The Editor will make a subjective decision based on your request.
If you simply disagree with a CHIP's goals, you are not allowed to pursue a transferal of ownership to yourself -- hostile CHIP takeovers will not be tolerated. Instead, you should open a competing CHIP and attempt to convince the community that your proposal is better.
The CHIP's Comments-URI field will be the official location for the community to make comments and add reviews for the CHIP. This site is meant for formal and professional reviews and commentary only. The CHIP Editor will periodically review the content of this site and remove any postings not deemed sufficiently professional. Along those lines, everyone who adds a comment or review to this site is required to include their name and the current date. The Editor will contact them with any questions or clarifications.
Additionally, informal reviews and comments are welcome in the #chia_dev channel of Chia's Discord. These comments will receive significantly less moderation. In fact, we encourage you to use this forum to introduce yourself to the community.
| Name | Keybase Handle | Discord Handle | GitHub Profile |
|---|---|---|---|
| Bram Cohen | @bramcohen | bram_cohen | bramcohen |
| Gene Hoffman, Jr. | @hoffmang | hoffmang | hoffmang9 |
| Dan Perry | @dan_perry | danperry | danieljperry |
| Freddie Coleman | @fcoleman | freddiec12_381 | freddiecoleman |
| Will Riches | @riches | wriches | wriches |
| Andreas Greimel | @acevail | acevail | greimela |
When a pull request is created for a new CHIP, an Editor must review the template for:
- Preamble - Have all of the fields been filled out properly? Does it include the email or GitHub address of at least one author?
- Abstract - Does it give a succinct and accurate description of the proposal that could stand on its own?
- Adherence - Does the template follow each of the values listed in the Idea section (Original, Valuable, Narrow, Feasible, Compatible, Non-complicating, Congruent)?
- Completeness - Has the template been completely filled out? Does it meet the concise technical standards required for all CHIPs?
- Licensing - The CHIP must waive all rights via CC0 in order to be considered.
If the template does not meet these standards, the Editor will return it to the author for revision.
However, it is important to keep in mind that the Editor must remain a neutral arbiter. The Editor should refrain from injecting opinions into the discussion and should never reject a CHIP due to a personal disagreement. If an Editor has a conflict of interest (such as working on a competing proposal), they must recuse themselves and a different Editor will take over. Additionally, if there is or has been a personal disagreement between an Editor and an author, a new Editor must take over. The original Editor is allowed to raise issues pertaining to the disagreement with the new Editor, but not with the author.
After the Editor has determined that the CHIP is ready to be moved into draft, they will assign the CHIP with a number and send a message to the author, who will present it to the community for further discussion.
The Editor will also assign the CHIP with a comments URI, which, unless there is a good reason to do otherwise, will take the form "Comments-URI: CHIPs repo, PR #000".
As detailed in the "CHIP categories and sub-categories" section above, the Editor (and not the Author) is responsible for changing the CHIP's status.
When referring to a CHIP by number, it should be written in the hyphenated form CHIP-WXYZ where WXYZ is the CHIP's assigned number.
This document was derived heavily from:
- Ethereum's EIP-1 written by Martin Becze and Hudson Jameson
- Bitcoin's BIP-0001 written by Amir Taaki
- Python's PEP-0001 written by Barry Warsaw, Jeremy Hylton, and David Goodger
The authors of these documents are not responsible for the CHia Improvement Process. Please direct all questions to the CHIP Editors.
Copyright and related rights waived via CC0.