KCC Purpose and Guidelines

Table of Contents

• 1. What is a KCC?
• 2. KCC Rationale
• 3. KCC Types
• 4. KCC Work Flow
  • 4.1 Shepherding a KCC
  • 4.2 KCC Process
  • 4.3 Application to existing KCCs
• 5. What belongs in a successful KCC?
• 6. KCC Formats and Templates
• 7. KCC Header Preamble
• 8. Linking
  • 8.1 Linking to External Resources
  • 8.2 Linking to other KCCs and KIPs
• 9. Auxiliary Files
• 10. Registries
• 11. Transferring KCC Ownership
• 12. KCC Editors
  • 12.1 Editor Responsibilities
• 13. Style Guide
• 14. History
• 15. Copyright

1. What is a KCC?

KCC stands for Kaspa Call for a Convention. A KCC is a design document specifying a convention around which independent Kaspa ecosystem participants and implementations may converge: covenant conventions, application interfaces, asset standards, wallet and indexer interoperability, based applications, verifiable programs, and other areas where independent implementations benefit from convergence. The KCC should provide a concise technical specification of the convention and a rationale for it. The KCC author is responsible for building consensus within the community and documenting dissenting opinions.

A finalized KCC marks an ecosystem convergence point. It does not make the convention protocol ground truth, and it does not obligate any participant to implement it.

KCCs do not propose changes to Kaspa consensus or core-node behavior. Such changes belong in Kaspa Improvement Proposals (KIPs). A KCC may depend on consensus features defined by KIPs and must identify such dependencies in its Requires header.

2. KCC Rationale

We intend KCCs to be the primary mechanism for proposing new ecosystem conventions, for collecting community technical input on an issue, and for documenting the design decisions behind conventions the ecosystem has adopted. Because KCCs are maintained as text files in a versioned repository, their revision history is the historical record of the convention.

For implementers, KCCs are a convenient way to track the maturity of a convention: ideally each implementation maintainer would list the KCCs they have implemented, giving end users a convenient way to know the state of any given implementation or library.

3. KCC Types

There are three types of KCC:

• A Standards Track KCC describes any convention that affects interoperability between independent implementations: byte layouts, encodings, ABIs, application-level standards, and interface conventions. Standards Track KCCs consist of a design document, a specification with conformance vectors, and (before finalization) a reference implementation. Standards Track KCCs are broken down into the following categories:
  • Covenant: conventions concerning covenant programs themselves, covering terminology, byte layouts, state, templates, and transition rules.
  • ABI: conventions on the Program ABI surface, covering types, encodings, entrypoints, dispatch, authority schemes, and artifact formats.
  • Application: application-level standards and conventions, such as token standards and registries of application behavior.
  • Interface: conventions for interoperability between applications and surrounding software such as wallets, indexers, transaction builders, and discovery.
• A Meta KCC describes a process surrounding the KCC repository or proposes a change to a process. Meta KCCs apply to areas other than the conventions themselves, including procedures, guidelines, and changes to the decision-making process. This document is a Meta KCC.
• An Informational KCC describes a Kaspa ecosystem design issue, or provides general guidelines or information to the community, but does not propose a convention. Informational KCCs do not necessarily represent a community consensus or recommendation, so users and implementers are free to ignore them or follow their advice.

It is highly recommended that a single KCC contain a single key convention or new idea. The more focused the KCC, the more successful it tends to be.

A KCC must meet certain minimum criteria. It must be a clear and complete description of the proposed convention. The convention must represent a net improvement, and, for Standards Track KCCs, must be implementable exactly, byte for byte, from the specification alone.

4. KCC Work Flow

4.1 Shepherding a KCC

Parties involved in the process are you, the champion or KCC author, the KCC editors, and the Kaspa ecosystem community.

Before you begin writing a formal KCC, you should vet your idea. Ask the community first if the idea is original to avoid wasting time on something that will be rejected based on prior research. It is thus recommended to open a discussion thread at the Kas-Smiths research forum to do this. You may also open a pull request before the document is complete in order to share it.

Once the idea has been vetted, your next responsibility is to present the idea by means of a KCC to reviewers and all interested parties, and invite feedback at the discussion thread recorded in the Comments-URI header. You should try and gauge whether the interest in your KCC is commensurate with both the work involved in implementing it and how many parties will have to conform to it. Negative community feedback will be taken into consideration and may prevent your KCC from moving past the Draft stage.

4.2 KCC Process

The following is the standardization process for all KCCs in all types and categories. Every KCC follows it, including this one.

Idea -> Draft -> Review -> Last Call -> Final
          ^________|_________|
          (changes required)

Draft | Review | Last Call -> Stagnant (6 months of inactivity)
Stagnant -> Draft | Review  (resurrection)
Draft | Review -> Withdrawn (irreversible)

• Idea: An idea that is pre-draft. It is not yet tracked as a numbered KCC, but it may exist as an open pull request, and opening one at this stage is welcome. A pull request is not closed for being incomplete or for not yet conforming to this document. It stays open and an editor or someone else will flag out specifically what is missing. Once it confirms, it can be merged which is when it becomes a Draft.

