CIP-1: Canton Improvement Proposal Process and Guidelines

Networks Canton
1

CIP-1: Canton Improvement Proposal Process and Guidelines

What is a CIP

A Canton Improvement Proposal (CIP) is a formal design document proposing changes, enhancements, or new standards for the Canton Network. CIPs serve as the primary mechanism for communicating ideas within the Canton community, whether involving technical modifications to the core protocol, economic parameters, governance changes, or process improvements. Each CIP provides a concise but sufficiently detailed technical specification and rationale, allowing stakeholders — including developers, node operators, Super Validators, and application builders — to evaluate the proposal’s impact, feasibility, and alignment with the network’s objectives.

CIPs are intended to be the single canonical source of truth for proposed changes. Rather than informal discussions or ad-hoc decisions, the CIP process ensures that all meaningful changes are documented, discussed publicly, reviewed consistently, and decided through clearly defined governance mechanisms.

CIP-1 defines the CIP process itself: how to write a proposal, how CIPs are categorized, how proposals progress through different lifecycle stages, and how responsibilities are distributed among participants. This document is classified as a Process CIP, meaning it defines governance and coordination rules without introducing new protocol features or network behavior.

CIP Types

Standards Track CIP
Proposals affecting Canton Network’s core protocols, interoperability, or technical standards. These typically require updates to Canton node software and, in some cases, coordinated network-wide upgrades. Standards Track CIPs define behavior that multiple independent implementations or participants must follow to remain compatible.

Sub-categories include:

  • Core: Changes to protocol or consensus rules that require coordinated network upgrades. This includes modifications to block structure, transaction validation logic, consensus parameters, or Global Synchronizer behavior. These proposals have the highest coordination and governance requirements.
  • Daml (Smart Contract Layer): Improvements to smart contract execution semantics or Canton’s DAML integration, including contract lifecycle behavior, execution constraints, or ledger interaction rules.
  • Interface (APIs/RPC): Changes to how external applications, SDKs, wallets, or tooling interact with Canton nodes, including RPC endpoints, API schemas, and client-facing interfaces.
  • Application-Level Standards: Standards for smart contracts and applications built on Canton, such as token standards, asset representations, or cross-application conventions. These proposals aim to improve interoperability at the application layer without modifying core consensus rules.
  • Networking: Improvements to Canton’s networking layer, peer communication, synchronization mechanisms, or message propagation between nodes.

Governance CIP
Proposals focusing on Canton Network’s governance and operational parameters. This includes adding or removing Super Validators, adjusting validator roles or weights, establishing committees or working groups, and modifying governance processes or decision-making structures.

Tokenomics CIP
Proposals modifying economic parameters or incentive structures, such as Canton Coin issuance, distribution schedules, validator rewards, staking mechanics, fee models, or economic safeguards. These proposals typically require both economic rationale and governance approval.

Process (or Informational) CIP
Proposals outlining processes, guidelines, or other non-technical aspects of the Canton ecosystem. These do not introduce protocol or economic changes but define how the community coordinates, governs itself, or manages upgrades and standards.

Roles and Responsibilities

CIP Author (Champion)
An individual or team responsible for writing the proposal and driving it through the CIP process. Responsibilities include drafting the CIP, initiating and maintaining discussions, incorporating feedback, updating the document through revisions, building community consensus, guiding the proposal through lifecycle stages, providing reference implementations when applicable, and responding to formal reviews and objections.

CIP Editors
Experienced community members responsible for managing the CIP repository and maintaining procedural consistency. Editors review submissions for completeness and formatting, assign CIP numbers, merge drafts, manage status transitions, and verify that required review stages have been respected. Editors act in an administrative capacity and do not judge the technical or political merit of proposals.

Canton Core Developers
For proposals affecting the core protocol or execution environment, core developers provide technical evaluation, assess feasibility and risks, participate in design discussions, signal readiness for acceptance, implement approved changes, coordinate releases, and document reasons for rejection when applicable.

Network Governance (Super Validators and Committees)
Super Validators play a central role in consensus, upgrades, and governance decisions. They review Governance and Tokenomics CIPs, participate in formal votes, signal approval for protocol-level changes, oversee Process CIPs, and may request revisions or reject proposals that lack sufficient support or introduce unacceptable risk.

CIP Workflow

CIP Workflow
CIP Workflow3118×838 162 KB

Idea Formation & Preliminary Discussion

Every CIP begins with an idea. Authors are encouraged to discuss via:

  • CIP Discussion Forum or Mailing List
  • GitHub issues/discussions

Goals: solicit feedback, gauge interest, refine concepts, avoid duplicates.

Drafting the CIP

Authors write a draft following the template with:

  • Header with metadata (number, title, author, discussions-to, status, type, layer, created date, dependencies)
  • Body sections: Simple Summary, Abstract, Motivation, Specification, Rationale, Backward Compatibility, Test Cases, Implementation, Security Considerations

