Diem Improvement Proposals (DIPs) offer the Diem developer community a way to participate in advancing the features and functioning of the Diem payment network (DPN), either by proposing a change or engaging in discussion about a proposal.

Soon after a full Diem specification is posted to diem.com as the root standard DIP, proposals that address the core Diem Blockchain protocol, the Move development platform, smart contracts and systems for smart-contract verification, operating standards, APIs, and off-chain mechanisms can be addressed with a DIP. The DIP itself is the design document that describes the proposed change or new feature. As a text file maintained in a versioned repository, it serves as the historical record of decisions made during the approval process.

The DIP program operates under the governance of the Diem Association, with technical decisions supervised by the Association’s Technical Steering Committee (TSC). Day-to-day technical decisions are made using a framework inspired by standards bodies (such as the W3C and IETF) and open source projects (such as Python, the Linux Foundation, and Apache) to coordinate the work of open source contributors.

This process is based on the family of approaches derived from Python’s PEP process. It is supported by a team of Maintainers who are assigned individually to serve as the DIP Manager on an active DIP and who work to build consensus among Diem community members about technical decisions. Additionally, DIP matters are routinely discussed by the Lead Maintainer with the TSC.

Ask the community for support

DIP types#

There are three types of DIP:

  • Standard DIPs describe any change or addition that affects DPN, such as a change to the Diem Blockchain protocol, a change to transaction processing, proposed application standards/conventions, or any change or addition that affects the interoperability of applications using DPN.

  • Process DIPs describe the governance procedures and tools of the Diem project, such as the DIP procedure itself, GitHub plug-ins, and other development tools and guidelines.

  • Informational DIPs describe a Diem project design issue, or provide general guidelines or information to the Diem community, but do not propose a material change or addition to DPN. Informational DIPs do not necessarily represent Diem community consensus or a recommendation, so users and implementers are free to ignore Informational DIPs or follow their advice.

Ask the community for support

The DIP process#

01IDEA
02DRAFT
03LAST CALL
04ACCEPTED
05FINAL

Parties involved in the process are the DIP author(s) and a designated DIP Manager. The Lead Maintainer shall act as the primary DIP Manager and can appoint at any time a delegate Manager to specific DIPs.

The formal DIP process will typically (and advisably) begin after the champion of the proposal has already discussed and socialized it with the Diem community (see below for what goes into a DIP). It is comprised of the following steps:

  • Idea – Authors will socialize their idea with the developer community and Maintainers, possibly by writing a GitHub Issue and getting feedback. If possible (and relevant), authors should include in discussions an implementation to support their proposal.

    Once the discussion reaches a mature point, the formal DIP process starts with a pull-request to the diem/dip folder. The status field of the document should be “Draft” at this point. A DIP Manager will review/comment/approve/deny the pull-request.

    • Draft – If agreeable, DIP Manager will assign the DIP a number (generally the issue or PR number related to the DIP, and ask to rename or move to a folder/file with that number) and approve the pull request. The DIP Manager will not unreasonably deny a DIP.
    • Draft – Reasons for denying Draft status include misalignment with Diem mission or Association policy, being too unfocused, too broad, duplication of effort, being technically unjustified, not providing proper motivation, or not addressing backwards compatibility. The Authors can work to refine and resubmit their DIP Idea for review again.

  • Draft – After the draft is merged, additional changes may be submitted via pull requests. When a DIP appears to be completed and stable, Authors may ask to change the status to Last Call.

    • Last Call – If agreeable, the DIP Manager will approve the Last Call status and set a reasonable amount of time (usually 2-4 weeks) for a final review. Additional time can be granted by the DIP Manager if requested.
    • Last Call – A request for Last Call will be denied if material changes are still needed for the draft. DIPs should only be promoted to Last Call once.

  • Last Call - This DIP will be listed prominently on the Diem public Discourse under the DIP category. The final status change by the DIP Manager will be either Accepted or Rejected.

    • Accepted – A successful Last Call without any material changes or unaddressed technical complaints will become Accepted. This status signals that material changes are unlikely and Diem Maintainers should support driving this DIP for inclusion.
    • Rejected – The Maintainers can decide to mark this DIP as Rejected at their discretion, e.g., a major, but uncorrectable, flaw was found in the DIP.

  • Accepted - A DIP in the Accepted state means the TSC has determined it is ready for active implementation

    • Final – DIP is deployed to mainnet. When the implementation is complete and deployed to mainnet the status will be changed to “Final”.
    • Draft – If new information becomes available an Accepted DIP can be moved back into Draft status for necessary changes.
    • Deprecated – The DIP Manager or Maintainers may mark a DIP Deprecated if it is superseded by a later proposal or otherwise becomes irrelevant.

  • Final – The Final state of a DIP means the necessary implementations of the DIP are complete and deployed to the codebase. This DIP represents the current state-of-the-art. A Final DIP should only be updated to correct errata.

A DIP may refer to related/dependent DIPs. Every DIP will be assigned a status tag as it evolves. At every stage there can be multiple revisions/reviews until the next stage.

Ask the community for support

What goes into a DIP#

The following is a summary of what each DIP should include. For an example DIP, see DIP 0. There is also a template to help you get started.

  • Preamble - RFC 822 style headers containing metadata about the DIP, including the DIP number, a short descriptive title (limited to a maximum of 44 characters), and the author details.

  • Simple Summary - Provide a simplified and layman-accessible explanation of the DIP.

  • Abstract - a short (~200 word) description of the technical issue being addressed.

  • Motivation (*optional) - The motivation is critical for DIPs that want to change the Diem protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the DIP solves. DIP 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 of the Diem protocol or any other Diem platforms that may emerge.

  • 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 DIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The DIP must explain how the author proposes to deal with these incompatibilities. DIP submissions without a sufficient backwards compatibility treatise may be rejected outright.

  • Test Cases - Test cases for an implementation are mandatory for DIPs that are affecting consensus changes. Other DIPs can choose to include links to test cases if applicable.

  • Implementations - The implementations must be completed before any DIP is given status “Final,” but it need not be completed before the DIP is merged as draft. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of “rough consensus and running code” is still useful when it comes to resolving many discussions of API details.

  • Copyright Waiver – All DIPs must be in the public domain. Please use the copyright notice featured at the bottom of this page.

Ask the community for support
Copyright Notice: This documentation is made available under the Creative Commons Attribution 4.0 International (CC BY 4.0) license (available at https://creativecommons.org/licenses/by/4.0/).