NEAR Spec and standards

[ilblackdragon]

Want to start discussion for where and how we are going to maintain NEAR Spec and standards.

The NEPs process is mostly around proposal to modify / add things, but we also need the final version that lists the overall specification for the protocol and also all the accepted / used standards.

My proposal, we actually rework this repository instead of been a list of proposals into maintaining the released version of Spec + all accepted standards.

E.g. if would be a combination of https://github.com/ethereum/eth2.0-specs and https://github.com/ethereum/EIPs.

Where as NEP gets accepted it modifies the staging version of the spec and gets released with the new version. Alternatively if NEP represents new standard and doesn't require changes to protocol - it goes to the standards list.

Why standards mixed with spec? Mostly because standards end up representing a big part of the protocol itself. If you think of ERC-20 specification - it actually is a core part of the Ethereum protocol, even though doesn't live on blockchain level itself. Same thing can go for any number of other protocols.

I also think we can repurprose https://nomicon.io/ to serve final version of spec. That website already maintains mostly the spec details with few implementation details that we currently have in Rust client. We can split Rust specifics into the docs inside Rust repo (which currently is not pointing to nomicon.io anyway).

[MaksymZavershynskyi]

I suggest we make a separate repo for specs. NEPs is a great place to discuss all sorts of major ideas, like large rewrites, performance improvements. I would even use NEPs for discussions around the processes!

+1 For moving specs and standards into https://nomicon.io/ but let's not limit it to specs and standards only. Nomicon is a great place to guide through the details of the internals, which makes it easier for external people to contribute. If we foresee several versions of the implementation then let's give our implementation a code name, e.g. linear (other names for our client: bilinear, collinear, nonlinear, overnear) and have a section that talks specifically about its implementation.

[lexfrl]

Would be nice to have a clear discriminator for categories (layers) for specifications. For example, I'm for having specification and proposals which describe/alter consensus in a separate place from other documentation. If it's a ERC-20-like standard or a different serialization/deserialization format for contracts, or an addition of some RPC method: since it's a not altering consensus - better to keep it in a different category.

[ilblackdragon]

Here is my reasoning:

• The more places we have, harder it is to keep track of things. I for example can not keep up already with all the different sources of truth for different parts of the ecosystem.
• Standards are actually become part of the protocol. ERC-20 really is part of Ethereum, even if it's not enforced by code in geth, it's still something that lots of other tooling relies on, exchanges and wallets operate and etc. For example Wallet API which doesn't have anything to do with client, is still part of the protocol how apps and wallets will be interacting.
• I don't see clear different between consensus changes and RPC changes. Obviously they touch different pieces of code, but both require coordination across many different teams to address the changes. In case of consensus it will be coordination between client teams, in case of RPC it will be all the tooling. Changes to economics may affect everyone across the board and will require massive coordination.
• @fckt we should have different folders in the spec for different parts of the protocol / standards / etc.
• It's unclear why development details of nearcore are not in the nearcore repo. Same for discussion about optimizations in the nearcore specifically. Vs if we are discussing optimization of the state trie which actually changes protocol - it should be change to the spec.
• Processes should be documented in the spec, especially if they are involving the coordination between different clients / parties. For example Upgradability after discussion should be change to the spec providing both what do we need to change in the code and process that participants will need to be aware of.

@nearmax I didn't understand your "linear"/"sublinear". I want to have "releases" for spec, in similar way we are planning to have releases for clients. Ideally have trains with monthly release, which also includes some tests release. This way we can say which version clients target of the spec.

[lexfrl]

Changes to economics may affect everyone across the board and will require massive coordination.

What we're calling "economics" - it's a part of the consensus. Сhanges in consensus are any changes which lead to a fork (validator which is not following the current consensus (e.g. running out-of-date node) will be slashed). So, the primary target audience for the consensus changes are the node operators (validators).

I don't see clear different between consensus changes and RPC changes.

RPCs can be backward-compatible, but consensus rules cant. User can even add a new RPC to his node and support it for himself only (or disable some of these). Typical node operator will likely to switch off the RPC at all.

"ERC-20"-like (we call it app-layer) proposals are user-land protocols and require user coordination, but not node operators.

[ilblackdragon]

Ok, here is the decision:

• Rename this repo into specs.
• This repo will be maintaining specs, processes and standards.
• Moving the content of https://github.com/nearprotocol/nomicon to this repo.
• Changing format for NEPs to either:
  • Modify spec (toward next planned release of the spec)
  • Add new standard (Fungible Token) or revise existing standard (e.g. Open Web v1.2)
  • Describe process for something (e.g. release process for specs)

[mfornet]

It is not clear how the (structured) content of nomicon will fit in this unstructured repository. If this is supposed to be the source of truth (among other things) to implement clients we should have a clear structure that help developers going through it.

From my point of view the main feature of this repository was the discussion around new proposals before accepting them, but then we have Commonwealth too.

[ilblackdragon]

Will be moving structure into here. Proposals here should update changes according to the structure if they changing spec. Discussion for changing spec should be happening here as well. We are working with Commonwealth to add PRs from this repo to the Commonwealth so we can cross-discuss + add in future bounty for implementation and others.

[ilblackdragon]

Closing this issue. The spec is moved here.