Update interfaces, clarify type intentions

[rekmarks]

Link to file: https://github.com/rekmarks/EIPs/blob/1193-update-interfaces/EIPS/eip-1193.md

Summary of Changes

• Remove index signatures from interfaces
  • i.e. no more [key: string]: unknown; the ability to add properties is implied
• RequestArguments
  • params?: unknown -> params?: unknown[] | object
  • Explicitly define relationship between RequestArguments fields and RPC method names and parameters
    • You could say that relationship was heavily implied, but 🤷
• Remove redundant MAY statements.
• Various minor fixups and clarifications
  • Clarify author intentions in certain places

A Note on request

After review, here's where I currently stand on the signature of request.

• request takes a single, options bag argument, to make it as extensible as possible. We are extremely unlikely to have to revisit it ever again. This is a wonderful thing.
  • If devs find the options bag unergonomic, they can define their own wrapper functions. We, however, should not bloat the spec with syntactic sugar.
• Provider implementers should type RequestArguments and its params property however it makes practical sense to do so. Presumably, they'll type it such that it supports whatever RPC methods the implementation supports.
  • That said, I have not found an example of an RPC protocol that does not take its parameters by name (object) or position (array). As such, we set the type to params?: unknown[] | object.
  • This is not normative for future RPC specifications. This only normative for how those methods are called via this API. If RPC standards emerge that map poorly to this concept, that's IMO an acceptable use case for errata.
• I recommend that implementers implement request in this way:
  • Do basic input validation (i.e. typeof args?.method === 'string').
  • Try to find a method handler.
  • If no handler, return error. If handler, hand off to handler; return result or error from handler.
    • Do detailed type checking of params in handler.

---

Ref #2319

cc: @alcuadrado @ryanio @MicahZoltu

[ryanio]

Lgtm, thanks for putting this together from the feedback!

[rekmarks]

@ryanio after further discussion with @MicahZoltu and others, I expanded these changes, and changed the type of RequestArguments.params.

cc: @alcuadrado

[MicahZoltu]

I'm a fan of short and concise standards that clearly indicate the set of things necessary for communication between two systems implementing the standard. As indicated in my comments, I feel like a number of the additions (along with some of the text that was present prior to this PR) needlessly hand hold developers and are not necessary for the standard to serve its purpose in providing a mechanism for two systems to communicate with each other.

TypeScript is structurally typed (duck typed), and JavaScript is untyped so there is no need for any mention of what else may or may not be on an object and we can instead focus this specification on what MUST be on the object. The time when MAY is useful is when something is optional but if present then it MUST meet some constraints. That is, I think an MAY statement that doesn't also contain a MUST (or in some cases a MUST NOT) should be removed from the spec.

I would also generally like to see this standard cleaned up a of much of the opinion and style comments, and also get rid of some of the redundancy that is currently present. While we have been having a lot of discussion and disagreement on what the standard should be, I think whatever that is can be described in very few words and we should strive to be pithy (unlike this comment).

[ryanio]

Looks good, nice summary and changes, thx! 👍

[alcuadrado]

These changes look good. Thanks @rekmarks.

[rekmarks]

FYI: I'm not making any changes to this PR anymore, I'm just force-pushing to cause CI to rerun.

[frozeman]

Thanks for that @rekmarks!
I would though like to see at least one example in written out JS as I know how much easier it will make it to implementers, and how it will prevent misunderstandings. 99% developers don’t read the spec they simply copy the example and change it up.

[rekmarks]

MetaMask has a working implementation here: https://github.com/MetaMask/inpage-provider/blob/master/src/MetamaskInpageProvider.js

Edit: Our implementation includes a lot of cruft related the old API and some of our internals. I'm considering extracting all of the method and event implementations into a sample implementation gist that could be attached to 1193 itself.

[frozeman]

I mean a one liner:

ethereum.request({method: 'eth_exampleRequest', params: ['param1']});

Not a full implementation. We shouldn’t need to go to one companies implantation for reference, as this could be biased. (Don’t get me wrong, I like MM)

[rekmarks]

Ah, got it! Haha, our implementation is definitely biased.

There are a number of examples like that in the Examples section already, see: https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1193.md#examples

[frozeman]

Oh yes, I forgot about those. Sorry I am on my phone.