Quality Control for Protocol&API Changes

We want ideas on protocol changes to be both iterated on rapidly and be adhering to the highest standards of the quality control. This is a difficult balance to achieve but this proposal is trying to do exactly that. Please read how this proposal addresses quality control goals and feel free to suggest adjustments or alternatives to the solutions.

We want to iterate on protocol changes rapidly because we believe in blockchain to be an ever-evolving technology. No whitepaper can capture all the current and future ideas, so we accept protocol design to be a living organism – once it stops adapting it dies and users will gradually move to other blockchains that capture ideas that the old blockchain did not.

We want to adhere to the highest standards with protocol changes for two reasons:

  • We don’t want to compromise our technological values: safety, user-friendliness, developer-friendliness, performance, scalability, decentralization, not needing to trust anybody specifically. In certain cases trade-offs can be made, but this needs to be explicitly discussed and not swept under the rug;
  • We don’t want to engineer ourselves into a corner, i.e. we don’t want to make a protocol change that will either constrain our further development impeding our velocity, or it will introduce undesirable things that we would want to remove but it will be either extremely costly/laborious or impossible to remove.

The ability of the blockchain to evolve rapidly while not compromising on quality determines its survivability in a long-run.

This means that any protocol change proposal should have the following qualities:

  • It should be meticulous and exhaustive to make sure there are no uncertainties, double-interpretations, and gaps;
  • It should be focused both on immediate and distant effects. Effects can be distant in two ways:
    • Time – things that happen way ahead in the future. In turn, they can be of two sub-types:
      • Delayed effects – effects that happen because enough time has passed. E.g. a blockchain has accumulated an absurdly large state and is now hitting hardware constraints;
      • New context – effects that happen because the context changed or a new context emerged;
    • Dependencies – things that happen through a number of transitive dependencies. E.g. a blockchain changes how it charges for the state usage → contract developers change their contracts → … → users have transactions failing all the time, because they do not use the contracts correctly;

Working with the Risks

It is however, not possible to have a perfect foresight, but we can have a system while trying to have one.

There are four types of risks:

  • Known knowns. We know about an existence of a specific risk, and we have full understanding of it. E.g. we know that state staking can “lock” the contract if there is not enough balance to perform state changes, but we also know that anyone can send tokens to it to unlock it, so most likely such locking of a contract does not create surface of attack for malicious actors, since it is trivial to undo;
  • Known unknowns. We know about the existence of the specific risk, but it is not well-understood and all side-effects are hard to account for. E.g. we know that state staking would require attaching tokens to function calls to offset the difference in state size, however we don’t have full understanding on how much of inconvenience to the users it is going to be and how much more complex this will make the contracts;
  • Unknown unknowns. Risks that exist but we did not think of;
  • Unknown knowns. We know about the risk but we refuse to acknowledge it, e.g. because we like the proposal and have a personal attachment to it, thus we avoid criticising it. Since it is often hard to criticize our own brain-child an explicit process needs to be in place to surface all potential unknown knowns. E.g. author knows that the proposal will open certain hypothetical angles of attack or degrade the experience but does not emphasize and justify it because they think it either dilutes the message or is a side-track;

Many design discussions start with all four kinds of risks, but for protocol proposal to be accepted we want to be left only with known knowns. There will be processes to achieve it:

  • Known unknowns → known knowns. Once we noticed that there is a risk whose extend we don’t fully understand, the author of the proposal and its proponents will be required to work on clarifying it until it becomes a known known;
  • Unknown unknowns & unknown knowns → known unknowns. Since these risks are not written down anywhere explicitly, the only way to uncover them is to “fish” for them (similarly to how a red team would try to uncover security risks by playing an opposing force). There will be two methods to do it:
    • Willing participants of the discussion will play an opposing force, whether voluntarily or they will be nominated and even funded by stakeholders like NEAR Foundation to construct scenarios in which the proposed change can compromise our technological values or velocity, in the process uncovering unknown risks;
    • There will be standard scenarios that will be agreed ahead of time by the community. Each proposal would have to include a walk-through for each standard scenario before it is submitted. E.g. give a detailed example of a cross-contract transaction that contains merged promises, callbacks, and a contract factory. Explain how the proposed change will affect each receipt, including refunds in a high detail. How will values of each field in each receipt change with the proposed change?

Roles, Ownership, and Accountability

