You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
172 lines
5.8 KiB
172 lines
5.8 KiB
Wire Protocol
|
|
=============
|
|
|
|
The `Tendermint wire protocol <https://github.com/tendermint/go-wire>`__
|
|
encodes data in `c-style binary <#binary>`__ and `JSON <#json>`__ form.
|
|
|
|
Supported types
|
|
---------------
|
|
|
|
- Primitive types
|
|
- ``uint8`` (aka ``byte``), ``uint16``, ``uint32``, ``uint64``
|
|
- ``int8``, ``int16``, ``int32``, ``int64``
|
|
- ``uint``, ``int``: variable length (un)signed integers
|
|
- ``string``, ``[]byte``
|
|
- ``time``
|
|
- Derived types
|
|
- structs
|
|
- var-length arrays of a particular type
|
|
- fixed-length arrays of a particular type
|
|
- interfaces: registered union types preceded by a ``type byte``
|
|
- pointers
|
|
|
|
Binary
|
|
------
|
|
|
|
**Fixed-length primitive types** are encoded with 1,2,3, or 4 big-endian
|
|
bytes. - ``uint8`` (aka ``byte``), ``uint16``, ``uint32``, ``uint64``:
|
|
takes 1,2,3, and 4 bytes respectively - ``int8``, ``int16``, ``int32``,
|
|
``int64``: takes 1,2,3, and 4 bytes respectively - ``time``: ``int64``
|
|
representation of nanoseconds since epoch
|
|
|
|
**Variable-length integers** are encoded with a single leading byte
|
|
representing the length of the following big-endian bytes. For signed
|
|
negative integers, the most significant bit of the leading byte is a 1.
|
|
|
|
- ``uint``: 1-byte length prefixed variable-size (0 ~ 255 bytes)
|
|
unsigned integers
|
|
- ``int``: 1-byte length prefixed variable-size (0 ~ 127 bytes) signed
|
|
integers
|
|
|
|
NOTE: While the number 0 (zero) is encoded with a single byte ``x00``,
|
|
the number 1 (one) takes two bytes to represent: ``x0101``. This isn't
|
|
the most efficient representation, but the rules are easier to remember.
|
|
|
|
+---------------+----------------+----------------+
|
|
| number | binary | binary ``int`` |
|
|
| | ``uint`` | |
|
|
+===============+================+================+
|
|
| 0 | ``x00`` | ``x00`` |
|
|
+---------------+----------------+----------------+
|
|
| 1 | ``x0101`` | ``x0101`` |
|
|
+---------------+----------------+----------------+
|
|
| 2 | ``x0102`` | ``x0102`` |
|
|
+---------------+----------------+----------------+
|
|
| 256 | ``x020100`` | ``x020100`` |
|
|
+---------------+----------------+----------------+
|
|
| 2^(127\ *8)-1 | ``x800100...`` | overflow |
|
|
| \| | | |
|
|
| ``x7FFFFF...` | | |
|
|
| ` | | |
|
|
| \| | | |
|
|
| ``x7FFFFF...` | | |
|
|
| ` | | |
|
|
| \| \| | | |
|
|
| 2^(127*\ 8) | | |
|
|
+---------------+----------------+----------------+
|
|
| 2^(255\*8)-1 |
|
|
| \| |
|
|
| ``xFFFFFF...` |
|
|
| ` |
|
|
| \| overflow |
|
|
| \| \| -1 \| |
|
|
| n/a \| |
|
|
| ``x8101`` \| |
|
|
| \| -2 \| n/a |
|
|
| \| ``x8102`` |
|
|
| \| \| -256 \| |
|
|
| n/a \| |
|
|
| ``x820100`` |
|
|
| \| |
|
|
+---------------+----------------+----------------+
|
|
|
|
**Structures** are encoded by encoding the field values in order of
|
|
declaration.
|
|
|
|
.. code:: go
|
|
|
|
type Foo struct {
|
|
MyString string
|
|
MyUint32 uint32
|
|
}
|
|
var foo = Foo{"626172", math.MaxUint32}
|
|
|
|
/* The binary representation of foo:
|
|
0103626172FFFFFFFF
|
|
0103: `int` encoded length of string, here 3
|
|
626172: 3 bytes of string "bar"
|
|
FFFFFFFF: 4 bytes of uint32 MaxUint32
|
|
*/
|
|
|
|
**Variable-length arrays** are encoded with a leading ``int`` denoting
|
|
the length of the array followed by the binary representation of the
|
|
items. **Fixed-length arrays** are similar but aren't preceded by the
|
|
leading ``int``.
|
|
|
|
.. code:: go
|
|
|
|
foos := []Foo{foo, foo}
|
|
|
|
/* The binary representation of foos:
|
|
01020103626172FFFFFFFF0103626172FFFFFFFF
|
|
0102: `int` encoded length of array, here 2
|
|
0103626172FFFFFFFF: the first `foo`
|
|
0103626172FFFFFFFF: the second `foo`
|
|
*/
|
|
|
|
foos := [2]Foo{foo, foo} // fixed-length array
|
|
|
|
/* The binary representation of foos:
|
|
0103626172FFFFFFFF0103626172FFFFFFFF
|
|
0103626172FFFFFFFF: the first `foo`
|
|
0103626172FFFFFFFF: the second `foo`
|
|
*/
|
|
|
|
**Interfaces** can represent one of any number of concrete types. The
|
|
concrete types of an interface must first be declared with their
|
|
corresponding ``type byte``. An interface is then encoded with the
|
|
leading ``type byte``, then the binary encoding of the underlying
|
|
concrete type.
|
|
|
|
NOTE: The byte ``x00`` is reserved for the ``nil`` interface value and
|
|
``nil`` pointer values.
|
|
|
|
.. code:: go
|
|
|
|
type Animal interface{}
|
|
type Dog uint32
|
|
type Cat string
|
|
|
|
RegisterInterface(
|
|
struct{ Animal }{}, // Convenience for referencing the 'Animal' interface
|
|
ConcreteType{Dog(0), 0x01}, // Register the byte 0x01 to denote a Dog
|
|
ConcreteType{Cat(""), 0x02}, // Register the byte 0x02 to denote a Cat
|
|
)
|
|
|
|
var animal Animal = Dog(02)
|
|
|
|
/* The binary representation of animal:
|
|
010102
|
|
01: the type byte for a `Dog`
|
|
0102: the bytes of Dog(02)
|
|
*/
|
|
|
|
**Pointers** are encoded with a single leading byte ``x00`` for ``nil``
|
|
pointers, otherwise encoded with a leading byte ``x01`` followed by the
|
|
binary encoding of the value pointed to.
|
|
|
|
NOTE: It's easy to convert pointer types into interface types, since the
|
|
``type byte`` ``x00`` is always ``nil``.
|
|
|
|
JSON
|
|
----
|
|
|
|
The JSON codec is compatible with the ```binary`` <#binary>`__ codec,
|
|
and is fairly intuitive if you're already familiar with golang's JSON
|
|
encoding. Some quirks are noted below:
|
|
|
|
- variable-length and fixed-length bytes are encoded as uppercase
|
|
hexadecimal strings
|
|
- interface values are encoded as an array of two items:
|
|
``[type_byte, concrete_value]``
|
|
- times are encoded as rfc2822 strings
|