Skip to main content

CIP-9999: 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:

NameDescription
PreambleHeaders containing metadata about the CPS (see below).
AbstractA short (~200 word) description of the target goals and the technical obstacles to those goals.
ProblemA more detailed description of the problem and its context. This section should explain what motivates the writing of the CPS document.
Use casesA concrete set of examples written from a user's perspective, describing what and why they are trying to do. When they exist, this section should give a sense of the current alternatives and highlight why they are unsuitable.
GoalsA list of goals and non-goals a project is pursuing, ranked by importance. These goals should help understand the design space for the solution and what the underlying project is ultimately trying to achieve. Goals may also contain requirements for the project. For example, they may include anything from a deadline to a budget (in terms of complexity or time) to security concerns. Finally, goals may also serve as evaluation metrics to assess how good a proposed solution is.
Open QuestionsA set of questions to which any proposed solution should find an answer. Questions should help guide solutions design by highlighting some foreseen vulnerabilities or design flaws. Solutions in the form of CIP should thereby include these questions as part of their 'Rationale' section and provide an argued answer to each.
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 (---).

FieldDescription
CPSCPS number (without leading 0), or "?" before being assigned
TitleA succinct and descriptive title
StatusOpen
CategoryOne registered or well-known category covering one area of the ecosystem.
AuthorsA list of authors' real names and email addresses (e.g. John Doe )
Proposed SolutionsA list of CIPs addressing the problem, if any
DiscussionsA list of links where major technical discussions regarding this CPS happened. Links should include any discussion before submission, a link to the pull request that created the CPS, and any pull request that modifies it.
CreatedDate created on, in ISO 8601 (YYYY-MM-DD) format

For example:

---
CPS: 1
Title: The Blockchain Trilemma
Status: Open
Category: Consensus
Authors:
- Alice
- Bob
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.

StatusDescription
OpenAny problem statement that is fully formulated but for which there still exists no solution that meets its goals. Problems that are only partially solved shall remain 'Open' and list proposed solutions so far in their header's preamble.
SolvedProblems for which a complete solution has been found1 and implemented. When solved via one or multiple CIPs, the solved status should indicate it as such: Solved: by [,,...].
InactiveThe statement is deemed obsolete or withdrawn for another reason. A short reason must be given between parentheses. For example: `Inactive (...reason...).

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.

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

Implementation Plan

  • Schedule a retrospective in 2-3 months to assess the effectiveness of the process

This CIP is licensed under CC-BY-4.0.

CIP Information

This null ./CIP-9999 created on 2022-10-14 has the status: Active.
This page was generated automatically from: cardano-foundation/CIPs.


  1. A problem may be only partially solved, in which case it remains in status 'Open'. Authors are encouraged to amend the document to explain what part of the problem remains to be solved. Consequently, CPS that are 'Solved' are considered fully addressed.