CAIP-1: CAIP Purpose and Guidelines

Author	ligi
Status	Review
Type	Meta
Created	2019-08-31
Updated	2019-08-31

What is an CAIP?
CAIP Rationale
CAIP Formats and Templates
CAIP Header Preamble
Auxiliary Files
Transferring CAIP Ownership
CAIP Editors
CAIP Editorial Process
History
- Bibliography
Copyright

What is an CAIP?

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.

CAIP Rationale

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.

CAIP Formats and Templates

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.

CAIP Header Preamble

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).

`author` header

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 <address@dom.ain>

Random J. User (@username)

if the email address or GitHub username is included, and

Random J. User

if the email address is not given.

`resolution` header

`discussions-to` header

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.

`type` header

The type header specifies the type of CAIP: Standard, Meta, or Informational.

`created` header

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.

`updated` header

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.

`requires` header

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 ([]).

`superseded-by` and `replaces` headers

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.

Auxiliary Files

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”).

Transferring CAIP Ownership

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 :)).

CAIP Editors

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.

CAIP Editorial Process

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.

History

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.

Bibliography

Copyright

Citation

Please cite this document as:

ligi, "CAIP-1: CAIP Purpose and Guidelines," Chain Agnostic Improvement Proposals, no. 1, August 2019. [Online serial]. Available: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-1.md