We want the process to be democratic and inclusive, but we also want to have accountability. This means the proposal needs to have owners – people who carry the burden of proving “beyond reasonable doubt” that the proposed design does what it claims to do and that it does not negatively affect our technological values or impede our future velocity. The owners of the proposal are the author and its potential proponents. It is their responsibility to prove that the proposal works, and it is not responsibility of others to prove that it does not work. The default decision for any protocol change should be a No.

We also need admins who will decide when the proposal is accepted or rejected. In a long run, this will be a council elected by the stakeholders, which most likely will be only the validators and people that validators consider as an authority or experts, since validators have an ultimate control of deciding which protocol version to run on their machines. However, at the beginning as a way to bootstrap this process admins will be a preselected group of people. Admins will also be moderating the discussion once the proposal is submitted to make sure the discussion is civil and focused.

As explained above, there will be opponents and people nominated to play the opposing force and try to do the following:

  • Find gaps, double-interpretations, inconsistencies;
  • Suggest better alternatives and ask author and proponents to justify why alternative is not better;
  • Find angles of attack and other kinds of abuse;
  • If the proposed design makes trade-offs with our technological values and velocity, then argue why these trade-offs are not justifiable;

Additionally, there are people who work on different parts of the protocol and have deep understanding of it. It makes sense to invite them into the discussion and when judgement call is needed (e.g. when the trade-offs are present) ask them to weigh-in.

To summarize, the roles are:

  • The author.
    • Election process: Self-elected by submitting a proposal;
    • Responsibilities: Submit the proposal following the format, address the comments from the community until proposal is accepted;
  • The admins.
    • Election process: Initially pre-selected, but eventually elected by the validators. They are the same for all proposals;
    • Responsibilities: Moderate the discussion, make the final accept/reject decision, enforce the timeline, recognize/invite subject matter experts;
  • The incentivized auditors.
    • Election process: Funded by stakeholders, e.g. NEAR Foundation;
    • Responsibilities: scrutinize the proposal, the incentive model might be paying per finding;
  • The subject matter experts (SMEs).
    • Election process: recognized or nominated by admins either for all proposals or for specific proposals;
    • Responsibilities: Present their take on the specific proposal;
  • The affected projects.
    • Election process: The author of the proposal needs to list all major projects that will be affected by the change in the proposal. Admins then invite representatives from major projects for the discussion;
    • Responsibilities: Explain in detail how they will be affected if the proposal is implemented;
  • The community members.
    • Election process: none, anyone can join the discussion as proponent, opponent, or non-incentivized auditor;
    • Responsibilities: Add clarity to the discussion, surface issues, present alternative points of view;
  • The implementers.
    • Election process: self-elected by being one of the owners of a client implementation for our protocol;
    • Responsibilities: implement the change, if accepted. Very likely, they will be in sync with the validators and other stakeholders so they will have an interest in implementing the change;

Note, some roles might overlap, e.g. the implementers will also likely be the SMEs. However, certain roles should be separate to avoid conflicts of interest, e.g. the author should be separate from the admins and the auditors. If the admins want to submit a proposal themselves then they need to recuse themselves from the process.

The Proposal Process

We don’t want proposals to be stuck in a limbo state of always being in progress, therefore we commit to always either accept or reject the proposal.

It can be rejected for the following reasons:

  • No-op proposal. It does not improve any of our values or velocity;
  • Unjustifiable trade-offs. It makes the trade-offs in technological values or velocity that are not justifiable. Note, that if proposal is too difficult to implement or it adds too much architectural complexity it can be rejected as impeding future velocity too much;
  • Not ready. The proposal does not satisfy the required format, e.g. it does not explain all standard scenarios. Also, we don’t want the proposal discussion the be the place where the process is created, and so the authors and the proponents should come with a sufficiently ready proposal and do not expect to iterate on it with the community. They can however iterate on the proposal with the community in other open forums outside the official proposal process. Therefore, if proposal is submitted but community keeps finding gaps in the proposal, e.g. like reasonable alternatives, adversarial angles or gaps in the design, then even if author and proponents continue explaining them, after some time proposal runs out of time and is rejected;
  • Duplicate. A similar proposal has been already submitted and the author did not explain the difference sufficiently;
  • Spam. Someone is trying to get their proposal through by spamming;

