ABI Format: binary extensions

[tbfleming]

This supports extending existing binary formats; e.g. adding new fields to tables.

Caution: binary extensions only operate correctly in certain locations.

• ok: a non-embedded struct stored in a row may have binary extensions at its end
• ok: an action may use binary extensions to add additional arguments to its end
• ok: a struct with binary extensions may be used inside another struct, but only if the inner struct is the last field of the outer struct and the outer struct is allowed to contain binary extensions
• not ok: a struct with binary extensions may not be used inside an array
• not ok: a struct with binary extensions may not be used as a base of another struct
• not ok: fields with types which don't end in $ following fields with types which do
• not ok: $ used anywhere except in struct field types

ABI version string

eosio::abi/1.1

ABI Text format

Types may have a $ suffix. During binary-to-json conversion, fields with a $ type don't error out when end-of-data has been reached; instead they're omitted. During json-to-binary conversion, missing fields don't error out as long as no non-missing fields follow in the ABI. This omits the bytes from the output stream.

e.g.

    {
      "name": "my_table_struct",
      "base": "",
      "fields": [
        {
          "name": "required_field_1",
          "type": "string"
        },
        {
          "name": "required_field_2",
          "type": "float32[]"
        },
        {
          "name": "optional_field_3",
          "type": "float32[]$"
        },
        {
          "name": "optional_field_4",
          "type": "string$"
        },
      ]
    },

JSON representation

Missing fields aren't included; null isn't used. E.g. all of these are valid JSON representations of my_table_struct:

{
    "required_field_1": "foo",
    "required_field_2": [1,2,3,4]
}

{
    "required_field_1": "foo",
    "required_field_2": [1,2,3,4],
    "optional_field_3": [5,6,7,8]
}

{
    "required_field_1": "foo",
    "required_field_2": [1,2,3,4],
    "optional_field_3": [5,6,7,8],
    "optional_field_4": "bar"
}

ABI Binary format

$ can be included in type strings. No other changes.

eosiolib

A new type tag (TBD) will identify these types. When an extension field is missing during deserialization, it will be left default-constructed.