Feature addition policy

[arnetheduck]

Each addition to the beacon API carries a significant implementation and maintenance cost, since in general, there's an expectation that beacon nodes actually will implement the API as specified.

As such, we should consider the requirements for any new additions to the common API so as to manage expectations with users and keep implementation burden reasonable.

A couple of ways this can be done:

• minimal approval requirements - ie at least N clients commit to implementing the API by approving it
• minimal released implementations - ie features are not merged until a client release exists supporting the feature (to ensure that we don't add features that are unimplementable or that nobody actually is willing to implement)
• explicitly experimental / extension API (to manage user expectations around API stability)
  • this is similar to how the engine API defines a "required" of the more general JSON-RPC API - modules can creatively be used for "special-interest" features such as distributed validator middleware etc

While many features are obvious (ie hard-fork related updates to BN/VC interface), others are more nuanced - it is trivial to keep adding things to a standard, but much harder to remove or change things.

In general, it's fairly cheap to keep things in PR until they pass minimal QA bars such as above - the PR serves as implementation guide for early adopters avoiding fragmentation while at the same time making it easy for implementers to track what is "usually" supported by clients and what is not.

[mcdee]

The original beacon API was designed to provide an interface to the data structures in the spec, along with some minor additions where they were required to avoid a lot of back-and-forth with multiple API calls to obtain information, or where the required information was held in larger data structures such as state.

I tend to agree that we need to try to limit the scope of the changes to the API such that they don't expand too far beyond this remit. Requiring beacon nodes to do work that can be done outside of the beacon nodes seems to be overloading the API, and adding more methods makes it harder for new entrants to implement either a client or a server.

An alternative is to consider putting such APIs in their own namespace and their own repo. The MEV-boost-related API calls are a decent example of this, where there is still input from the client teams and they work on much the same principles, but they are their own entity. They can use separate top-level endpoints to provide separation, and client teams won't have the same pressure to build and maintain them if they do not have the time or desire to do so.

[rolfyone]

To me, two great examples are

• mev
• lightclient
  where we're adding api calls specifically for basically non beacon-apis functionality.

To varying degrees we've got a split of the amount of implementation on both, and it's not really documented as to the level of support for various things (even the OG rest api had certain endpoints not supported by certain clients), which is why I've added a table to try to capture that in changes, but with all these things, once the implementation is done it's harder to go back and fill that table - it kind of appeared very late in the picture.

At least being their own namespace I think would make sense. This would make the UX better for people looking for them a lot cleaner, as well as make it arguably easier for devops / systems type people to load balance certain endpoints, block subroutes etc.

I guess this does ultimately pose the question did we make the wrong choice on MEV and / or Lightclient, and is it something that there's lessons to learn from...

[arnetheduck]

There are other recent examples too: distributed validator endpoints and validator performance API come to mind.

Re light client data, these actually have direct backing in the beacon spec, so they shouldn't be controversial as far as adding them here goes.

MEV indeed is a troublesome example, but perhaps not so much: all clients have expressed approval and actually implemented it.