• Draft: The first formally tracked stage of a KCC in development. A KCC is merged by a KCC editor into the KCC repository when properly formatted.

• Review: A KCC author marks the KCC as ready for and requesting peer review.

• Last Call: The final review window for a KCC before moving to Final. A KCC editor assigns Last Call status and sets a review end date (Last-Call-Deadline), typically 14 days later. If this period results in necessary normative changes, the KCC reverts to Review.

• Final: This KCC represents the final standard, an ecosystem convergence point. A Final KCC exists in a state of finality and should only be updated to correct errata and add non-normative clarifications. A normative defect correction in a Final KCC must be announced at the KCC's Comments-URI and recorded in a Changelog section of the document. Any other substantive change is made by a new KCC that supersedes it, setting Supersedes on the new document and Superseded-By on the old one.

  In addition to a completed Last Call, a Standards Track KCC moves to Final only when all of the following hold:

  1. the conformance vectors required by Section 5 are present, in both human-readable and machine-readable form;
  2. at least one publicly available implementation passes all machine-readable conformance vectors and is linked from the KCC or its pull request; and
  3. every entry in Requires is itself Final (for KCCs) or Active (for KIPs).

  These criteria are deliberately stricter than in some other ecosystems. A Final KCC is a claim that independent implementations can converge byte-for-byte, and that claim is only credible once demonstrated.

• Stagnant: Any KCC in Draft, Review, or Last Call that is inactive for a period of 6 months or greater is moved to Stagnant. A KCC may be resurrected from this state by authors or KCC editors by moving it back to Draft or its earlier status. If not resurrected, a proposal may stay forever in this status.

• Withdrawn: The KCC authors have withdrawn the proposed KCC. This state has finality and can no longer be resurrected using this KCC number. If the idea is pursued at a later date it is considered a new proposal. The Withdrawal-Reason header must be set.

Status changes are made by pull request. Every status change except the initial Draft merge should be announced at the KCC's Comments-URI. The README index of this repository lists every KCC with its number, title, authors, and status, and is updated in the same pull request as any status change.

4.3 Application to existing KCCs

KCC-1, KCC-2, and KCC-20 predate this document and retain their Draft status. Before entering Review, each must be brought into conformance with this document: the header preamble of Section 7, the section requirements of Section 5, including Security Considerations and conformance vectors, and the style rules of Section 13.

5. What belongs in a successful KCC?

Each KCC should have the following parts:

• Preamble: RFC 822 style headers containing metadata about the KCC, described in Section 7.
• Abstract: A multi-sentence (short paragraph) technical summary. Someone should be able to read only the abstract to get the gist of what the specification does.
• Motivation (optional): A motivation section is critical for KCCs that propose replacing or extending existing conventions, or whose need is not evident. It should clearly explain why the existing ecosystem conventions are inadequate to address the problem the KCC solves. This section may be omitted if the motivation is evident.
• Specification: The technical specification should describe the convention in enough detail that a conforming implementation can be written from it alone. Normative requirements use the key words of RFC 2119 and RFC 8174, capitalized, with the standard boilerplate included. If pseudocode and prose state the same rule, the specification says which is authoritative. Terminology defined by existing KCCs should be reused with citation rather than redefined.
• 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.
• Backwards Compatibility (optional): All KCCs that introduce incompatibilities with previously deployed conventions must include a section describing these incompatibilities and their consequences. The KCC must explain how the author proposes to deal with these incompatibilities. This section may be omitted if the proposal does not introduce any.
• Conformance Vectors: Mandatory for Standards Track KCCs that define byte layouts, encodings, hashes, or other computable artifacts; optional otherwise. Vectors cover every construction the KCC defines and are provided both in the document and in machine-readable form (JSON) under kcc-NNNN/vectors/. The two must agree, and the machine-readable form is authoritative for automated testing.
• Reference Implementation (optional before Final): An optional section that contains, or links to, a reference implementation. A Standards Track KCC cannot reach Final without one that passes the conformance vectors, per Section 4.2.
• Security Considerations: All Standards Track KCCs must contain a section that discusses the security implications and considerations relevant to the proposed convention: the threat model, trust assumptions, known foot-guns, and malleability or replay concerns, along with important discussions and decisions made during the life of the proposal. A Standards Track KCC cannot proceed to Last Call without this section. Meta and Informational KCCs, such as this document, omit it where it does not apply.
• Copyright Waiver: All KCCs must be in the public domain. The copyright waiver must link to the license file and use the following wording: Copyright and related rights waived via [CC0](LICENSE.md).

6. KCC Formats and Templates

KCCs should be written in Markdown format. There is a template to follow. Each KCC is a single file named kcc-NNNN.md, where NNNN is the KCC number zero-padded to four digits.

7. KCC Header Preamble

Each KCC begins with a fenced code block containing RFC 822 style headers, in the following order. Headers marked with "*" are optional; all other headers are required.

