PIP-1: PIP Purpose and Guidelines

Abstract

A Pearl Improvement Proposal (PIP) is a design document providing information to the Pearl community, or describing a new feature for the Pearl network, its processes, or its environment. PIP-1 itself describes what a PIP is, the kinds of PIPs that exist, the lifecycle a PIP goes through, and the minimum format a PIP must follow.

PIPs are the primary mechanism for proposing new features, for collecting community input on an issue, and for documenting the design decisions that have gone into Pearl.

What is a PIP?

A PIP is a short, focused document that:

• describes a single change or topic;
• explains the motivation for that change;
• specifies it precisely enough that competent implementers can build it from the document alone;
• discusses backwards compatibility, security, and privacy considerations where relevant;
• carries a stable identifier (its PIP number) and an explicit status.

PIPs are not a substitute for code. They are the contract between the people designing Pearl and the people running it.

PIP Types

Every PIP MUST declare one of the following types in its preamble:

• Standards Track: describes a change that affects most or all Pearl implementations, such as a change to the consensus protocol, the wire protocol, the way transactions or blocks are validated, or any change that affects the interoperability of Pearl software. Standards Track PIPs further specify a category:
  • Consensus: changes that require a hard or soft fork.
  • Networking: changes to peer-to-peer protocols, message formats, and relay rules that do not change consensus.
  • Interface: client APIs/RPCs, RPC schemas, or other interfaces used by external software.
  • Applications: application-level standards and conventions, including address formats, key derivation, signing protocols, URI schemes, and other ecosystem-facing standards.
• Informational: provides general guidelines, design rationale, or background information to the Pearl community. Informational PIPs do not recommend a particular feature and implementers are free to ignore them.
• Process: describes a process surrounding Pearl, or proposes a change to one. Process PIPs are like Standards Track PIPs but apply to things outside the Pearl protocol itself. They may not be ignored. PIP-1 is itself a Process PIP.

PIP Statuses

A PIP moves through the following statuses during its life:

• Draft: The PIP is being actively edited by its author(s). It has been merged into the PIPs repository so it has a stable number, but it is not considered final. This is the entry status for all new PIPs.
• Proposed: The PIP is feature-complete in the eyes of its author(s) and has been opened for broader community review. No further substantive changes are expected before a status decision.
• Active: The PIP describes an ongoing process or guideline (only applies to Process and Informational PIPs).
• Final: The PIP describes a Standards Track change that has been accepted and deployed.
• Withdrawn: The PIP has been withdrawn by its author(s).
• Rejected: The PIP has been formally rejected and will not be pursued in its current form.
• Replaced: The PIP has been obsoleted by a later PIP. The preamble of the replaced PIP MUST set superseded-by to the replacement PIP's number.
• Obsolete: The PIP describes a feature or process that is no longer in use, but is preserved for historical record.

Status transitions are tracked in the source repository and reflected on this site. Once a PIP reaches Final, Rejected, Withdrawn, Replaced, or Obsolete it SHOULD NOT be edited except to correct typos, clarify wording, or add references.

Submitting a PIP

PIPs are managed through pull requests against the source repository github.com/pearl-research-labs/pips.

The intended flow is:

1. Discuss first. Float the idea on the Pearl research forum, on the relevant chat channel, or in an issue on the PIPs repository. The goal of this step is to find out whether the idea has already been proposed and to collect early objections cheaply.
2. Fork the repository and copy pip-template.md to a new file named PIPS/pip-XXXX.md. Use XXXX = 9999 while the PIP is in flight; the editors will assign a real number when the PIP is merged.
3. Write the PIP using the required preamble (see below) and at least the sections: Abstract, Motivation, Specification, Rationale, Backwards Compatibility (if applicable), Security Considerations (if applicable), and Copyright. Images, diagrams, and other auxiliary files belong in assets/pip-XXXX/ and are referenced with relative links.
4. Open a pull request to the main branch of the PIPs repository. The PR description should include a one-paragraph summary suitable for someone skimming the change.
5. Address review. PIP editors will check format, scope, and clarity, and the community will review technical content. The author SHOULD update the PIP in response to review comments rather than arguing in PR threads.
6. Merge as Draft. When the format is clean and the scope is well-defined, editors assign a PIP number and merge the PR with status Draft.
7. Promote. Once feature-complete, the author opens a follow-up PR moving the status to Proposed, then Final / Active once accepted.

PIP editors are not gatekeepers of merit. They are responsible for ensuring that PIPs are well-formatted, in scope, and clearly written.

Required Preamble

Every PIP MUST begin with a YAML front-matter block containing at least:

pip: <number>           # assigned by editors; use 9999 while drafting
title: <short title>    # max ~60 characters
description: <one-line description>
author: <name(s) or handle(s)>
status: Draft           # one of the statuses above
type: Standards Track   # or Informational, or Process
category: Consensus     # required if type is Standards Track
created: YYYY-MM-DD

Optional fields:

requires: <PIP number(s)>      # PIPs this PIP depends on
replaces: <PIP number>         # PIP this PIP replaces
superseded-by: <PIP number>    # filled in when status becomes Replaced
discussions-to: <URL>          # discussion thread for in-flight PIPs

All fields are free text except where a finite vocabulary is specified above.

Style Guide

• Write specifications, not advertising copy. Prefer precise, boring language over rhetoric.
• Use SHOULD / MUST / MAY (RFC 2119) only inside the Specification section, and only where conformance is intended.
• Code, math, and protocol constants belong in fenced code blocks.
• Keep PIPs focused. If you find yourself describing two unrelated changes, split them into two PIPs.
• Cite prior PIPs and external work explicitly; do not assume the reader has read the discussion thread.

Copyright

This PIP, and all PIPs unless explicitly stated otherwise, is placed in the public domain under CC0.