Move to Protocol Spec

[bw-solana]

I have been working on a draft of a full Solana Protocol Specification. I would like feedback on changing the SIMD process so that the primary artifact for a protocol change is a PR against the specification.

The existing process has produced many useful proposals, but it has also exposed several recurring problems:

1. Many proposals change existing protocol behavior, but there is often no way to reference that behavior outside of linking to a client implementation or defining the current behavior inline in the SIMD. This leads to the same behavior being defined repeatedly, sometimes in slightly different ways.
2. It is often difficult to determine whether a proposal has addressed every affected part of the protocol.
3. Because SIMDs are standalone documents, they do not inherit a common structure or make it easy to follow the conventions established by related proposals.
4. The absence of a consolidated specification makes it difficult for newcomers to understand how the protocol is intended to work and forces them to reverse engineer that behavior from client implementations.

The proposed process makes the protocol change itself the proposal.

Proposed process

Ideas would still begin in SIMD Discussions. This is where an idea receives an initial concept ACK and where we discuss whether it is worth specifying in detail.

Once an idea is ready to become a concrete proposal, its author would open a pull request against the protocol specification. That pull request would describe the complete normative change, including byte layouts, state transitions, error behavior, limits, feature interactions, and any other details needed for independent implementations to agree.

Each proposed change would retain a stable SIMD identifier, assigned and used in much the same way as it is today. The identifier would follow the proposal through discussion, specification review, implementation, and activation. After the change merges, the identifier would remain available as a way to reference that particular protocol change.

The substantive SIMD approval process would also remain largely the same. The same technical review, relevant contributor ACKs, and governance approval would still be required.

The specification is organized primarily by horizontal protocol domains: transactions, runtime, consensus, networking, ledger format, programs, and so on. A proposal should update every affected domain. Large features that cut across several domains may also receive a cohesive description in a dedicated "Features" section so that the feature can be understood as a whole.

The specification describes the protocol currently active on Mainnet. It is versioned by Mainnet epoch. A specification pull request does not merge just because the design has been accepted, implemented, or activated on another cluster. A normative protocol change merges when that change becomes active on Mainnet.

Errata and clarifications are different. A correction that makes the specification accurately describe behavior already active on Mainnet may merge without a feature activation.

Testnet, devnet, implementation, and rollout status can be recorded in comments on the pull request. Issues that require changes to the proposed specification would be reflected in new commits to the PR.

In short:

Stage	Proposed representation
Idea and concept ACK	SIMD Discussion
Stable change identifier	SIMD identifier assigned similarly to today
Draft protocol change	Draft specification PR
Proposal review	Specification PR review
Accepted for implementation	Open PR marked as accepted
Governance approval, when required	Link and status recorded on the PR
Testnet or devnet deployment	PR comment or linked tracking issue
Mainnet activation	Merge the specification PR
Final protocol state	Published specification for that Mainnet epoch

This proposal is mainly about standard protocol changes. Meta proposals concerning governance or the process itself still make sense as standalone documents.

Why make this change?

A protocol proposal should focus on what an implementation must do differently. Creating the proposal as a specification diff makes this explicit during review. It also makes omissions easier to find. If a change affects transaction validation, runtime execution, fees, and consensus, reviewers can see whether all four areas were updated.

It also keeps the current protocol in one place. Implementers should not need to reconstruct Mainnet behavior by combining a base implementation, years of SIMDs, feature-gate history, and implementation-specific behavior.

SIMD discussions and links would still preserve the motivation, alternatives, and design history. The specification would describe the resulting protocol.

Migration

There will be a transition period for existing SIMDs that are not yet active on Mainnet.

I propose that we:

1. Catalogue every SIMD in Draft, Review, Accepted, or Implemented status that is not active on Mainnet.
2. Migrate SIMDs in Draft or Review to specification PRs and continue their review under the new process.
3. Create specification PRs for SIMDs that have already been accepted or implemented.
4. Preserve the existing SIMD identifier and link each specification PR to the original SIMD, discussion, and implementation work.
5. Keep each specification PR open until Mainnet activation.
6. Merge the specification PR as part of the Mainnet activation process.

The baseline specification is intended to capture SIMDs already active on Mainnet. Any omissions or inaccuracies in that baseline would be handled as specification errata.

Following adoption of this process, all new protocol proposals would use the specification-PR process.

Dependencies between proposals

Dependencies can be handled in much the same way as dependencies between code changes.

If proposal B depends on proposal A, B can be developed on top of A's specification branch or diff. The dependency should be stated clearly in the PR. Once A merges, B rebases onto the updated specification.

