github.com/gnolang/gno@v0.0.0-20240520182011-228e9d0192ce/tm2/pkg/amino/README.md (about)

     1  # Amino
     2  
     3  http://github.com/gnolang/gno/tm2/pkg/amino
     4  
     5  NOTE: This project used to be gnolang/gno/pkgs/amino, derived from
     6  tendermint/go-amino.
     7  
     8  Amino is an encoding/decoding library for structures.
     9  
    10  In Amino, all structures are declared in a restricted set of Go.
    11  
    12  From those declarations, Amino generates Protobuf3 compatible binary bytes.
    13  
    14  For faster encoding and decoding, Amino also generates Protobuf3 schemas, and
    15  also generates translation logic between the original Go declarations and
    16  Protobuf3/protoc generated Go.  In this way, Amino supports a restricted set
    17  of Protobuf3.
    18  
    19  Though Amino supports a subset of Protobuf3 and uses it to optimize encoding
    20  and decoding, it is NOT intended to be a Protobuf3 library -- complete support
    21  of Protobuf3 is explicitly not its design goal.
    22  
    23  You can see the performance characteristics of the improvements in [XXX -- this
    24  exists, but i forget the filename.].
    25  
    26  The gist is that in recent versions of Go, the reflection-based binary
    27  encoding/decoding system is about 3x slower than the protoc generated Go ones,
    28  and that the translation system works pretty well, accounting for only ~25% of
    29  the total time, so the performance hit isn't fatal.
    30  
    31  While creating and finalizing this library, which I believe it is, roughly, the
    32  final form of a well structured piece of software according to my tastes, it
    33  occurred to me that Proto3 is a complexification that is not needed in well
    34  written software, and that it mostly serves systems that are part of the mass
    35  public surveillance database amassed in datacenters across the world.  Somewhere,
    36  there is a proto3 field number and value that describes some new aspect about me,
    37  in several instances of Google's massive database.
    38  
    39  What I want instead is a language, and for that, the original implementation
    40  of Amino is better suited.
    41  
    42  # Amino JSON
    43  
    44  This is experimental and subject to change.
    45  
    46  ## Amino in the Wild
    47  
    48  * Amino:binary spec in [Tendermint](
    49  https://github.com/tendermint/tendermint/blob/master/docs/spec/blockchain/encoding.md)
    50  
    51  
    52  # Amino Spec
    53  
    54  #### Registering types and packages
    55  
    56  Previous versions of Amino used to require a local codec where types must be
    57  registered.  With the change to support Any and type URL strings,
    58  we no longer need to keep track of local codecs, unless we want to override
    59  default behavior from global registrations.
    60  
    61  Each package should declare in a package local file (by convention called amino.go)
    62  which should look like the following:
    63  
    64  ```go
    65  // see github.com/gnolang/gno/tm2/pkg/amino/protogen/example/main.go
    66  package main
    67  
    68  import (
    69  	"github.com/gnolang/gno/tm2/pkg/amino"
    70  	"github.com/gnolang/gno/tm2/pkg/amino/genproto/example/submodule"
    71  )
    72  
    73  var Package = amino.RegisterPackage(
    74  	amino.NewPackage(
    75  		"main", // The Go package path
    76  		"main", // The (shorter) Proto3 package path (no slashes).
    77  		amino.GetCallersDirname(),
    78  	).WithDependencies(
    79  		submodule.Package, // Dependencies must be declared (for now).
    80  	).WithTypes(
    81  		StructA{}, // Declaration of all structs to be managed by Amino.
    82  		StructB{}, // For example, protogen to generate proto3 schema files.
    83  		&StructC{}, // If pointer receivers are preferred when decoding to interfaces.
    84  	),
    85  )
    86  ```
    87  
    88  You can still override global registrations with local \*amino.Codec state.
    89  This is used by genproto.P3Context, which may help development while writing
    90  migration scripts.  Feedback welcome in the issues section.
    91  
    92  ## Unsupported types
    93  
    94  ### Floating points
    95  Floating point number types are discouraged as [they are generally
    96  non-deterministic](http://gafferongames.com/networking-for-game-programmers/floating-point-determinism/).
    97  If you need to use them, use the field tag `amino:"unsafe"`.
    98  
    99  ### Enums
   100  Enum types are not supported in all languages, and they're simple enough to
   101  model as integers anyways.
   102  
   103  ### Maps
   104  Maps are not currently supported.  There is an unstable experimental support
   105  for maps for the Amino:JSON codec, but it shouldn't be relied on.  Ideally,
   106  each Amino library should decode maps as a List of key-value structs (in the
   107  case of languages without generics, the library should maybe provide a custom
   108  Map implementation).  TODO specify the standard for key-value items.
   109  
   110  ## Amino and Proto3
   111  
   112  Amino objects are a subset of Proto3.
   113  * Enums are not supported.
   114  * Nested message declarations are not supported.
   115  
   116  Amino extends Proto3's Any system with a particular concrete type
   117  identification format (disfix bytes).
   118  
   119  ## Amino and Go
   120  
   121  Amino objects are a subset of Go.
   122  * Multi-dimensional slices/arrays are not (yet) supported.
   123  * Floats are nondeterministic, so aren't supported by default.
   124  * Complex types are not (yet) supported.
   125  * Chans, funcs, and maps are not supported.
   126  * Pointers are automatically supported in go-amino but it is an extension of
   127    the theoretical Amino spec.
   128  
   129  Amino, unlike Gob, is beyond the Go language, though the initial implementation
   130  and thus the specification happens to be in Go (for now).
   131  
   132  ## Limitations
   133  
   134  * Pointer types in arrays and slices lose pointer information.
   135  * Nested pointers are not allowed.
   136  * Recursive ReprType not allowed.