Define a better public API

[axic]

This is meant to be a discussion starter for defining a better public API.

Right now, both rawDecode and rawEncode expect an array of argument types as well as array of the values: encode('sampleMethod', [ 'bytes', 'uint' ], [ <bytes data>, 1234 ])

decode and encode was meant to support string definitions matched against the ABI JSON, but it wasn't implemented to date.

What I am thinking about right now for a more user friendly API is:

• encode('sampleMethod(bytes,uint)', <bytes data>, 1234), and/or
• encode(abiJSON, 'sampleMethod', <bytes data>, 1234) in this case it is devised that <bytes data> is suitable as bytes type and 1234 as uint type and a matching signature is looked up in the ABI JSON.

(Might need to use actual arrays or fall back to single argument if the signature allows.)

Augur's way:

encode({
  method: 'sampleMethod',
  signature: 'bi',
  params: [ <bytes data>, 1234 ]
})

Perhaps it would be nice to support the Serpent signature, but I am not adamant on it. The Standard Contract ABI page really only refers to the others.

Alternatively there is no need at all for handling the ABI JSON in this project, rather it should be a separate one building on top of an RPC library (perhaps ethrpc) and this one, providing a similar interface to web3.js Contract.

Any ideas?

[axic]

cc @tinybike @wanderer

[wanderer]

I like the simplicity of raw(De|En)code. I think exposing both would be a good idea. For encode wouldn't parsing the JSON abi be easier to do than a string?

[axic]

The ABI JSON makes it easy to support overloading for encoding, e.g. if the ABI defines someMethod with both bytes and uint as an input, encode() could decide which one to encode based on the type of arguments passed in Javascript. However this is not the case in decode() where the type needs to be given explicitly. This limits the usefulness of the JSON to encoding only.

Based on this, I think the JSON part would only make sense the way it is done in web3 - to instantiate objects which proxy encoding/decoding to the destination via RPC.

I like this shorthand though for both encoding and decoding: encode('someMethod(bytes,uint)', <bytes data>, 1234). Perhaps for decode() it should support the expected return type as: decode('someMethod(bytes,uint):(boolean)')

rawEncode() and rawDecode() shall remain unchanged.

[holgerd77]

This probably needs further discussion if wished to be pursued.