The time-line of the proposal is the following:

  1. Initial phase (1 week at most)
    1.1. The process is initiated by an author submitting it;
    1.2. The proposal is examined by the admins. If it deviates from the format the proposal is rejected and allowed to be resubmitted in 1 month;
    1.3. Admins invite SMEs (some SMEs recognized by admins might join voluntarily) and representatives from the affected projects;
    1.4. (Optional) The stakeholders hire the auditors;
  2. Discussion phase (2 months at most)
    2.1. SMEs and affected projects weigh-in;
    2.2. Auditors respond with their findings;
    2.3. Other community members join the discussion;
    2.4. Once the proposal is at the point where it is exhaustive, non-ambiguous, highly-detailed, and all findings are addressed and incorporated into the proposal, the admins make a decision on accepting or rejecting it;
    2.5. If proposal runs out of time it is rejected;
  3. Implementation phase
    3.1. Admins invite representatives from the affected projects and the implementers to discuss the timeline of rolling out the feature. Once the timeline is agreed on, the remaining process is delegated to the implementers.

The Format

Below is the format that every proposal needs to follow.


Any background that readers who are not SMEs need to know to understand the proposal, including the motivation, and the alternatives.


Explanation on why the proposed change is needed. It needs to address our technological values or improve velocity. If the proposal is doing trade-offs they need to be explicitly outlined and justified.

Affected major projects

List of affected major projects and the ways in which they will be affected.


A thorough design, which should include:

  • Any new data-structures or modifications to existing ones;
  • Any new mathematical formulas and algorithms which should be unambiguously formalized;
  • Any API changes;
  • Thorough explanations of the migration schemes and how exactly they should be performed;

Standard scenarios

Author should take each of the standard scenarios and describe unambiguously, in high-detail how the proposed change will affect it. This section should be treated as seriously as the design section, because it allows to uncover all the complex corner cases and give a complete picture to the readers.


All side-effects that this change will create for our technological values and velocity, including: developer-experience, safety, decentralization, etc.


A list of all alternatives that author is aware of with unambiguous explanation on why the proposed design is better.


The author should imagine the most likely scenarios in which this design can fail once it is accepted and implemented. The author then should elaborate on how exactly it will happen and what will be the consequences.

(Optional) Implementation details

Any hints on how this change can be implemented.

Discussion Place

It is important that there is a place where free-form public ideation can happen without any constraints. @mikedotexe and @Bowen will discuss what we should recommend as a place for ideation and will ink it in https://github.com/near/NEPs/blob/master/README.md.

Once it is ready to be submitted, the author will create a PR in https://github.com/near/NEPs that creates a file in proposals folder that follows the above Format. PR should also include the necessary modification to the protocol specification in specs folder.

Once the proposal is approved the admins will approve and merge the PR.

This achieves the following goals:

  • The history of the discussion is permanently preserved through git comments;
  • If proposal is accepted, it is automatically applied to the documentation;
  • If documentation is lacking in this area, we are creating it by making the author of the proposal write it;
  • Github projects can be used to track the progress of the proposal in the Kanban board.

Adjustments to the Process

In some cases critical bugs need to be fixed quickly without being blocked by the process, in that case the proposal needs to be written retroactively for archival reasons. Note, that this should only be done in very rare cases, since even the bug fixes themselves can introduce bugs and the entire point of the process is to guard from these kind of bugs.

Also, in some cases bugs need to be fixed discreetly. In that case the proposal process needs to be done privately and the proposal should be made public only once the change has propagated through the network.

The decision to allow certain proposals to be retroactive or private should be made and coordinated by the admins.

Appendix A. Initial Standard Scenarios

A. If the proposal touches anything related to the receipts, including their structure, how fields are interpreted, their behavior, then the proposal needs to include detailed explanation on how the following scenario will be affected:

  • Alice signs a transaction that calls contract Bob;
  • Bob calls contract Carol and Dave, joins their promises and attaches a callback to contract Erin;
  • Erin then deploys a contract to account Frank;
  • Describe also how all refunds and data receipts will be changed with your proposal;

B. If the proposal touches anything related to state, including introducing new forms of state. Then the project needs to explain the following:

  • How the dynamic resharding and resharding in general will be affected;
  • How the creation of state witness will be affected. Will there be new state witnesses? What will be the difficulties with distributing, creating and validating them? Can someone fake a state-witness to slash a validator?
  • Will it be possible to manipulate the structure of the state structure? Please explain exactly how?
  • Please explain if anything will change with regards to the light client and validation of the state;
  • Anything will change in terms of how much data we store on the disk

C. If the proposal touches anything related to the host functions, including modifying, adding new, or changing the meaning of the host functions.

  • Provide a full-specification of the function independent on the implementation;
  • Explain how we can guarantee this host function to be sand-boxed;
  • Explain how we can have a precise deterministic fee estimation mechanism for it;
  • Explain how the fees are going to differ on different platforms;
  • Will this function be eventually unused? If yes, then what is the rationale for including it?