Submitting a Pull Request

  1. Fork the CIP repository
  2. Add draft file (provisional naming)
  3. Submit PR with summary and discussion link
  4. Ensure automated checks pass

Draft Review and Number Assignment

Editors review for:

  • Completeness of required sections
  • Clarity and understandability
  • Valid discussions-to link
  • No duplicates

Upon approval:

  • Assign official CIP number (zero-padded, e.g., CIP-0026)
  • Update header and file name
  • Merge into repository with “Draft” status

Draft Phase and Iteration

  • Ongoing discussion continues
  • Author revises based on feedback
  • Community consensus building
  • Testing & prototyping
  • No fixed timeline

Last Call (Final Review)

When mature:

  1. Author requests Last Call status
  2. Editor reviews and sets end date (minimum 2 weeks)
  3. Announcement to community
  4. Final review period (only minor tweaks allowed)
  5. Evaluate any objections

Decision and Acceptance

Standards Track (Core):

  • Discussion in Core Dev/Governance Calls
  • Technical evaluation and consensus
  • Mark as “Accepted” upon agreement
  • May require on-chain Super Validator vote
  • “Final” after implementation and release

Standards Track (Non-core):

  • Can skip “Accepted” and go to “Final” with community consensus

Governance/Tokenomics:

  • Governance vote required
  • “Final” if approved, “Rejected” if not

Process CIPs:

  • Community endorsement via consensus
  • Mark as “Final” or “Active”

Final Status and Implementation

Final means proposal is fully approved and (where applicable) implemented. For Core proposals, may first be “Accepted” then “Final” after release/activation.

Other Outcome States

  • Deferred: Postponed for future consideration
  • Withdrawn/Abandoned: Author stops or community loses interest
  • Rejected: Decided against after consideration
  • Replaced/Superseded: Subsumed by newer proposal
  • Obsolete: No longer relevant
  • Active: Living documents that evolve (e.g., CIP-1)

CIP Format and Structure

Every Canton Improvement Proposal must follow a standard structure to ensure clarity, consistency, and effective evaluation. Each CIP consists of two main parts: a header (metadata) and a body (proposal content). Supporting materials such as diagrams or reference implementations may be included alongside the CIP in the repository.

CIP Header

The header is a block of YAML (or YAML-like) metadata placed at the top of the document, immediately after the title. It provides structured information used by both readers and tooling to track and manage CIPs.

Example header:

cip: <CIP number>
title: <Short Descriptive Title>
author: <Name or Alias> (<contact info>)
discussions-to: <Discussion URL>
status: <Draft | Last Call | Accepted | Final | Active | Deferred | Rejected | Withdrawn | Replaced | Obsolete>
type: <Standards Track | Governance | Tokenomics | Process>
layer: <Core | Daml | Interface | Application | Governance/Ecosystem | …>
created: <YYYY-MM-DD>
requires: <CIP number(s), optional>
replaces: <CIP number(s), optional>

Header fields:

  • cip: Unique identifier assigned by editors upon merge. Uses zero-padded numbering (e.g., cip: 0026) and never changes.
  • title: Short descriptive title summarizing the proposal.
  • author: Proposal champion(s), optionally with contact details.
  • discussions-to: Link to the primary discussion thread for transparency and context.
  • status: Current lifecycle state of the CIP. Only one status is valid at a time and is updated via approved changes.
  • type: High-level category of the proposal (Standards Track, Governance, Tokenomics, or Process).
  • layer: Affected system domain, primarily for Standards Track CIPs (e.g., Core, Daml, Interface).
  • created: Date the proposal was first submitted.
  • requires: (Optional) Other CIPs that must be finalized first.
  • replaces: (Optional) Earlier CIPs superseded by this proposal.

All fields except requires and replaces are typically mandatory. Consistent naming and casing are required to support automation and indexing.

CIP Body

The body contains the substantive content of the proposal and is written in Markdown. It explains the problem, the proposed solution, and all relevant technical, operational, and governance considerations.

A typical CIP body includes:

  • Simple Summary: Brief, non-technical overview.
  • Abstract: Concise technical summary of the problem and solution.
  • Motivation: Rationale and context explaining why the change is needed.
  • Specification: Precise, implementable description of the proposal, including definitions, rules, interfaces, or algorithms.
  • Rationale: Explanation of design choices and rejected alternatives.
  • Backward Compatibility: Impact on existing software, contracts, data, or processes, and any required migration steps.
  • Test Cases: Example scenarios and expected outcomes to validate correct implementation.
  • Implementation: Current status or plan for implementation, including references to code or releases.
  • Security Considerations: Analysis of risks introduced by the proposal and their mitigations.

The body should be self-contained: all normative requirements and essential explanations must be present in the CIP itself. External links may be used for background or references, but not as substitutes for core specifications.

