| caip | title | status | type | author | created | updated |
|---|---|---|---|---|---|---|
1 |
CAIP Purpose and Guidelines |
Review |
Meta |
ligi <[email protected]> |
2019-08-31 |
2019-08-31 |
CAIP stands for Chain Agnostic Improvement Proposal. A CAIP is a design document providing information to the community or describing a standard to be used across multiple chains. To be more precise, a CAIP may describe capabilities applicable to any sequential orderings of cryptographically hashed commitments, including non-blockchain systems that can interoperate with blockchains productively, such as DAGs, sharded systems, git systems using keyserver-based PKI, etc. The CAIP should provide a concise technical specification of the feature and a rationale for it. The CAIP author is responsible for building consensus within the community and documenting dissenting opinions.
Currently it is often the case that a standard defined in one chain is also used in another chain, e.g. the usage of BIP39 in Ethereum applications. Also, there is no real place to propose a standard that can be used for multiple chains (like mnemonics) currently. CAIPs are intended to fill this gap and be a place where such standards can live.
CAIPs should be written in markdown format.
Image files should be included in a subdirectory of the assets folder for that CAIP as follows: assets/caip-N (where N is to be replaced with the CAIP number). When linking to an image in the CAIP, use relative links such as ../assets/caip-1/image.png.
Each CAIP must begin with an RFC 822 style header preamble, preceded and followed by three hyphens (---). This header is also termed "front matter" by Jekyll. The headers must appear in the following order. Headers marked with "*" are optional and are described below. All other headers are required.
caip: (this is determined by the CAIP editor)
title:
author: <a list of the author's or authors' name(s) and/or username(s), or name(s) and email(s). Details are below.>
* discussions-to: <a URL pointing to the official discussion thread>
status: <Draft | Rejected | Review | Last Call | Withdrawn | Final | Superseded>
* review-period-end:
type: <Standard | Informational | Meta>
* category: <Core | Networking | Interface | ERC>
created:
* updated:
* requires: <CAIP number(s); if multiple, use [1,2] format to create a YAML array>
* replaces: <CAIP number(s); if multiple, use [1,2] format to create a YAML array>
* superseded-by: <CAIP number(s) | URL of non-CAIP standard >
Headers that permit lists must separate elements with commas.
Headers requiring dates will always do so in the format of ISO 8601 (yyyy-mm-dd).
The author header optionally lists the names, email addresses or usernames of the authors/owners of the CAIP. Those who prefer anonymity may use a username only, or a first name and a username. The format of the author header value must be:
Random J. User <[email protected]>
or
Random J. User (@username)
if the email address or GitHub username is included, and
Random J. User
if the email address is not given.
While a CAIP is a draft, a discussions-to header will indicate the mailing list or URL where the CAIP is being discussed.
As a single exception, discussions-to cannot point to GitHub pull requests.
The type header specifies the type of CAIP: Standard, Meta, or Informational.
The created header records the date that the CAIP was assigned a number. Both headers should be in yyyy-mm-dd format, e.g. 2001-08-14.
The updated header records the date(s) when the CAIP was updated with "substantial" changes. This header is only valid for CAIPs of Draft and Active status.
CAIPs may have a requires header, indicating the CAIP(s) on which this CAIP depends. Note that if the CAIP requires multiple others, the value should be an array of integers (no " needed) and/or URLs (wrapped in "s) within square brackets ([]).
CAIPs may also have a superseded-by header indicating that a CAIP has been rendered obsolete by a later document; the value is the number of the CAIP that replaces the current document. The newer CAIP must have a replaces header containing the number of the CAIP that it rendered obsolete.
CAIPs may include auxiliary files such as diagrams. Such files must be named CAIP-XXXX-Y.ext, where “XXXX” is the CAIP number, “Y” is a serial number (starting at 1), and “ext” is replaced by the actual file extension (e.g. “png”).
It occasionally becomes necessary to transfer ownership of CAIPs to a new champion. In general, we'd like to retain the original author as a co-author of the transferred CAIP, but that's really up to the original author. A good reason to transfer ownership is because the original author no longer has the time or interest in updating it or following through with the CAIP process, or has fallen off the face of the 'net (i.e. is unreachable or isn't responding to email). A bad reason to transfer ownership is because you don't agree with the direction of the CAIP. We try to build consensus around a CAIP, but if that's not possible, you can always submit a competing CAIP.
If you are interested in assuming ownership of a CAIP, send a message asking to take over, addressed to both the original author and the CAIP editor. If the original author doesn't respond to email in a timely manner, the CAIP editor will make a unilateral decision (it's not like such decisions can't be reversed :)).
Editorial duties to update and maintain the CAIPs is the primary duty of the chair of the editorial working group at CASA. For current working group chair, see CASA's administrative homepage.
For each new CAIP that comes in, an editor does the following:
- Read the CAIP 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 CAIP for language (spelling, grammar, sentence structure, etc.), markup (Github flavored Markdown), code style.
If the CAIP isn't ready, the editor will send it back to the author for revision, with specific instructions.
Once the CAIP is ready for the repository, the CAIP editor will:
-
Assign a CAIP number (generally the PR number or, if preferred by the author, the Issue # if there was discussion in the Issues section of this repository about this CAIP)
-
Merge the corresponding pull request
-
Send a message back to the CAIP author with the next step.
The editors don't pass judgment on CAIPs. We merely do the administrative & editorial part.
This document was derived heavily from Bitcoin's BIP-0001 written by Amir Taaki, which in turn was derived from Python's PEP-0001. In many places text was simply copied and modified. Although the PEP-0001 text was written by Barry Warsaw, Jeremy Hylton, and David Goodger, they are not responsible for its use in Chain Agnostic Improvement Proposals, and should not be bothered with technical questions specific to CAIPs. Please direct all comments to the CAIP editors.
Copyright and related rights waived via CC0.