Amino encoding protocol

amino Is the object encoding specification . It is Proto3 Subset , With interface support extension

amino And Proto3 Largely compatible with （ But with Proto2 Are not compatible ）

amino The goal of the agreement

• Parity is divided into logical objects and persistent objects through support interfaces .
• Have unique / Deterministic value coding .
• Binary bytes must be decoded using a pattern .
• Patterns must be upgradeable .
• No pattern , Enough structures must be parsed .
• Encoder and decoder logic must be fairly simple .
• Serialization must be reasonably compact .
• Sufficient compatibility must be maintained JSON Format （ But not with JSON Make a general conversion ）

Amino vs JSON

JavaScript Object Notation（JSON） Easy to read , Reasonable structure , Very suitable for Javascript interoperate , But it's inefficient . Why does it exist Protobuf3,BER,RLP, Because we need to be more compact , A more efficient binary coding standard .Amino For complex objects （ For example, embedded objects ） Provides effective binary encoding , These objects are naturally integrated with your favorite modern programming languages . Besides ,Amino With full compatibility JSON code

Amino vs Protobuf3

Amino Hope to become Protobuf4

• Protobuf3 Interface not supported . It supports oneof, As a union type , But in Modern Languages （ for example C ++ class ,Java Interface / class ,Go Interface / The implementation and Rust characteristic ） Can not be well converted to “ Interface ” and “ Realization ”

If Protobuf Interface support , The user of the externally defined schema file will be able to support the specific type of the interface defined by the caller . contrary ,oneofProtobuf3 The functional requirements of oneof The specific type is pre declared in the definition of the field

Amino Detailed rules for the

Interface

Amino It is a coding library that can handle interfaces . It's through every “ The specific type ” The byte prefix was added before .

The specific type is the non interface type that implements the registered interface . Not all types need to be registered as concrete types - Only if they will be stored in the interface type field （ Or a list of interface elements ） In the middle of the day , You need to register them . The specific types of interface registration and implementation shall be carried out during program initialization , To detect any problems

Registration type

To encode and decode the interface , You must register with them ,codec.RegisterInterface

amino.RegisterInterface((*MyInterface1)(nil), nil)
amino.RegisterInterface((*MyInterface2)(nil), nil)
amino.RegisterConcrete(MyStruct1{
    }, "com.tendermint/MyStruct1", nil)
amino.RegisterConcrete(MyStruct2{
    }, "com.tendermint/MyStruct2", nil)
amino.RegisterConcrete(&MyStruct3{
    }, "anythingcangoinhereifitsunique", nil)

Prefix bytes to identify specific types

All registered specific types are previously 4 Bytes （ be called “ Prefix bytes ”） Encoding , Even if it is not in the interface field / The same is true of elements . such ,Amino To ensure that （ almost ） Concrete types always have the same canonical representation . The first byte of prefix byte cannot be zero byte

When you register 1024 A concrete type that implements the same interface , The likelihood of conflict is about 0.01％

Prefix bytes never start with zero bytes , Therefore, ambiguous bytes are represented by 0x00 Transference .

4 Prefix bytes always precede the binary encoding of a specific type

Calculate prefix and ambiguous bytes

To calculate the disambiguation bytes , We take hash := sha256(concreteTypeName) And delete leading 0x00 byte .

> hash := sha256("com.tendermint.consensus/MyConcreteName")
> hex.EncodeBytes(hash) // 0x{00 00 A8 FC 54 00 00 00 BB 9C 83 DD ...} (example)

In the example above ,hash There are two leading 0x00 byte , So we delete it .

> rest = dropLeadingZeroBytes(hash) // 0x{A8 FC 54 00 00 00 BB 9C 83 DD ...}
> disamb = rest[0:3]
> rest = dropLeadingZeroBytes(rest[3:])
> prefix = rest[0:4]

Unsupported type

Floating point numbers

Floating point type is not recommended , because They are usually uncertain . If you need to use them , Please use field label amino:"unsafe".