Append B. Examples of the Proposals

We will take a couple of most recent WIP proposals and polish them until they adhere to the format. Once it is done, we will link them here.


Would the trade-offs clear until the Design section?

1 Like

Does this apply to every protocol change? There are some protocol changes that are very limited in scope or are done for the sake of fixing some existing bugs.


Fixes of bugs can create bugs of their own, so we should treat them seriously too. If some fix is straightforward and does not touch many components then this process automatically be fast for it. For example, if it is an adjustment of some constant, then very likely most of the standard scenarios are not going to be triggered, no one will poke holes in the proposal and it will likely be accepted within a couple of weeks or several days. On the other hand, if someone manages to poke a hole in it then it is good that we had a process to catch it. Also, unlike other code changes, protocol changes do not override the old code in the codebase, which means our code is going to be littered with conditional compilation clauses that will persist indefinitely. It would be good to have an explanation for each of them together with Background, Motivation, Alternatives, so that we don’t spend time doing archeology 1 year later.

1 Like

If not then admins will require from the author to clarify them in the Design section.

Well my point is that if there is some critical bug that can cause the entire network to go down or cause users to lose funds it probably shouldn’t go through this process which will publicly disclose the issue.


Makes sense. I have modified the Discussion Place section and added Adjustments to the Process section.

Some observations, comparing this with Rust model.

A, “admins moderate discussion”. Three are two kinds of moderation – one shepherding technical discussion in the most productive direction, the other is the usual internet moderation – telling grown up people that using kindergarten language is not OK, fighting spam, etc. In Rust, moderators of the second kind are a separate team, to avoid conflict of interests. Moderators should protect project members from participants, and vice verse.

B, In Rust, “decision phase” is very clear, and separate from the discussion. It follows two-phase protocol – after the informal consensus as to what the decisions should be is formed among the admins, the YES/NO question is posted, and the admints vote on it. Voting takes place for at least two weeks. This makes it clear when proposal transitions from brainstorm to decision making.

C, one drawback of RFC process is that, when RFC accumulates enough comments to make it difficult to read all the comments, comments become repated. I.e., three different persons would post “did you think of X?” questions. Rust sometimes uses “adversary collaboration” style of documents – a shared doc where proponents and opponents of a solution list there arguments in nested list style:

* the performance will drop considerably under the `foo` condition
  * but we observed that `foo` condition empirically never happens
    * one can force `foo` by doing `baz`

D, Rust’s RFCs have “postponed” outcome. Even if the idea is good, it might be not as impact as other (completely orthogonal) proposals. Accepted RFCs has opportunity cost, so it’s fine to reject some great (but not crucial) RFCs due to developers bandwidth reasons.

E, Rust historically doesn’t deal to good with separation between “finding solution to the problem” and “making decisions” process. RFC is usually a specific solution to the problem. People tend to jump to the solution (thinking fast and slow terminology) before thoroughly considering the problem and the whole space of the solutions. IE, an ideal RFC process is 4 phase:

  • Phase 1 identifies the problem and ensures that that’s the important problem to solve now.
  • Phase 2 brainstorms the set of possible solution
  • Phase 3 picks the most promising solution and refines it to iron out the four risks
  • Phase 4 makes a decision on the specific solution.

I like the explicit split between problem and solution. We frequently leading with solution in the discussions as well.

I think it’s important from both important from prioritization perspective (are solving the most pressing problems vs just discussing them and solving other problems?) and concluding conversations even when there is not enough information to move to next stage (in search of perfect solution quarters can pass)

Currently we know a number of problems listed in various places across this forum (might be good to collect them into a single place in NEP repo in prioritized order?) and at the same time many various discussions have happened on potential solutions without any proposals.

How would we in general ensure that team is working on the most important problems? How do we ensure discussions conclude and transition to proposals stage?

1 Like

I also feel the pain of not having all problems tracked in the same place and that part of the reason why I started this document, though google doc is definitely not a long term solution.

1 Like

@matklad Are you saying that it is implied that once proposal is accepted the development starts? Is this why proposal is rejected if there is no bandwidth?

