Cardano Problem Statements

Abstract

A Cardano Problem Statement (CPS) is a formalized document for the Cardano ecosystem and the name of the process by which such documents are produced and listed. CPSs are meant to complement CIPs and live side-by-side in the CIP repository as first-class citizens.

Note Read this CIP's number as "CIP minus 1"

Motivation: why is this CIP necessary?

A common friction point regarding complex CIPs is how their main problems are stated. For example, the 'Motivation' section in CIPs is sometimes not sufficient -- or simply underused -- to describe the various aspects of a problem, its scope, and its constraints in the necessary detail. This lack of clarity leads, in the end, to poorly defined issues and unfruitful debates amongst participants who understand problems differently.

The introduction of the Cardano Problem Statements (CPSs) addresses this gap by defining a formal template and structure around the description of problems. CPSs are meant to replace the more elaborate motivation of complex CIPs. However, they may also exist on their own as requests for proposals from ecosystem actors who've identified a problem but are yet to find any suitable solution.

Over time, CPSs may complement grant systems that want to target well-known problems of the ecosystem; they can, for example, serve as the foundation for RFP (Request For Proposals) documents. We hope they may also help make some discussions more fluid by capturing a problem and its various constraints well.

Specification

CPS

Structure

CPSs are, first and foremost, documents that capture a problem and a set of constraints and hypotheses. Documents are Markdown files with a front matter Preamble and pre-defined sections. CPS authors must abide by the general structure, though they are free to organize each section as they see fit.

The structure of a CPS file is summarized in the table below:

Header preamble

Each CIP must begin with a YAML key:value style header preamble (also known as 'front matter data'), preceded and followed by three hyphens (---).

For example:

---
CPS: 1
Title: The Blockchain Trilemma
Status: Open
Category: Consensus
Authors:
    - Alice <alice@domain.org>
    - Bob <bob@domain.org>
Proposed Solutions: []
Discussions:
    - https://forum.cardano.org/t/solving-the-blockchain-trilemma/107720
    - https://github.com/cardano-foundation/cips/pulls/9999
Created: 2009-02-14
---

Note A reference template is available in .github/CPS-TEMPLATE.md

Repository Organization

A CPS must be stored in a specific folder named after its number and in a file called README.md. Before a number is assigned, use ???? as a placeholder name (thus naming new folders as CPS-????). After a number has been assigned, rename the folder.

Additional supporting files (such as diagrams, binary specifications, dialect grammars, JSON schemas etc.) may be added to the CPS's folder under freely chosen names.

For example:

CPS-0001
├── README.md
└── requirements.toml

Statuses

From its creation onwards, a problem statement evolves around the following statuses.

Note There is no "draft" status: a proposal which has not been merged (and hence exists in a PR) is a draft CPS. Draft CPSs should include the status they aim for on acceptance, typically but not always; this will be 'Open'.

Categories

As defined in CIP-0001.

Licensing

CPSs are licensed in the public domain. More so, they must be licensed under one of the following licenses. Each new CPS must identify at least one acceptable license in its preamble. In addition, each license must be referenced by its respective abbreviation below in the "Copyright" section.

Warning

All licenses not explicitly included in the above lists are not acceptable terms for a Cardano Problem Statement unless a later CIP extends this one to add them.

The CPS Process

1. Early stages (same as CIP-0001)

1.a. Authors open pull requests with their problem statement (as defined in CIP-0001)

1.b. Authors seek feedback (as defined in CIP-0001)

2. Editors' role (same as CIP-0001)

2.a. Triage in bi-weekly meetings (as defined in CIP-0001)

2.b. Reviews (as defined in CIP-0001)

3. Merging CPSs in the repository

A statement must be well-formulated (i.e. unambiguous) and demonstrate an existing problem (for which use cases exist with no suitable alternatives). When related to a current project, the problem statement must also have been acknowledged by its respective project maintainers. In some cases, problem statements may be written after the facts and be merged directly as 'Solved' should they document in more depth what motivated an existing solution.

Problem statements deemed unclear, for which alternatives exist with no significant drawbacks or establish unrealistic goals, shall be rejected (i.e. pull request closed without merge) with justifications or withdrawn by their authors.

Similarly, problems that appear abandoned by their authors shall also be rejected until resurrected by their authors or another community member.

4. Actors of the ecosystem design and work on possible solutions

Once merged, authors, project maintainers, or any other ecosystem actors may propose solutions addressing the problem in the form of CIP. They add their CIP to the 'Proposed Solutions' field in the CPS' 'Preamble' once a solution has been fully implemented and reaches the goals fixed in the original statement.

Of course, a solution may only partially address a problem. In this case, one can alter the problem statement to incorporate the partial solutions and reflect the remaining issue(s) to solve.

Editors

As defined in CIP-0001.

Rationale: how does this CIP achieve its goals?

Goals

Goals make it easier to assess whether a solution solves a problem. Goals also give a direction for projects to follow and can help navigate the design space. The section is purposely flexible -- which we may want to make more rigid in the future if it is proven hard for authors to articulate their intents. Ideally, goals capture high-level requirements.

Use Cases

Use cases are essential to understanding a problem and showing that a problem addresses a need. Without use cases, there is, in fact, no problem, and merely disliking a design doesn't make it problematic. A use case is also generally user-driven, which encourages the ecosystem to open a dialogue with users to build a system that is useful to others and not only well-designed for the mere satisfaction of engineers.

Open questions

This section is meant to save time, especially for problem statement authors who will likely be the ones who end up reviewing proposed solutions. Open questions allow authors to state upfront elements they have already thought of and that any solution should consider in its design. Moreso, it is an opportunity to mention, for example, security considerations or common pitfalls that solutions should avoid.

Path to Active

Acceptance Criteria

• Review this proposal with existing actors of the ecosystem
• Formulate at least one problem statement following this process
  • CPS-0001: Metadata Discoverability & Trust
  • CPS-0002: Pointer Addresses

Implementation Plan

• Confirm after repeated cycles of CPS submissions, reviews, and merges that the CPS process is both effective and accessible to the community.

Copyright

This CIP is licensed under CC-BY-4.0.