Capability Improvement Proposals

Capability Improvement Proposals

The Signum community has established CIPs, short for “Capability Improvement Proposal,” as the process for advancing the development of Signum. CIPs describe standards for the Signum platform, including core protocol specifications, client APIs, and contract standards.

A Capability Improvement Proposal (CIP) is a design document that provides information to the Signum community, describes new features, processes, or aspects of its environment.  CIPs should provide concise technical specifications and rationale.

CIPs are the primary mechanisms for proposing new features, collecting community input, and documenting the design decisions. The CIP author is responsible for building consensus within the community and documenting dissenting opinions.

CIPs are maintained as text files in a versioned repository.  Their revision history is the historical record of the feature proposal.

The CIP repository is located at https://github.com/burst-apps-team/CIPs.

CIP Workflow Start

The CIP process begins with a new idea for Signum.  Many ideas have already been proposed and rejected for various reasons.  The first step should be to search past discussions to see if an idea has been considered before, and if so, what issues arose in its progression.  Vetting an idea publicly before going as far as writing a CIP is meant to save both the potential author and the wider community time. Asking the Signum community first if an idea is original helps prevent too much time being spent on something that is guaranteed to be rejected based on prior discussions.  It also helps to make sure the idea applies to the entire community and not just the author. Just because an idea sounds good to the author does not mean it will work for most people in most areas where Signum is used. After investigating past work, the best way to proceed is by posting the new idea to the Signum Discord forum.

Once community interest has been ascertained, a draft CIP should be composed.  The initial draft should be properly formatted, of high quality, and address any concerns raised about the proposal.  The author will be responsible for shepherding the discussions in the appropriate forums and building community consensus around the idea.

Small enhancements or patches to a particular piece of software often do not require standardization between multiple projects; these do not need a CIP and should be injected into the relevant project-specific development workflow with a patch submission to the applicable issue tracker.

Following discussion, the proposal should be submitted to the CIP repository.  The CIP should be named with an alias such as “cip-johndoe-signaproject” until an editor has assigned it a CIP number (authors MUST NOT self-assign CIP numbers).

CIP authors are responsible for collecting community feedback on both the initial idea and the CIP before submitting it for review.  Whenever possible, long, open-ended discussions on public mailing lists should be avoided.  Strategies to keep the discussions efficient include: setting up a separate mailing list for the topic, having the CIP author accept private comments in the early design phases, etc. CIP authors should use their discretion here.

It is highly recommended that a single CIP contain a single key proposal or idea. The more focused the CIP, the more successful it tends to be.  If in doubt, split a CIP into several that are more focused.

When the CIP draft is complete, the CIP editor will assign the CIP a number, label it according to type, and move it to the CIPs repository.

The CIP editor reviews incoming CIPs for their formal completeness and will not unreasonably reject a CIP.

Reasons for rejecting CIPs include duplication of effort, disregard for formatting rules, being unfocused or overly broad, being technically unsound, not providing proper motivation, not addressing backward compatibility, or not keeping with the Signum philosophy.

For a CIP to be accepted, it must meet certain minimum criteria. It must be a clear and complete description of the proposed enhancement. The enhancement must represent a net improvement. The proposed implementation, if applicable, must be solid and must not complicate the protocol unduly.

The CIP author may update the draft as necessary. Updates to drafts should also be submitted by the author.

Transferring CIP Ownership

It occasionally becomes necessary to transfer ownership of CIPs to a new author.  At the discretion of the original author, the original author should remain as a co-author of a transferred CIP.  A good reason to transfer ownership is that the original author no longer has the time or interest to update it or follow through with the CIP process or is no longer reachable.  It is not acceptable to transfer ownership solely because of disagreement.  Try to build consensus around a CIP.  If this is not possible, then submitting a competing CIP is appropriate.

If you are interested in assuming ownership of a CIP, contact the original author and the CIP editor.  If the original author does not respond in a timely manner, the CIP editor can make a unilateral decision.

CIP Editors

The current CIP editors are jjos, ohagar, and blankey1337.  They can be contacted on Discord.

CIP Editor Responsibilities & Workflow

The CIP editor is present in the Signum Discord channel.

For each new CIP, an editor verifies the following:

  • Ideas are sound and complete. The ideas must make technical sense, even if they do not seem likely to be accepted.
  • The title accurately describes the content.
  • A link to the CIP draft has been placed in the Signum Discord channel for discussion.
  • Motivation and backward compatibility (when applicable) has been addressed.
  • The defined layer header is correctly assigned for the given specification.
  • Licensing terms are acceptable.

If a CIP is deficient in any of these areas, the editor will send it back to the author for revision with specific instructions.

Once a CIP is ready, it is submitted to the CIPs repository to get further feedback.

The CIP editor will:

  • Assign a CIP number.
  • Place the CIP in the CIP repository.

The CIP editors are intended to fulfill administrative and editorial responsibilities. The CIP editors monitor CIP changes and update CIP headers as appropriate.

CIP Format and Structure

CIPs must be written in markdown format.