We want ideation phase to be as unconstrained as possible to allow free flow of new ideas, but we also don’t want ideas to be stuck in ideation phase indefinitely or be scattered around our communication channels. Unfortunately, we cannot prevent community from discussing ideas wherever they want and processes can be detrimental to free-form ideation. Therefore I suggest the following:

  • We advise community to do free-form ideation in one place without forcing it. As an example, our Open Discussions meetings will be recording ideations in that place. @Bowen , @matklad where do you think this place should be?
  • We have people responsible for cataloging all ideations that we are aware of. This does not force community into a process, but it allows ideas to be less scattered and it allows us to have a full picture of the ideas being currently discussed;
  • It takes a lot of effort to convert an idea to a well-thought-out proposal; sometimes, it requires orders of magnitude more effort. It is natural that community members will tend to discuss an idea without filling all the necessary gaps required by the formal proposal process. We would need to either incentivize people to do it (via rewards) or to have people working for NEAR organization doing it as part of their role.

I am going to modify the above post to include adjustments to the process to address the above.

I think this forum is a good place for that.

1 Like

That’s roughly the idea: after the RFC is accepted, it is expected that it’ll be implemented “soon”. Many RFCs actually have (unmerged) implementations by the time they are accepted. It is more of a result of a converse observation: if the implementation work does not start when the RFC is merged, the RFC usually ends up in such “accepted, but unimplemented” state for years.

I think this will be the difference between NEAR and Rust proposals: accepting NEAR proposal does not imply immediate start of the implementation phase. In a long-term, reference implementations of the client and the changes to the protocol are going to be done by different (potentially overlapping) groups of people, similarly to how it is done on Ethereum. So acceptance of the proposal and its implementation can only be loosely coordinated, since they cannot force each other do it.

It is similar to how triaging of new issues works in Agile – triaged issue can be rejected (closed immediately), scheduled for the next cycle or put into the ice-box. Having a proposal clarified to the point where it is rejected or accepted, but not implementing it immediately is an analog of an ice-box. So I don’t think it is a sign of a dysfunction that there are “accepted, but unimplemented” proposals that stay like this for years, since even regular issues (that are smaller and therefore more flexible) can stay in ice-box for months if not years.

Also, it will be operationally impossible to guarantee the start of the implementation even today. We want any proposal submitted by the community to be rejected or accepted within a fixed timeframe, however the team that is working on the protocol implementation has its own well-thought through priorities and the roadmap, and so they cannot promise to immediately de-prioritize things that they are doing and start working on some proposal that just got accepted.

I’m agree with @matklad - there should be at least a reference client implementation for a proposal to get fully accepted.

What we (and others in the industry) have experienced over and over again is that when spec is starting to get implemented - there are many more practical issues surface. Ideally spec should cover those as well, such that other client implementation don’t need to reinvent it.

Obviously other clients may have other practical issues like which library to use, etc. But crypto primitives is great example of using specific library in reference client leads to actually specific crypto formula to become part of protocol and later other clients would need to be compatible with that.

Also generally, if the proposal is not getting implemented - by the time people get to it, it might get outdated by others.

In Ethereum it depends on the author of EIP, but many EIPs were authored and implemented by the same people. At the same time EIPs that are don’t have implementation may live in limbo state for years.

I would create a new state “Staging” for NEPs that are ready for implementation.
E.g. next stages of proposal similar to Agile process can be used:

  • “Ice box” are “problems” to solve.
  • “Proposed” are actively discussed proposal.
  • “Staging” - the solution for the problem was discussed and main unknowns were discovered and figured out. This is can be considered “accepted” proposal but from perspective of NEP it’s in Staging.
  • “In progress” - there are implementations in progress
  • “Testing” - it’s on BetaNet (nightly)
  • “Done” - its’ on TestNet and scheduled for mainnet release. Can be reverted if issues were discovered at this stage back to “Testing” or “In progress” even.
  • “Rejected” - can go from proposed or staging. Things can change later and proposals in staging can actually get rejected later with less likelihood mainly in case of compatibility or new issues discovered.

We can have this in NEPs github repo in Kanban board to visualize the state and also allow people to contribute implementations of “Staged” proposals or discuss problems in the “Ice box”.

What do you think @nearmax ?


Bowen and I are talking about this now and wondering if we can get a more solid understanding of when a proposal is decided to be merged. Perhaps it’s always going to boil down to subjectivity, but some guidelines might be helpful here.

1 Like

I’d like to add some color to what is not discussed at length in the original post: the processing of releasing a protocol change once it is implemented. I think we are currently not doing a good job of informing the relevant stakeholders of what protocol changes a new release contains and how protocol features are stabilized. Right now that process is entirely bottlenecked on me, which is highly suboptimal and also sometimes leads to miscommunications and mistakes in releases.