Each author is listed in one of these formats, comma-separated:

Random J. User (@username)
Random J. User (@username) <address@dom.ain>
Random J. User <address@dom.ain>
Random J. User

At least one author must use a GitHub username, in order to get notified on change requests and to have the capability to approve or reject them.

The Comments-URI thread must be publicly readable without an account. Substantive design discussion should happen there rather than in pull-request comments, so that the record survives the pull request.

8. Linking

8.1 Linking to External Resources

Other than the exceptions below, links to external resources should not be included: external resources may disappear, move, or change unexpectedly. Permitted external resources, pinned to a stable form:

• Kaspa Improvement Proposals (KIPs), linked to a specific commit where the reference is normative;
• Bitcoin Improvement Proposals (BIPs), linked to a specific commit;
• IETF RFCs, via rfc-editor.org;
• W3C recommendations, as dated specifications in the /TR/ namespace;
• academic papers, via a Digital Object Identifier or a stable institutional URL.

8.2 Linking to other KCCs and KIPs

References to other KCCs use the format KCC-N, hyphenated. The first reference in a document is a relative Markdown link, e.g. [KCC-1](/1/), so that links work in this repository and in every fork and mirror of it. References to KIPs use the format KIP-N.

9. Auxiliary Files

Images, diagrams, reference code, extended rationale, and machine-readable conformance vectors are included in a subdirectory named kcc-NNNN/ for that KCC, and linked from the main document with relative paths. Auxiliary material is non-normative unless the main document states otherwise, with one exception: the machine-readable conformance vectors under kcc-NNNN/vectors/, which are authoritative per Section 5. Diagrams must be accompanied by an equivalent textual description.

10. Registries

A registry is an enumerated value space defined by a KCC whose values are assigned over time, for example authority-scheme bytes or borrow-scheme selectors. A KCC that defines a registry must specify the value space and the initial assignments, and must state that unassigned values are reserved.

New registry values are assigned only by a Final KCC that claims them. Adding a row to a registry table recording an assignment made by another Final KCC is an editorial change to the defining document. Implementations must treat unassigned registry values as invalid rather than assigning them local meaning.

11. Transferring KCC Ownership

It occasionally becomes necessary to transfer ownership of a KCC to a new champion. In general, we'd like to retain the original author as a co-author of the transferred KCC, 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 KCC process, or is unreachable. A bad reason to transfer ownership is because you don't agree with the direction of the KCC. We try to build consensus around a KCC, but if that's not possible, you can always submit a competing KCC.

If you are interested in assuming ownership of a KCC, send a message asking to take over, addressed to both the original author and the KCC editors. If the original author doesn't respond in a timely manner, the KCC editors will make a unilateral decision.

12. KCC Editors

The KCC editors are the maintainers of this repository, as listed by the repository's access settings.

12.1 Editor Responsibilities

For each new KCC that comes in, an editor does the following:

• Read the KCC 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.
• Check that the title accurately describes the content.
• Check the KCC for language (spelling, grammar, sentence structure, etc.), markup, and conformance to this document.

If the KCC isn't ready, the editor leaves the pull request open and gives the author specific instructions for revision, rather than closing it. Once the KCC is ready for the repository, the editor will:

• Assign a KCC number. Numbers are generally assigned incrementally and are never reused; the editors may assign a memorable number where recognizability aids adoption (for example, KCC-20 for the fungible-token convention).
• Merge the corresponding pull request.
• Send a message back to the KCC author with the next step.

The editors don't pass judgment on KCCs. They merely do the administrative and editorial part: merging a Draft signifies that it is well-formed and in scope, not that the editors endorse it. The editors also monitor KCC changes, correct structure, grammar, spelling, and markup mistakes, judge whether the Last Call window has surfaced unresolved blocking objections, and execute status transitions. An objection is blocking when it demonstrates a soundness or security defect, or an ambiguity that two conforming implementations could resolve differently. An editor who authored a KCC should abstain from that judgment on their own KCC when more than one editor exists.

13. Style Guide

• Titles: written in title case; do not contain the word "standard" or any variation thereof; do not contain the KCC's number.
• Descriptions: one full short sentence in sentence case; do not contain the word "standard" or any variation thereof; do not contain the KCC's number.
• KCC numbers: written in the hyphenated form KCC-N where N is the number without padding; file names keep the four-digit padding.
• Punctuation: do not use em dashes. Use a comma, colon, semicolon, parentheses, or a new sentence instead.
• RFC 2119 and RFC 8174: KCCs are encouraged to follow RFC 2119 and RFC 8174 for terminology, and to insert at the beginning of the Specification section the following: "The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174." Lowercase forms of these words carry no normative force.

14. History

This document was derived heavily from Ethereum's EIP-1, which was in turn derived from Bitcoin's BIP-0001 (written by Amir Taaki) and Python's PEP-0001 (written by Barry Warsaw, Jeremy Hylton, and David Goodger). In many places text was simply copied and modified.

15. Copyright

Copyright and related rights waived via CC0.