Referencing and Assets

  • Reference other CIPs as “CIP-X” with hyperlinks
  • Include images in assets folder (e.g., assets/cip-0026/)
  • Use relative paths for images
  • Minimize external dependencies

Managing CIP Changes and Versioning

The CIP process not only defines how to introduce proposals but also how to manage their evolution over time. Given that CIPs can undergo multiple revisions before finalization and that even after finalization the ecosystem might evolve, it’s important to handle changes methodically.

Key principles for managing CIP changes include immutability of finalized content, traceability of edits, and clarity in superseding proposals.

Draft Updates

While a CIP is in Draft status, it’s expected to change – sometimes significantly. Authors update the CIP by making commits to the CIP file (usually via new pull requests). Every change is recorded in the version control history. During draft stage, authors may choose to note major changes within the document for transparency (some add a History or Changelog section at the bottom of the CIP to track significant edits like “2025-10-01: Adjusted parameter X from 100 to 120 based on feedback from Y”). However, this is not strictly required, since Git history serves that purpose. In practice, simple iteration and responding to PR comments is sufficient.

If a CIP is completely rewritten or repurposed while in Draft – which can happen if the original approach proved unworkable and the author shifts to a new design – it might even be advisable to withdraw the original CIP and start a new one. This prevents confusion if the scope has dramatically changed. Otherwise, minor to moderate changes are fine within the same CIP number as draft refinement.

Changing Status

A CIP’s status is not changed arbitrarily – each transition corresponds to a milestone in the process. The only way to change the status field is via an approved change (pull request) to the CIP document. Usually, the author initiates this when they think it’s time (for example, making a PR to change “status: Draft” to “status: Last Call”). The editors oversee these transitions:

  • Editors verify that the criteria for the new status are met (e.g., did we allow at least two weeks of Last Call? Was there an official decision to Accept this core CIP?).
  • If so, the editor merges the status change. If not, they may hold off or close the PR with instructions (like “please extend Last Call another week” or “there’s no consensus yet to go Final, keep it Draft for now”).

Authors cannot just declare their CIP Final without approval. The governance aspect (editor oversight and, for core changes, developer/governance approval) is crucial. This prevents someone from, say, merging their own PR and marking a contentious proposal as Final prematurely.

In git-managed repos, often the rule is that only editors have write access to the main branch, so any status change PR from an author would need editor merging.

One nuance: sometimes for efficiency, an editor might directly change the status in a single commit (especially for straightforward cases like Draft to Last Call). But typically, even that goes through a PR where others can see it (maybe the editor’s own PR).

Authors should not be discouraged if an editor rejects a status-change PR – it usually means “not yet” rather than “never,” and the editor will explain what conditions need to be met.

Final CIP Updates

Once a CIP is Final (or Active), it is essentially locked in terms of content. No normative or substantive changes should be made to it via new commits. The reasoning is that a Final CIP is like a published standard or historical record; changing it would be like altering the past. If an aspect of it is found to be wrong or needing modification, the correct approach is to write a new CIP to amend or supersede it, rather than editing the Final CIP’s text (except in minor ways described below).

Allowed post-Final changes are:

  • Fixing typos or obvious errors in wording that do not change meaning.
  • Adding clarifications that were missing, again as long as they don’t alter the intent (and preferably marked or PR’d as editorial changes).
  • Updating the status if necessary (e.g., to Replaced or Obsolete, with a note).
  • In the case of Active documents, periodic updates as authorized by governance (but then again, such updates are usually mandated by a new CIP or decision).

All changes, even to Final CIPs, are logged via version control. The CIP repository is public, so anyone can inspect the history of a CIP file to see what changed when. This is important for trust – the community can verify that no one surreptitiously altered a standard after the fact.

Superseding and Replacing

When improvements or modifications to an already finalized idea come up, a new CIP should be created rather than modifying the old one. The new CIP can “replace” the old one. This replacement mechanism is handled by the replaces header and status changes:

  • The new CIP includes replaces: <old CIP number> in its header.
  • The new CIP goes through the normal process (Draft, discussions, etc.) until Final.
  • Once the new CIP is Final, an editor updates the old CIP’s status to Replaced (or Superseded) and often adds a note in the old CIP like “Superseded by CIP-XXXX” at the top.
  • The old CIP remains in the repository as a historical record of the previous approach, but it’s clear to readers that it’s no longer the go-to standard or rule.

This mechanism preserves continuity. For example, CIP-0002 was replaced by CIP-0008 and later CIP-0020, reflecting iterative refinement of Canton’s tokenomics. Each iteration got its own CIP, and you can trace the evolution by reading each in turn.

It’s generally discouraged to have two Final CIPs covering the same ground both be active – replacement is the clean way to handle evolution without confusion.

Dependencies (Requires)