Thinking about how we could improve this process, I have the following ideas:

  • Having a centralized place to track the list of protocol changes that go into the next release. This way everyone has visibility into what is going to be released next. More concretely, I suggest that we add a CHANGELOG.md in nearcore to document at least the protocol changes in each release as well as the upcoming protocol changes once a new protocol feature is merged.
  • Consider having a more formal process to consolidate new protocol features. Rust uses the RFC process to vote on whether a nightly feature should be stabilized and we could use a similar process. One concern here, however, is whether this process may be too heavy for us and whether it will slow down the speed of development.

Feel free to suggest alternatives on how we could make the release process of protocol features better! @matklad @nearmax

1 Like

CHANGELOG.md sounds sufficient and light-weight enough for our needs.

Not exactly. The RFC is used when designing and implementing the feature. For stabilizaion, the process goes via stabilization report and FCP.

That is, someone first writes down what exactly is being stabilized as a comment on GitHub. The value here is that, during development, a lot of alternatives are often tried, and people might get lost as to what’s the current state is.

Then, the relevant team votes on the FCP for this report. The value here is to have a very specific decision point.

For us, a changelog sounds like a good first step. It probably might be a good idea to include “stabilization reports” into changelog. That is, rather than using a pointer ("we stabilized erc_recover"), we dereference it: “new host function is added: erc_recover. It has the following signature … and does the following operation … . The cost of this function is computed using this formula … . The starting costs are …”.


FYI, we are going to finalize the entire process and link all the guidelines and resources from the Developer Dashboard, once we have the first version launched, as mentioned here.

I think it is a good idea to have a Github Kanban board for the proposals of all kinds. It will also help with planning of OKRs.

The proposal should be merged once it enters the Staging phase. We will clarify how moving to the Staging phase will be triggered, once we have the first iteration of the Developer Dashboard.

Some more thoughts on the constraints:

Half-baked ideas

Proposals can have a very varying degree of readiness, and proposers/stakeholders can be only mildly interested to work towards its completion (i.e. they are just throwing an idea). We cannot ask NEAR Inc engineers to take over and drive such proposals to completion, since it will consume internal engineering resources that they have planned to spend on tasks defined in OKRs, and since we have lots of dependencies between the teams, we cannot simply adjust OKRs of one team to accommodate a work on a proposal (which often takes weeks just for design discussion). Therefore, we need to have an option to reject such proposal as “Not Ready” and move to “Ice Box” (as suggested by @illia ).

Decision vs Execution phases

There is a natural separation between Decision and Execution for proposals in blockchain, in general (see e.g. separation between Snapshot and Gnosis Safe). Execution cannot be forced by the Decision, because they are done by different parties and have different processes, so in the linked post Decision is even called Signal – emphasizing that it only signals that the community wants it. While we can bundle the entire end-to-end process from idea creation to implementation in one place (NEPs repo, Github project board, etc) to create some sense of accountability in a hope that it can prevent proposals from getting stuck in a limbo, I suggest, we acknowledge that limbo is in an inherent normal state for the proposals, and like @illia suggested allow proposals to stay in Staging indefinitely. There is a benefit to having some proposals sit in the Staging – sometimes a better idea comes around, ecosystem changes and makes it irrelevant, or business context changes. Therefore, I don’t think it is a good idea to require proposals to have a reference implementation, because reference implementation is an attempt to conceive Execution during the Decision phase and circumvent the natural order of ideas being stuck in Staging.

Also, there are big technical obstacles in requiring reference implementation in the proposals. Lots of protocol proposals can have a very brief specification in terms of how they are expressed but very invasive and scattered implementation. The analogy is that if we were to rewrite a declarative program into an imperative language it would become orders of magnitude more complex. Just because something is easy to declare in a specification does not mean it can be implemented easily imperatively. The implementation will also vary greatly on the client language, programming patterns that are used in the code, and used frameworks and libraries. I think it is sufficient if we require proposals to have a non-ambiguous declarative specification.

Also, by requiring proposals to have a reference implementation we are undermining the core value of having multiple implementations of the protocol. We want to avoid a coordinated error. Having not only the declaration of the idea, but its implementation in the proposal will create a space for injecting coordinated errors into all protocol implementations.

Perhaps, we can allow proposals to have “reference implementation” in pseudocode or Python if it helps resolving ambiguity, similarly to how EIPs are doing it.