Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: edit encoding docs #17626

Merged
merged 4 commits into from
Sep 8, 2023
Merged

docs: edit encoding docs #17626

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ede00f9
edit encoding docs
tac0turtle Sep 5, 2023
5605840
edit encoding docs
tac0turtle Sep 5, 2023
fdfe6ea
Merge branch 'main' into marko/encoding_docs
tac0turtle Sep 5, 2023
a5f74cf
Update docs/docs/develop/advanced/05-encoding.md
tac0turtle Sep 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 5 additions & 49 deletions docs/docs/develop/advanced/05-encoding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

### Amino

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
for their types, this is autogenerated via [buf](https://buf.build/)

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:
If modules use [Collections](../../build/packages/collections.md) or [ORM](../../build/packages/orm.md), encoding and decoding are handled, marshal and unmarshal should not be handled manually unless for specific cases identified by the developer.
tac0turtle marked this conversation as resolved.
Show resolved Hide resolved

```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

Expand Down