🔄 Modernize the Conditions to Change the Protocol

[JFWooten4]

Much of the policy checks in this doc were written 7 years ago in #247. Since then, the Foundation and community have come a long way. Except d9501c2, this PR strictly changes lines from there and #279, made 2 weeks later.

Recently, Jay Geng did an awesome job updating his CAP for both implementation and technical details in 2bd0506. I really appreciate seeing the CAP author go back and enrich the explanation of their changes. Jay made complex changes that are way above my head, providing new specifications and concepts for anyone to explore going forward.

But not everyone is as smart as the Core devs. And certainly few have the experience to just look at the codebase and immediately understand how it works. Tomer once called it a complex spider web of interconnected functionality.

Most of my constituents fall into this group. Many of them want to understand the network, and they just need a place to start. This is difficult when many repos use direct commits to main with little or no descriptions despite substantial changes.

The CAPs solve this problem. They provide anyone a clear, ordered changelog of how the network grew over time. They link to the concentrated technical discussions, express why a specific person or team suggested a change, and give a clear audit log of progress to completion.

In my last years writing over 100 PRs for the Docs, I have relied substantially on the CAPs when they relate to changes I need to document. Namely, I have promised my regulators specific protocol-level transactional specifications of claimable balances, in relation to the use case discussed in https://github.com/orgs/stellar/discussions/1504. As such, I have been working a lot with CAP-23.

CAP-23 proposes the new XDR OperationID as the preimage union used to find the ClaimableBalanceID. This matters for us because regulators specifically requested improvements in our management and indexing of claimable-balance IDs. However, the final implementation uses a union called HashIDPreimage, whereas the operation ID is actually a struct.

When I updated the CAP's footnote in 2024 to explain the precomputation and XDR resolution, I mistakenly referenced this final union given my reading of the spec that the union was the preimage. This is incorrect, and in fact the hex of the hash which contains the struct is only a part of the final ID downstream. I forgot to include the type discriminant.

My mistake should not sully the otherwise very well-written CAPs. And there's nothing wrong with addressing an issue like in CAP-75 when reality diverges from the proposal due to implementation. As such, I propose these changes to clarify the amendment process.

First, I've expanded the edit circumstances from just errata to also include procedural and implementation adjustments. The CAPs can already be adjusted in title meta when they are superseded. This first section makes that carveout explicit and public.

It can also be used for cleanups like c96ca2a, which was not merged in. This update applies the following linking convention, which we also have in the Docs. Outside contributions make these cleanups a breeze while preserving the great specific files referenced by the author.

stellar-protocol/core/README.md

Lines 232 to 235 in 8912a80

	- If your CAP requires images or other supporting files, they should be included in a sub-directory
	of the `contents` folder for that CAP, such as `contents/cap-TBD/`. Links
	should be relative, for example a link to an image from your CAP would be
	`../contents/cap-TBD/image.png`.

Next is the main improvement, with changes based on the implementation. This stops the CAP from aging and diverging from Core, like what misled me into many hours of wasted time concluding the final discrepancy. It's not a place to renegotiate the intent of an Accepted proposal, just to clearly state real specs.

The CAPs were my starting place for understanding Stellar so many years ago, and I'm not the only one who looks to them for inspiration and explanation. The incredible Tupui recently released a frontend reader that organizes and formats the protocol improvements by fetching this repository. I would like to see it incorporated into the Docs, which refer to the CAPs voluminously.

I can't tell you how many times I've searched specifically for the GitHub links here to draft a proposal or explain an idea. They've been the basis of many compliance explanations, and I want to see them keep improving over time. There are also future concepts like stellar/stellar-docs#1545 (comment), which the SDF's own documentation expert Elliot recommended I record here.

A network reflects the infrastructure it's built on. And I want Stellar to be as perfect as possible. By working together on these specs, we give newcomers clear and accurate direction to deploy and improve the protocol.

I'm sorry for the mistakes I've made, like this or adding new content in a merge commit. I believe very much in what we can do here since most of the implementation authors in Core are the CAP owners anyway. There are only a few exceptions like 29, where it might take a little more analysis from contributors.

Lastly, I make a correctness change since consensus comes from an SCP quorum rather than a simple majority for liveness approval. I hope that we can come to quorum on a reasonable path forward where we communicate about proposed changes and issues so that everyone ends up better. The community wants to help and spread protocol adoption if you will only let us be part of the upgrades. We can only provide big leaps in the future if we're allowed to merge tiny interactions to get our footing.

[Copilot]

Pull request overview

Modernizes CAP finalization and amendment policy in the central CAP process documentation.

Changes:

• Replaces validator-majority terminology with SCP consensus terminology.
• Broadens permitted updates to Final CAPs.
• Corrects Markdown table spacing.

Suppressed comments (1)

core/README.md:329

• This repeats the ambiguous finalization condition above: SCP reaches consensus on and externalizes a ledger value containing the protocol-version upgrade; it does not accept the implementation itself. Use that concrete network event here so the workflow states exactly when the CAP moves to Final.

the protocol version that the implementation targets. From there, once an SCP quorum of validators
on the network has accepted the implementation, it will move to **Final**.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[leighmcculloch]

There are multiple quorums on the network, and it's marked final when the tier 1 validators agree, so we should probably specify that here.