JSON RPC OpenRPC Spec

[alita-moore]

This specification uses EIP 1474, splits up the spec into a more manageable multi-file format, and I've begun incorporating the yellow paper where applicable.

This is the initial commit, and changes are expected. Particularly as they pertain to including edgecases as an md in each endpoints description. This will be accomplished by storing each edgecase in the same format as the methods themselves but in an "edgecases" folder.

the current structure allows for more easy reuse of components / schemas with method specific descriptions and requirements and it more clearly separates schemas from components from methods which are all different levels. This separation is necessary due to the way that OpenRPC parses the json.

You may notice that I use external references to internal entries in the json (i.e. ./File.json#/item instead of #/item). This is just a work around for a weird bug I ran into where internally referenced items would try to resolve relative to the externally imported component (i.e. file2 imports File.json#/item and then #/item is not in file2 so it errors).

you can see the built specification here

The goal here was maximum maintainability by keeping relevant info where it's most useful and never repeating things. I'd like to get rid of the components in the future fit this reason but they already to be a key part of the openrpc. Nevertheless I've done my best here to keep things as clean as possible. There are some ways to clean it up still. But I think it's fine for now. But what do you think?

[lightclient]

Left a couple comments, but mainly trying to understand the need for the aliases? I loaded the built spec into the openrpc playground, and it didn't seem like there were any additional docs. Additionally, it seems like a lot of these things aren't used (like addressOrNull).

[lightclient]

We should remove files that can be auto generated. We can add a CI task to build the spec into a non-main branch.

[alita-moore]

You need this to be pre generated for the open RPC playground.

[lightclient]

Yes, I understand. It's generally standard though to do this as a CI task rather than require developers to do this on push. You can see how we do it for the eth1 spec here: https://github.com/quilt/eth1.0-specs/blob/pyspec/.github/workflows/gh-pages.yaml

[shanejonas]

as as stop-gap for the external md files, you could use the method.externalDocumentation object to link back to the repos markdown files.

or just compile them to a string in the build step, and add them as the description:

$ cat foo.md
# Hello World

my markdown file


## Second thing


- a list
- of things


$ node
> const fs = require('fs');
undefined
> const mdFile = fs.readFileSync("foo.md");
undefined
> mdFile.toString();
'# Hello World\n\nmy markdown file\n\n\n## Second thing\n\n\n- a list\n- of things\n'

[alita-moore]

@lightclient i don't know what you mean by additional docs. The aliases are useful because they abstract components as to be easier to maintain. There's some clutter right now that I can clean up, though.

[alita-moore]

Thanks @shanejonas !

[alita-moore]

@lightclient this is ready for review again with the exception of the build on push (which is still in progress)

[shanejonas]

I like that the content descriptors are inline now, easier to follow.

the schemas left need to be cleaned up to only have title and description, not name and summary

[alita-moore]

got it @shanejonas will make that change, it's especially nice that the schemas are separated because it can be fixed easily using regex. Thanks!

[shanejonas]

link needs to be updated to this repo, and pointed at the raw version

[shanejonas]

this doesnt look right combining headerObject with an array of tx hashes.

it should be combining type: 'object's together with the correct shape that you want to merge:

"allOf": [
      {
        "$ref": "./Header.json#/headerObject"
      },
      {
       "type: "object",
       "properties": {
           "transactions": {
              "$ref": "./Block.json#/transactionHash"
           }
       },
        {
       "type: "object",
       "properties": {
           "uncles": {
              "$ref": "./Block.json#/transactionHash"
           }
       }
]       

side note: the name transactionHash seems like an incorrect name for an array of transaction hashes.

also you can pass true to eth_getBlockByNumber and it returns the transactions filled out instead of just the hashes:

so it needs to take that into account too

[lightclient]

I ended up splitting out the spec in #23. I recommend using that as the base for additional work on the method and schema definitions.

[alita-moore]

Alright, thanks