Polygon Improvement Proposals (PIPs) describe standards for the Polygon Ecosystem, including core protocol specifications such as Heimdall and Bor, client APIs, and contract standards, etc.
What is a PIP?
PIP stands for Polygon Improvement Proposal. A PIP is a design document providing information to the Polygon community, or describing a new feature for Polygon or its processes or environment. The PIP should provide a concise technical specification of the feature and a rationale for the feature. The PIP author is responsible for building consensus within the community and documenting dissenting opinions.
PIP Rationale
We intend PIPs to be the primary mechanisms for proposing new features, for collecting community technical input on an issue, and for documenting the design decisions that have gone into Polygon Ecosystem. Because the PIPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal.
For Polygon Ecosystem implementers, PIPs are a convenient way to track the progress of their implementation. Ideally, each implementation maintainer would list the PIPs that they have implemented. This will give end users a convenient way to know the current status of a given implementation or library.
PIP Types
The following are mostly the types of PIPs that will be categorised in:
Core : Improvements on the Core Components such as Heimdall and Bor as well as changes that are not necessarily consensus critical but may be relevant to core components
Contracts : Improvements on the Core Contracts that are deployed on Ethereum.
Interface - includes improvements around client API/RPC specifications and standards, and also certain language-level standards like method names and contract ABIs.
Informational PIP : An Informational PIP describes a Polygon design issue, or provides general guidelines or information to the Polygon community, but does not propose a new feature. Informational PIPs do not necessarily represent Polygon community consensus or a recommendation, so users and implementers are free to ignore Informational PIPs or follow their advice.
PIP Flow
The Parties involved in a PIP are the Author, Community, Matic Validator Advisory Board and Polygon Core Team.
In addition to making sure your idea is original, it will be your role as the author to make your idea clear to reviewers and interested parties, as well as inviting editors, developers and community to give feedback on the aforementioned channels.
A Polygon Improvement proposal needs to be first created on the Matic Forum (https://forum.polygon.technology).
Once a PIP has been drafted in the Forum. The same will be announced by the Polygon Team in the Discord Announcements channels to let the community know about the latest PIP.
This will then allow the community members and the Matic Validator Advisory board to have deeper discussions about the PIP and engage on the Forum. This will involve a lot of back and forth between the Community, MVAB and the Author too.
Once, the community feels that an idea has been refined and finalized, this will then be translated to an issue on Github on their respective repositories and taken forward by the Polygon Core team based on the type of PIP. That translation of a PIP to Github will be undertaken by the Polygon Team.
The Polygon Core Team will then prioritize and implement the PIP. This will then be tested on the Mumbai Testnet and only then be rolled out as an upgrade on the Mainnet.
PIP Body
Whenever an Author is submitting a PIP, they need to ensure that they submit it with all the details and provide as much as details as possible so that everyone and anyone reading the draft should be able to understand it.
This is highly important because otherwise, there will be too many iterations on only correcting the body / formatting of the PIP and that would be a sincere waste of time for everyone.
A really good PIP should contain the following in their Draft:
Title : The Title of your PIP needs to crisp and clear. It should explain the purpose of your PIP
Status : There are going to 3 statuses for each PIP
-
Draft : When a new PIP is submitted. The status will remain Draft during the discussion stages as well. Authors need to ensure that they add this prefix to their Title. During this stage Amendments to the Draft will be subject to discussions.
-
Last Call : This is the final review window for a PIP before moving to FINAL. A PIP author will assign Last Call status and set a review end date. This will only happen when there is a consensus on the PIP that it has reached a finalized state. Meaning the idea is now refined.
-
Final: This state represents the Final standard. No more amendments will be made to the PIP now. The Final state will be called on by the Author, MVAB and the Polygon team.
Abstract: A short (~200 word) description of the technical issue being addressed.
Motivation (*optional): Motivation is critical for PIPs that want to change the Polygon protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the PIP solves. PIP submissions without sufficient motivation may be rejected outright.
Specification: The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current Polygon platforms
Rationale: The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The rationale may also provide evidence of consensus within the community, and should discuss important objections or concerns raised during discussion.
Backwards Compatibility: All PIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The PIP must explain how the author proposes to deal with these incompatibilities. PIP submissions without a sufficient backwards compatibility treatise may be rejected outright.
Test Cases: Test cases for implementation are mandatory for PIPs that are affecting consensus changes. Other PIPs can choose to include links to test cases if applicable.
Reference Implementation: An optional section that contains a reference/example implementation that people can use to assist in understanding or implementing this specification.
Security Considerations: All PIPs must contain a section that discusses the security implications/considerations relevant to the proposed change. Include information that might be important for security discussions, surfaces risks and can be used throughout the life cycle of the proposal. E.g. include security-relevant design decisions, concerns, important discussions, implementation-specific guidance and pitfalls, an outline of threats and risks and how they are being addressed. PIP submissions missing the “Security Considerations” section will be rejected. A PIP cannot proceed to status “Final” without a Security Considerations discussion deemed sufficient by the reviewers.
Copyright Waiver: All PIPs must be in the public domain.
PIP Admins
The Current PIP Admins are Jaynti Kanani, Anurag Arjun and Delroy Bosco
PIP Editor Responsibilities
For each new PIP that comes in, an editor does the following:
- Read the PIP to check if it is ready: sound and complete. The ideas must make technical sense, even if they don’t seem likely to get to final status.
- The title should accurately describe the content.
- Check the PIP for language (spelling, grammar, sentence structure, etc.),
If the PIP isn’t ready, the editor will send it back to the author for revision, with specific instructions.