IValue representation within GraphQL

[greymistcube]

Although we use IValue almost exclusively in terms of storing data, there is no consensus on how this should be served over the GraphQL service that we provide. There are numerous endpoints where conversions are dealt with separately with varying return formats.

Given some value of type IValue, there are currently four major formats in use:

• Hex: A hexadecimal representation of value encoded as byte array.
• Base64: A base64 representation of value encoded as byte array.
• Json: A JSON representation of value according to this schema
• Inspection: A semi human readable representation of value similar to usage in python.

Currently, the following simple query

query {
  state (
    address: "0123"
    hash: "abcd"
  )
}

would return something like

{
  "data": {
    "state": "0123456789abcdef"
  },
  "extensions": {}
}

that is, a hex representation by default without a way to retrieve the value in any other format.

Now, if we are to provide a general API to retrieve an IValue, we should try to standardize the API.
In order to allow a user to decide which representation to retrieve, such information must be passed on. Here I propose three different possible schemes.

Scheme 1

query {
  state (
    address: "0123"
    hash: "abcd"
    encoding: "hex"  # Can be ommitted if default value is set.
  )
}

• Pros: Least amount of change to the API with highest compatibility with the existing API.
• Cons: Requires higher level queries to take the argument and do the conversion.

Scheme 2

query {
  state (
    address: "0123"
    hash: "abcd"
  ) {
    hex
    json
  }
}

• Pros: Can retrieve multiple formats at once. Types of usable encoding can be easily documented.
• Cons: Breaks the existing API.

Scheme 3

query {
  state (
    address: "0123"
    hash: "abcd"
  ) {
    value(encoding: "hex")  # Simply can be `value` (without arguments) if default value is set.
  }
}

• Pros: Can have default argument.
• Cons: Breaks the existing API. Also excessive nesting.

Schemes 2 and 3 have additional advantage where it can be applied more generally. Such as querying serialized Block or Transaction in a more modular fashion. For example,

query {
  transaction {
    getTx(txId: "1234") {
      id
      nonce
    }
  }
}

can be changed more easily by adding a field (or fields) of an existing graph type.