When writing a new CIP that depends on another CIP, the author should use the requires field to list those dependencies. This signals to editors and readers that “we shouldn’t finalize this until those prerequisites are resolved.” It might be something like a multi-step upgrade where CIP-0030 sets groundwork that CIP-0031 builds on. If CIP-0031 is submitted first, it would list “requires: 0030” because without CIP-0030 implemented, CIP-0031 doesn’t make sense or can’t function.

Editors will enforce that a CIP that “requires” another will not go Final until the required one is Final (or at least Accepted, depending on context). This prevents, say, locking in a standard that references a protocol change which hasn’t happened.

It also helps ordering upgrades. If CIP A depends on CIP B, then obviously CIP B must be activated first in the network upgrade sequence.

Coordination with Software Versions

For CIPs that result in changes to the Canton software (particularly core and possibly interface changes), it’s helpful to link them with software release versions or network upgrade events. Although this might not be a formal part of the CIP document, often the Implementation section or an appended note will say something like: “Included in Canton release v3.4” or “Scheduled for activation at block height 12,000,000 on testnet, corresponding to mainnet upgrade ‘Spring 2026’.”

Canton network upgrades may be named or numbered; referencing those in the CIP provides context. For example: “This CIP will be implemented in the Periander upgrade (Canton v4.0) if accepted.” After the fact, a Final CIP might note the block or epoch where it went live.

This coordination ensures that readers (especially node operators or developers) know exactly from which point a Final CIP’s changes are active. It also ties the governance document (CIP) to real-world action (software rollout).

Transferring Ownership

Occasionally, a CIP author may become unresponsive or choose to step away from the project. Since a good idea shouldn’t die just because the author left, the CIP process allows for transferring the “ownership” (authorship responsibility) of a Draft CIP to someone else:

  • This is usually done by mutual agreement. If an author is MIA, an interested community member might ask an editor, “Can I take over CIP-XX? I have ideas to push it forward.” The editor may try to contact the original author; if they get no response after a reasonable time, they can approve the transfer.
  • The CIP’s author field can be updated to add the new champion (possibly keeping the original name for credit, but marking the new primary author).
  • From then on, the new author would address feedback, make updates, and advocate for the CIP.
  • The goal is to avoid “orphaned” proposals. Of course, if no one picks it up, a CIP might be marked Withdrawn. But if there’s energy to continue, the process welcomes it.

Any change in authorship should be noted in a CIP update (often an editor will do it by PR or direct commit, including a brief rationale like “Transferring authorship from Alice to Bob as per discussion on #CIP channel”).

Conclusion

The Canton Improvement Proposal process is the foundation of transparent and collaborative development for the Canton Network. By providing a clear, structured path from initial idea through drafting, discussion, review, and final decision, the CIP process ensures that all meaningful changes are openly evaluated and broadly agreed upon before implementation.

This document (CIP-1) defines the types of CIPs, participant roles, proposal workflow, required formatting, and rules for managing change over time. Together, these elements establish a shared expectation: changes to Canton should be deliberate, well-documented, and the result of open discussion rather than surprise.

Adhering to the CIP process delivers key benefits:

  • Inclusivity: Any community member can propose improvements and have them considered on their merits.
  • Transparency: Discussions and decisions are public, creating trust and accountability.
  • Rigor: Clear specifications and rationale reduce risk and improve implementation quality.
  • Coordination: Predictable stages help developers, validators, and application teams prepare for change.
  • Continuity: CIPs form a lasting record of Canton’s technical and governance evolution.

As the Canton ecosystem matures, the CIP process itself may evolve. This document is a living guideline, currently marked Active, and may be refined or replaced as governance practices and tooling advance.

Ultimately, the CIP process embodies Canton’s commitment to an open, reliable, and community-driven network. All participants are encouraged to engage—by reviewing proposals, contributing feedback, and authoring CIPs—to help shape Canton’s future in a structured and collaborative way.

1 Like
2

Great to see CIP-1 formalized so clearly. This document sets a solid foundation for Canton’s governance and technical evolution by defining a transparent, predictable process from idea to final decision. The clear separation of CIP types, well-defined roles, and strict rules around Final/Active documents help avoid ambiguity and reduce governance risk.

Especially valuable is the emphasis on public discussion, Last Call, and proper superseding instead of retroactively changing finalized proposals. Overall, CIP-1 strikes a good balance between rigor and flexibility and should make future upgrades more coordinated, auditable, and community-driven.

1 Like
3

This is well structured and easy to follow. Are there any example CIPs (even early drafts) that people can look at? Seeing a couple of real submissions usually makes it much easier for first-time contributors to get started.

4

Who exactly can submit a CIP? Is it restricted to existing Super Validators and partners, or is the process open to any developer building on the Canton Network? Clear guidelines on ‘who has a seat at the table’ would be very helpful