This allows dependent proposals to be reviewed and implemented without pretending that their prerequisites are already part of the Mainnet protocol. It also makes dependencies, conflicts, and incompatibilities more explicit.

Representing proposal status

The main GitHub-state question I have is how to represent a proposal whose language has been accepted for implementation but which is not yet active on Mainnet.

The beginning and end are reasonably clear:

• A concept ACK happens in SIMD Discussions.
• A merged specification PR means the change is finalized and active on Mainnet.

For the intermediate state, I suggest keeping the PR open, applying an "accepted for implementation" label, and adding a maintainer comment identifying the exact approved commit. Implementers could work against that commit. Any subsequent spec change would require renewed review before the proposal could be considered accepted again.

Where governance approval is required, a separate label and a link to the governance decision could record that ACK without merging the protocol change early.

This preserves the useful states in the current SIMD lifecycle, while making merge status mean something unambiguous—the change is part of the active Mainnet protocol.

Next Steps

Collect feedback on this general approach and discuss any concerns.

If there is broad agreement on the direction, next steps would be:

1. concrete update to SIMD-0001 defining repository ownership, review authority, labels, identifier assignment, migration, etc.
2. agreement on the baseline spec for cutting over, where to host it, etc.

[alnoki]

Understood on how proposal diff dependencies can be managed using git-style version control, but what about in-protocol dependencies that are currently detected using implementation-specific details (e.g. rust-analyzer failures in the simplest form)?

Is there anyway to incorporate some kind of specification dependency chart in the RFC 2119-style spec draft?

Asking because while I think that spec-driven development is overall the right option, I suspect that updates to text files might miss some of the interplay caught by client implementations

[bw-solana]

you bring up some good points. In reality, I think it's tough to propose a spec change w/ high confidence without halfway implementing some PoC of the thing.

I expect escapes wrt proposal collisions to be caught quickly during implementation phase and fed back into the spec definition.

we could do something more sophisticated with cross-references and dependency charts, but I lean towards starting simple and seeing where we're experiencing the most pain

[jacobcreech]

Each proposed change would retain a stable SIMD identifier, assigned and used in much the same way as it is today. The identifier would follow the proposal through discussion, specification review, implementation, and activation

IMO we should not assign a SIMD identifier until the SIMD has graduated from discussion to spec review(Github discussion to Pull Request). Are you interested in having this completely decoupled from the issue number?

Accepted for implementation

If we're keeping these open until Mainnet activation, will each additional change to the protocol spec as new unknown behavior found in testing be an additional acceptance as a commit on top of the PR? Would we update the status from Accepted for implementation back to Proposal review during the additional approval cycles?

agreement on the baseline spec for cutting over, where to host it, etc.

If we're making PRs to the spec in SIMDs, imo this should live here.

[bw-solana]

IMO we should not assign a SIMD identifier until the SIMD has graduated from discussion to spec review(Github discussion to Pull Request)

I agree. I was sloppy with the "proposed" wording, but meant when actual PR is opened

Are you interested in having this completely decoupled from the issue number?

No, I'm fine w/ continuing to use the PR# as the SIMD identifier

If we're keeping these open until Mainnet activation, will each additional change to the protocol spec as new unknown behavior found in testing be an additional acceptance as a commit on top of the PR?

Not sure I fully understand what you're asking. Are you basically asking about how to handle integration when two unmerged proposals interact with each other?

Would we update the status from Accepted for implementation back to Proposal review during the additional approval cycles?

I'm not sure what the right thing to do here is... this is one of the things I least like with the proposal.

I want it to be clear what state something is in, but also want the process to be low touch such that state remains accurate.

imo this should live here

agree

[jacobcreech]

Not sure I fully understand what you're asking. Are you basically asking about how to handle integration when two unmerged proposals interact with each other?

It's common that we amend the proposals in a subsequent PR. Your comment

I'm not sure what the right thing to do here is... this is one of the things I least like with the proposal.

I want it to be clear what state something is in, but also want the process to be low touch such that state remains accurate.

Answers it. Let's just set up simd bot to update for amended review on a commit after the original acceptance.

[dimandotsol]

I absolutely love this.

I have one small suggestion. Since there are quite a few open SIMDs, it might be difficult for someone new to the specification to understand what changes are already planned.

I suggest adding a list of SIMDs that are expected to modify each section at the beginning of that section, and keeping it up to date - adding SIMDs once they are accepted and removing them once they are activated.

[bw-solana]

I like this idea in theory. I'm worried about keeping things up to date and the amount of churn to the spec.

Let me think about this a little more... I wonder if we could have some spec.next branch with the in-progress SIMDs or something