OIP-1: OIP Purpose and Guidelines

What is an OIP?

OIP stands for an Onomy Improvement Proposal. An OIP is a resolution document providing information to the Onomy community, or describing a new addition or feature to Onomy’s network or ecosystem on the chain-level. The OIP should provide a concise specification of the feature and a rationale for the feature. The OIP author is responsible for building consensus within the community and documenting dissenting opinions. All successful OIPs are governance proposals, but not all governance proposals are OIPs. OIPs are intended to be of particularly significant impact to Onomy.

OIP Rationale

OIPs are intended to be the primary mechanisms for proposing significant features, changes, products, or additions, for collecting community technical input on an issue, and for documenting the design decisions that have gone into Onomy.

For Onomy contributors, OIPs are a convenient way to track the progress of their implementation. Ideally each contributor would list the OIPs that they have implemented. This will give end users a convenient way to know the current status of a given implementation or library. Although, it is recognized that many contributions may only ever be discussed on community socials - and not formally through an OIP.

OIP Workflow

Championing your OIP

Before you begin writing a formal OIP, you should vet your idea and gauge the support it will have amongst the Onomy community. It is thus recommended to minimally engage in a Discord discussion, and ideally open a discussion thread in the forums “Discussion” category.

Once the idea has been vetted, your next responsibility will be to present (by means of an OIP) the idea to the reviewers and all interested parties, invite editors, developers, and the community to give feedback on the aforementioned channels.

Stages of an OIP

Idea - An idea that is pre-draft and in the “Championing” stage, whereby an OIP Author will vet the idea and gauge for community support via Discord discussions and/or a post in the “Discussions” category of the community forum.

Draft - After sufficient vetting of the idea, an OIP author will begin the first formally tracked stage of an OIP in development. A properly formatted OIP must be submitted to the Onomy Improvement Proposals category of the community forum.

Peer Review - An OIP Author marks an OIP as ready for and requesting Peer Review. Discussions may be carried out in the Forum OR through community channels such as Discord.

Governance Proposal - After sufficient discussion, an OIP author may feel they have championed enough support. At this point, an OIP author must submit a governance proposal to the Onomy DAO for on-chain voting. This represents the final stage of an OIP gaining official acceptance.

Active - This stage represents an OIP that has been successfully passed via on-chain governance. An OIP author may provide updates as to the implementation, where necessary.

Rejected - The OIP was not passed via on-chain governance. The OIP author may try again at a later time.

Complete - This stage represents an OIP that has been fully implemented.

Stagnant - Any OIP in Draft or Review that has been inactive for a period of 3 months or greater may be moved to Stagnant. An OIP may be resurrected from this state by the Author providing additional commentary and updates to move along the OIP process. If not resurrected, a proposal may stay forever in this status.

Withdrawn - The OIP Author(s) have withdrawn the proposed OIP. If the idea is pursued at later date it is considered a new proposal.

Living - A special status for OIPs that are designed to be continually updated and not reach a state of finality.

What belongs in a successful OIP?

Each OIP should have the following parts:

  • Abstract - Abstract is a multi-sentence (short paragraph) technical summary. This should be a very terse and human-readable version of the specification section. Someone should be able to read only the abstract to get the gist of what this specification does.
  • Motivation (optional) - A motivation section clearly explains what prompted the author to submit the OIP.
  • Specification - The specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for contributors to use or ideate from - enabling multiple interfaces developed and sustained by independent contributors to be generated, for example.
  • 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.
  • Backwards Compatibility (optional) - All OIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their consequences. The OIP must explain how the author proposes to deal with these incompatibilities. This section may be omitted if the proposal does not introduce any backwards incompatibilities, but this section must be included if backward incompatibilities exist.
  • Reference Implementation (optional) - An optional section that contains a reference/example implementation that people can use to assist in understanding or implementing this specification. This section may be omitted for all OIPs.
  • Security Considerations (optional) - All OIPs 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.
  • Author name and contact information
  • Status of OIP, displayed as “STATUS: NAME OF STAGE”


PLEASE NOTE: OIPs are intended for thoughtful discussion. As such, new members must earn Trust Level 1 before posting or replying in the OIP Category. Trust Level 1 is earned by making at least 1 Topic Post in another category, such as the Discussion category, and spending at least 10 minutes reading 5 other posts.

1 Like