Each CIP should have the following parts:

  • Preamble – Headers containing metadata about the CIP (see below).
  • Abstract – A short (~200 word) description of the technical issue being addressed.
  • Copyright – As the CIPs are part of the Signum project, the license is GNU FDL.
  • 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 different Signum platforms.
  • Motivation – The motivation is critical for CIPs that want to change the Signum protocol. It should clearly explain why the existing protocol is inadequate to address the problem that the CIP solves.
  • 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. The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussions.
  • Backward compatibility – All CIPs that introduce backward incompatibilities must include a section describing these incompatibilities and their severity. The CIP must explain how the author proposes to deal with these incompatibilities.
  • Reference implementation – The reference implementation must be completed before any CIP is given the status of “Final”, but it need not be completed before the CIP is accepted. It is better to finish the specification and rationale first and reach a consensus before writing code. The final implementation must include test code and documentation appropriate for the Signum protocol.

CIP Header Preamble

Each CIP must begin with an RFC 822 style header preamble. The headers must appear in the following order. Headers marked with “*” are optional and are described below. All other headers are required. 

  CIP: <CIP number, or "?" before being assigned>* Layer: <Consensus (soft fork) | Consensus (hard fork) | Peer Services | API/RPC | Applications>  Title: <CIP title; maximum 44 characters>  Author: <list of author names or known community handles>* Discussions-To: <email address>* Comments-Summary: <summary tone>  Comments-URI: <links to wiki page for comments>  Status: <Draft | Active | Proposed | Deferred | Rejected |           Withdrawn | Final | Replaced | Obsolete>  Type: <Standards Track | Informational | Process>  Created: <date created on, in ISO 8601 (yyyy-mm-dd) format>  License: <abbreviation for approved license(s)>* License-Code: <abbreviation for code under different approved license(s)>* Post-History: <dates of postings to bitcoin mailing list, or link to thread in mailing list archive>* Requires: <CIP number(s)>* Replaces: <CIP number>* Superseded-By: <CIP number>

The layer header (only for Standards Track CIPs) documents which layer of Signum the CIP applies to.

The author header lists the names and email addresses of all the authors/owners of the CIP. The format of the author header value must be

Random J. User <[email protected]>

If there are multiple authors, each should be on a separate line following RFC 2822 continuation line conventions.

While a CIP is in private discussions (usually during the initial Draft phase), a discussions-to header will indicate the mailing list or URL where the CIP is being discussed. No discussions-to header is necessary if the CIP is being discussed privately with the author or on the bitcoin email mailing lists.

The type header specifies the type of CIP: Standards Track, Informational, or Process.

The created header records the date that the CIP was assigned a number, while post-history is used to record when new versions of the CIP are posted to bitcoin mailing lists. Dates should be in yyyy-mm-dd  format, e.g., 2001-08-14. Post-history is permitted to be a link to a specific thread in a mailing list archive. 

CIPs may have a requires header, indicating the CIP numbers that this CIP depends on.

CIPs may also have a superseded-by header indicating that a CIP has been rendered obsolete by a later document; the value is the number of the CIP that replaces the current document. The newer CIP must have a replaces header containing the number of the CIP that it rendered obsolete.

Auxiliary Files

CIPs may include auxiliary files such as diagrams. Auxiliary files should be included in a subdirectory for that CIP.

CIP Types

There are three kinds of CIP:

  • A Standards Track CIP describes any change that affects most or all Signum implementations, such as a change to the network protocol, a change in block or transaction validity rules, or any change or addition that affects the interoperability of applications using Signum. Standards Track CIPs consist of two parts, a design document, and a reference implementation.
  • An Informational CIP describes a Signum design issue or provides general guidelines or information to the Signum community.  It does not propose a new feature. Informational CIPs do not necessarily represent a Signum community consensus or recommendation, so users and implementers are free to ignore Informational CIPs or follow their advice.
  • A Process CIP describes a process surrounding Signum or proposes a change to (or an event in) a process. Process CIPs are like Standards Track CIPs but apply to areas other than the Signum protocol itself. They may propose an implementation, but not to Signum codebase; they often require community consensus; unlike Informational CIPs, they are more than recommendations.  Users are typically not free to ignore them. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in Signum development. Any meta-CIP is also considered a Process CIP.

CIP Status Field

The typical paths of the status of CIPs are in the CIP Workflow diagram.

 

 

CIP Workflow

Champions of a CIP may decide on their own to change the status between Draft, Deferred, or Withdrawn. The CIP editor may also change the status to Deferred when no progress is being made on the CIP.

A CIP may only change status from Draft (or Rejected) to Proposed when the author deems it is complete, has a working implementation (where applicable), and has community plans to progress it to the Final status.

CIPs should be changed from Draft or Proposed status to Rejected status, upon request by any person, if they have not made progress in three years. Such a CIP may be changed to Draft status if the champion provides revisions that meaningfully address public criticism of the proposal, or to Proposed status if it meets the criteria required as described in the previous paragraph.

A proposed CIP may progress to Final only when specific criteria reflecting real-world adoption has occurred. This is different for each CIP depending on the nature of its proposed changes, which will be expanded on below. Evaluation of this status change should be objectively verifiable and/or be discussed on the development
channel(s).

When a Final CIP is no longer relevant, its status may be changed to Replaced or Obsolete (which is equivalent to Replaced). This change must also be objectively verifiable and/or discussed.

A process CIP may change status from Draft to Active when it achieves rough consensus on the mailing list. Such a proposal is said to have a rough consensus if it has been open to discussion on the development channel(s)for at least one month, and no person maintains any unaddressed substantiated objections to it.  Addressed or obstructive objections may be ignored/overruled by general agreement that they have been sufficiently addressed, but clear reasoning must be given in such circumstances.

1 + 7 =

Share This