Previously, the specifics of blockchain ecosystems and namespaces were defined in single stand-alone CAIPs alongside cross-chain CAIPs. Now, as the system has matured and expanded, it has become clear that namespaces are more complex and multi-dimensional than can be efficiently governed over time in the current CAIP single-document structure; instead, a Namespace Reference is proposed that splits out the application of each cross-namespace CAIP to a given namespace as a distinct document with its own ratification/supersession lifecycle. This way, long-term specifications for low-level primitives like Chain IDs and addresses can be defined once and not be superseded by the addition or modification of higher-level specifications for RPC interfaces or multiple asset types.
In practical terms, that means each bounded ecosystem's namespace is defined
by a folder containing a distinct document for each CAIP applied to that
namespace. How namespaces get bounded is irreducibly subjective, but overlapping or contentious boundaries are to be avoided where possible, and overlaps or redundancies should be justified in technological and interoperability terms. At a high level, the important facts about a namespace, its
governance, and its nomenclature can be defined/introduced in a README.md
file, and each CAIP can be defined in a caip{X}.md file, where X is the number
of the ratified CAIP.
Like CAIPs, each CAIP-reference and namespace-reference is a design document providing information to the community and/or describing an addressing scheme with the explicit aim of further cross-chain (and more importantly, cross-namespace) engineering. The references should provide a concise technical specification of each feature or variant, as well as a rationale requiring little namespace-specific context. The namespace reference should include canonical (and ideally long-lived) links to authoritative documents, both when relied upon by the specified behavior AND when namespace-specific context is required to understand the inputs to or assumptions of the behavior.
The reference author is responsible for building consensus within the community and documenting dissenting opinions or rejected alternatives.
Cross-system engineering is difficult and often requires one to know both sides of a cross-namespace/cross-ecosystem interaction deeply to avoid serious security, UX, and design problems. The primary function of defining a namespace reference is to map the cross-namespace CAIPs against the specifics of a given ecosystem and namespace, ideally written for a reader with very little context in that ecosystem and its technical decisions to date.
Namespace references should be written in markdown format.
Image files should be included in the same namespace directory to allow for simple relative references. Such files must be named readme-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”).
Templates for both the namespace reference and for each namespace-caip reference are included in the namespaces repo folder for easy cloning.
Each reference document must begin with an RFC
822 style header preamble, preceded and
followed by three hyphens (---). This header is also termed "front matter" by
Jekyll.
Please Note:
key: ["str1", "str2"],
NOT key: Str1, Str2, even though single strings can be encoded in the form
key: Str1namespace-identifier: <{unique lowercase alphanumeric string}[-caip{X}],
where the optional suffix replaces X with the number of the applied CAIP unless
the reference is a base namespace reference>title: {string1}[ - {string2}]author: a string or array of strings, each consisting of the author's public
name and github username or emailresolution?: a string or array of strings, each consisting of an archival urldiscussions-to?: a string or array of string, each consisting of a urlstatus: { Draft / Last Call / Accepted / Active / Abandoned / Rejected / Superseded }review-period-end?: date review period endstype: { Standards Track / Informational / Meta }category?: { Core / Networking / Interface / ERC } if type == Standards Trackcreated: date created onupdated?: comma separated list of datesrequires?: CAIP number(s), i.e. CAIP-104replaces?: { CAIP number(s) / namespace-specific document reference(s), i.e. EIP-155 }superseded-by?: { namespace reference(s) / URL of non-namespace standard }title header{string1} should be the natural-language spelling/name of the namespace, e.g.
"EIP-155" for eip155; if this name is technical or otherwise counterintuitive,
an optional clarification may be affixed, e.g. ", aka EVM Chains." If the
reference in question is a per-CAIP reference, a common name for the specified
referent can be added for further clarity, i.e. " - Assets" (for CAIP-19) or " -
Addresses" (for CAIP-10), as these markdown files will double as page-titles if
rendered in a browser.
author headerThe 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>
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.
resolution header (optional)If ratification of this document was recorded at a permanent URL (e.g. the recorded minutes of a CASA meeting or mailing list), that URL can be placed here for additional context.
discussions-to header (optional)While an CAIP is a draft, a discussions-to header will indicate the mailing
list or URL where the CAIP is being discussed.
type headerThe type header specifies the type of CAIP: Standards Track, Meta, or
Informational.
created headerThe 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 (optional)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 (optional)Namespace-CAIPs may have a requires header, indicating the CAIP number(s) that
this reference depends on.
superseded-by and replaces headers (optional)Namespace-CAIPs may also have a superseded-by header indicating that an CAIP
has been rendered obsolete by a later document; the value is the title that
replaces the current document, i.e., if "eip155-caip10" gets superseded, it
should rename in the directory eip155 directory but contain a link to the
superseding specification(s), like [caip10v2](caip10v2.md). The newer
Namespace-CAIP must have a replaces header containing the number of the
Namespace-CAIP that it rendered obsolete.
Namespace-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 references to a new champion. In general, we'd like to retain the original author as a co-author of the transferred reference document, 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 CASA 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 document. We try to build consensus around each document, but if that's not possible, you can always submit an alternate/competing document through the same PR/consensus process.
If you are interested in assuming ownership of an document, send a message asking to take over, addressed to both the original author and the CAIP editor (this can be done in a new github issue or email). If the original author doesn't respond in a timely manner, CASA editor(s) may make a unilateral but reversible decision in the interest of keeping things moving.
This document was derived heavily from CAIP-1, which was in turn influenced by 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 the Ethereum Improvement Process, 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.