LaconicNetwork/cosmos-sdk
10
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 2 Wiki Activity

docs: edit encoding docs (backport #17626) (#17665)

Browse Source 
Co-authored-by: Marko <marbar3778@yahoo.com>
This commit is contained in:
mergify[bot] 2023-09-08 16:33:26 +02:00 committed by GitHub
parent 837430f8bc
commit ccd7288ef3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 5 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
docs/docs/develop/advanced/05-encoding.md
View File

@ -42,58 +42,14 @@ In the `codec` package, there exists two core interfaces, `BinaryCodec` and `JSO
where the former encapsulates the current Amino interface except it operates on
types implementing the latter instead of generic `interface{}` types.
In addition, there exists two implementations of `Codec`. The first being
`AminoCodec`, where both binary and JSON serialization is handled via Amino. The
second being `ProtoCodec`, where both binary and JSON serialization is handled
via Protobuf.
This means that modules may use Amino or Protobuf encoding, but the types must
The `ProtoCodec`, where both binary and JSON serialization is handled
via Protobuf. This means that modules may use Protobuf encoding, but the types must
implement `ProtoMarshaler`. If modules wish to avoid implementing this interface
for their types, they may use an Amino codec directly.
for their types, this is autogenerated via [buf](https://buf.build/)
### Amino
If modules use [Collections](../../build/packages/02-collections.md) or [ORM](../../build/packages/03-orm.md), encoding and decoding are handled, marshal and unmarshal should not be handled manually unless for specific cases identified by the developer.
Every module uses an Amino codec to serialize types and interfaces. This codec typically
has types and interfaces registered in that module's domain only (e.g. messages),
but there are exceptions like `x/gov`. Each module exposes a `RegisterLegacyAminoCodec` function
that allows a user to provide a codec and have all the types registered. An application
will call this method for each necessary module.
Where there is no protobuf-based type definition for a module (see below), Amino
is used to encode and decode raw wire bytes to the concrete type or interface:
```go
bz := keeper.cdc.MustMarshal(typeOrInterface)
keeper.cdc.MustUnmarshal(bz, &typeOrInterface)
```
Note, there are length-prefixed variants of the above functionality and this is
typically used for when the data needs to be streamed or grouped together
(e.g. `ResponseDeliverTx.Data`)
#### Authz authorizations and Gov/Group proposals
Since authz's `MsgExec` and `MsgGrant` message types, as well as gov's and group's `MsgSubmitProposal`, can contain different messages instances, it is important that developers
add the following code inside the `init` method of their module's `codec.go` file:
```go
import (
authzcodec "github.com/cosmos/cosmos-sdk/x/authz/codec"
govcodec "github.com/cosmos/cosmos-sdk/x/gov/codec"
groupcodec "github.com/cosmos/cosmos-sdk/x/group/codec"
)
init() {
// Register all Amino interfaces and concrete types on the authz and gov Amino codec so that this can later be
// used to properly serialize MsgGrant, MsgExec and MsgSubmitProposal instances
RegisterLegacyAminoCodec(authzcodec.Amino)
RegisterLegacyAminoCodec(govcodec.Amino)
RegisterLegacyAminoCodec(groupcodec.Amino)
}
```
This will allow the `x/authz` module to properly serialize and de-serializes `MsgExec` instances using Amino,
which is required when signing this kind of messages using a Ledger.
```go reference
### Gogoproto