Abstract

This PIP defines process requirements for changes to Pearl's consensus rules. Changes take one of two lanes. The standard lane carries a Standards Track PIP and a minimum on-chain notice window before activation. The expedited lane exists for a defect that puts the network at risk, keeps a much shorter notice floor, and pays for the speed with a published advisory, a bounded scope, and retroactive documentation. The PIPs repository maintains a register listing every consensus change ever activated on mainnet, including the historical ones that predate this PIP, and recording which lane each one used. The goal is that any party running a node, a pool, or an independent index can learn what the validity rules are, and when they changed, from documents rather than from diffing releases.

Motivation

Pearl's block structure already anticipates consensus change. The whitepaper's block-structure section defines the certificate as "certificate := version || bytes" and states that "Separating the certificates keeps header format stable, yet allowing future upgrades to the certificate mechanism" (Pearl whitepaper, Block Structure; quoted 2026-08-11). The mechanism works and has carried two upgrades, to version 2 at height 71,935 and to version 3 at height 99,000. What it does not carry is the document trail that tells a node or pool operator which rules are in force at which height, and when that changed. This PIP adds that half.

Pearl's governance record to date, from public artifacts:

1. Mainnet has activated five consensus-affecting changes beyond the launch rules (unit: activated mainnet consensus changes, one per register entry; the genesis rule set is a baseline rather than a change and is excluded, as is any proposal with no activation height): a certificate-capability hard fork at height 71,935, a capability-retracting softfork at height 91,630, a release-gated validity-semantics fix in v1.2.1, a proof-parameter softfork at height 96,251, and a commitment-layer hard fork at height 99,000. One of the five (71,935) has a PIP; the other four have none. The one with a PIP is the one whose capability was later retracted, at 91,630, with no PIP in either direction.
2. The 96,251 softfork shipped in a release published 12 h 14 m 35 s before its activation height (release publication timestamp against the activation block's timestamp, recomputed 2026-08-11; an earlier estimate of about 18.5 hours, published in the independent register described under Rationale, is not reproducible from those two endpoints and is corrected here). Measured adaptation on the network: one pool stack shipped four releases within 14 hours of activation, and the whole network reached full compliance with the new rule about two days after the fork.
3. The 99,000 hard fork changed how the noise seeds derive from the certificate's commitments and required a new certificate version network-wide at a single height. The release carrying the height that activated was published 1 h 33 m 56 s before that block, the shorter of the two notice windows we have measured (same two endpoints, measured 2026-08-11; the 71,935 and 91,630 changes carry no release publication timestamp we could measure against). The upgrade guide shipped in that release states that mining software deriving seeds the old way produces invalid shares from the fork height on, so the notice window was also the window in which every miner had to be rebuilt.
4. One testnet fork height has been edited retroactively: a testnet fleet was not upgraded for the 91,630-class change, blocks that violated the shipped height were accepted, and a later release moved the height after the fact to legalize them (public pull request, merged by its author with no review comments; checked 2026-08-07).
5. Before this proposal, the repository's complete history contained no outside contributions and no issues: eight pull requests, every one from an account affiliated with the project, and no issues at all (checked 2026-08-15). This proposal and its companions are offered as the first such contributions. That is context rather than criticism. A process is only worth writing down if someone outside the project can follow it, and this submission is the first occasion to find out whether this one can be.

None of this is a claim of bad faith. The record shows that release diffs are currently the reliable statement of Pearl's consensus rules, and that the notice available to node and pool operators has been as short as 1 h 34 m. Independent validation, academic measurement, exchange listing diligence, and miner capacity planning all need better than that.

Specification

A consensus change takes one of two lanes. Rules 1 to 3 define the standard lane, rule 4 defines the expedited lane and the conditions on which it may be used.

1. A change to consensus validity rules taking the standard lane MUST be described by a Standards Track PIP (category Consensus) merged into the PIPs repository, at Draft status or later, before the release that schedules its activation is published.
2. That PIP MUST state: the fork class (hard or soft), the activation height and network, the exact validation rules changed (with source references), and the behavior of non-upgraded nodes across activation.
3. A standard-lane activation height MUST lie at least 3,600 blocks after the publication of the release that first ships it (8.1 days at the 194-second block target).
4. A change whose purpose is to mitigate a defect that is being exploited, or that is exploitable sooner than the standard lane can complete, MAY take the expedited lane. The expedited lane is exempt from rules 1 and 3 and carries these requirements instead:
   1. The activation height MUST lie at least 900 blocks after the publication of the release that schedules it (48.5 hours at the same block target), unless the release notes state that advance notice would itself increase risk to the network. Where they state that, the notice MAY be shorter, and the statement MUST ship with that release rather than be added after activation.
   2. An advisory MUST be published with that release, naming the class of defect, the affected versions, and the behavior of non-upgraded nodes across activation. It need not describe how to reproduce the defect while the defect is not public.
   3. The change MUST be limited to the mitigation and to what the mitigation requires. Any other consensus-affecting change shipped in the same release takes the standard lane and its own activation height.
   4. A retroactive PIP MUST be merged within 7 days of activation, stating which condition of this rule was relied on, what notice was actually given, and what the change does.
   5. A description of the defect sufficient to verify the fix MUST be published within 30 days of activation, or sooner if the defect becomes public by another route.
5. A retroactive edit to any previously shipped consensus parameter, including fork heights on any network, is a consensus change under this PIP and MUST be documented per rule 4.4.
6. The PIPs repository MUST maintain a register file with one entry per consensus change activated on Pearl mainnet: height (or release gate), fork class, lane, shipping release, the governing PIP or the word "none", and one line of description. Where the same change also activated on testnet, testnet2, regtest or simnet, the entry MUST record those heights inside it; they are not separate entries, so the entry count and the mainnet change count stay equal. The register MUST be backfilled to genesis. Historical entries with no PIP keep "none", and entries that predate this PIP carry no lane; this PIP does not rewrite history, it records it.
7. PIP editors SHOULD decline to mark a Consensus PIP Final while any of its activation facts are missing from the register.

Rationale

Both windows are sized from measured behavior on this network rather than from convention elsewhere.

The standard lane is sized against the adaptation time the network has actually shown. Under forcing conditions the network reached full compliance about two days after activation, so 3,600 blocks (8.1 days at the 194-second block target) is about 4 times that figure, which leaves room for a weekend and a missed announcement on either side. Against the two notice windows actually measured it is a large multiple: about 16 times the 12 h 14 m 35 s of the 96,251 softfork, and about 124 times the 1 h 33 m 56 s of the 99,000 hard fork. Rule 3 constrains when an activation height may fall, not when code may ship; rule 1 is the one that gates the scheduling release, and it asks only for a Draft PIP.

The expedited lane exists because this network is young, has shipped urgent fixes, and will ship more. A single long window with no named alternative does not prevent short-notice forks, it only ensures that the process document is ignored the first time one is needed, which is the state the record already shows. Naming the fast path and pricing it is the more durable arrangement. Its floor of 900 blocks (48.5 hours) is set at about the two-day compliance figure and is still about 4 times the notice given for the 96,251 softfork and about 31 times the notice given for the 99,000 hard fork, so the lane that exists for emergencies is bounded below by more notice than either measured case actually had.

Rule 4.1 admits that some defects cannot be pre-announced at all, and requires the claim to ship with the release rather than be constructed afterwards, which turns it into a dated public statement that can be weighed later. Rule 4.3 is the one that keeps the lane narrow: a fast path is where unrelated work gets carried along, and the release that first shipped the most recent hard fork changed 75 files, 32 of them on the consensus surface, per the register's entry for it. Rule 4.4 sets the documentation debt at 7 days rather than a fortnight, because a retroactive PIP written two weeks later is written after the operators who needed it have already worked the change out from the diff.

The register exists because the current arrangement puts the work on the reader: the record of what Pearl's consensus rules are lives in release diffs, and at least one independent register had to be built outside the project to track them. Backfilling from genesis is cheap: on rule 6's unit, one entry per activated mainnet consensus change, the whole history is five entries plus the launch rule set as of 2026-08-11, each carrying its other-network heights inside it. It can seed from existing independent work.

Precedent starts inside Pearl. PIP-1 established this repository's process (dated 2026-05-17), and PIP-2 documented the height-71,935 hard fork, the single activated mainnet consensus change that has a PIP. The pattern is already set; this PIP asks that it apply to every consensus change instead of one in five. Outside Pearl, Bitcoin's BIP-2 process and activation conventions, and Ethereum's EIP process with Meta EIPs enumerating each fork's contents, both treat "the rules changed, where is the document" as a process invariant. This PIP asks for the same invariant at a fraction of the ceremony, matched to a small ecosystem.

Backwards Compatibility

No protocol change and no effect on any deployed software. The requirements apply to changes scheduled after this PIP reaches Active; historical changes are affected only by appearing in the register.

Security Considerations

Short-notice forks concentrate upgrade risk: operators patch under time pressure, in two classes that now both have an observed instance. A non-upgraded fleet keeps extending a minority chain; the observed instance is the retroactively legalized testnet blocks in Motivation item 4. A miner or pool that does not rebuild in time produces invalid shares from the activation height on; the observed instance is the mainnet hard fork in Motivation item 3, with 1 h 33 m 56 s of notice, and unlike the height-71,935 fork it left no path for old mining software to keep producing valid work. A minimum notice window spreads both risks. The expedited lane preserves the ability to ship an urgent fix, and prices it in disclosure rather than in delay: an advisory at release time, a scope limited to the mitigation, a retroactive PIP within 7 days, and a defect description within 30 days. Every use therefore leaves a dated public record, and a lane used routinely is visible as such in the register. The 30-day description in rule 4.5 is the term that keeps the lane from becoming a way to hold a known defect undocumented indefinitely, which is itself a risk to anyone validating the chain independently. A maintained register also hardens the network against disputes about which rules were in force at a given height, which matters for any party validating history independently.

Copyright

Copyright and related rights waived via CC0.