Add specification for Portal JSON-RPC

[KolbyML]

I am still working on this just getting it out there

[KolbyML]

I do think it would be nicer if we can get this all on one place/page, i.e. within the json-rpc specifications that get generated. But I do understand that this could be more work.

As example, the beacon api has very rich explanations on all of their calls: https://ethereum.github.io/beacon-APIs/

I don't think that is as detailed for implementations as the specification for the engine_api is. https://ethereum.github.io/beacon-APIs/ is more user focused, where this documentation I am building is more implementor focused

The engine_api has both a user facing https://ethereum.github.io/beacon-APIs/ and a developer-facing specification which goes into how RPC endpoints should behave which is more developer focused

[bhartnett]

We have recently reviewed and updated the validation of the state portal JSON-RPC endpoints and this is what we implemented based on what intuitively made sense:

• All content key parameters are now validated by decoding and checking that the content key is a valid type.
• All content values (offers) received as parameters are validated using local validations without network lookups. For the state network this means skipping the part that looks up the block header to get the state root but we can still validate the structure of the proofs and that the nodeHash in the content key matches the proof etc.
• All content fetched from the network for findContent endpoints is validated using local validation, in the case of the state network we decode and then check that the hash in the content key matches the hash of the returned value.
• Some endpoints store in the local db and others don't.
  • stateStore and stateLocalContent only touch the local db as expected.
  • stateRecursiveFindContent (being renamed to stateGetContent) and stateGossip store in the local db as we are thinking of these like 'high level' endpoints.
  • stateFindContent and stateOffer both query or send to a specific enr and therefore we opted to not store in the db and treat these as low level endpoints.

This was just our initial intuition of what seems like be a good implementation and perhaps the spec could head in this direction. I think we need to be clear what we mean by validation in the spec as well because the ones that can be done without network look ups should probably still be required by the spec.

[kdeme]

The engine_api has both a user facing https://ethereum.github.io/beacon-APIs/ and a developer-facing specification which goes into how RPC endpoints should behave which is more developer focused

I assume you meant to link https://github.com/ethereum/execution-apis/tree/main/src/engine. But yes, good point on user vs implementer docs, I didn't look at it with this differentiation. Perhaps that should be made clear also.

But I do think that in some cases you can just write it differently in the "users" specification because it is still very useful information to the user in the end. E.g. Implementer doc/spec would say: "Data MUST be validated by its hash before returning" User doc/spec: "Returned data is validated by its hash"

By the way, https://ethereum.github.io/beacon-APIs/ is quite detailed also, especially if you start looking into the validator API.