Co-authored-by: Marko <marko@baricevic.me>
This commit is contained in:
@@ -47,7 +47,7 @@ via Protobuf. This means that modules may use Protobuf encoding, but the types m
|
||||
implement `ProtoMarshaler`. If modules wish to avoid implementing this interface
|
||||
for their types, this is autogenerated via [buf](https://buf.build/)
|
||||
|
||||
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.
|
||||
Modules are recommended to use [collections](../../build/packages/02-collections.md) for handling encoding and decoding of state. Usage of collections handles marshal and unmarshal for you. By default protobuf is used but other encodings can be used if preferred.
|
||||
|
||||
### Gogoproto
|
||||
|
||||
@@ -78,15 +78,15 @@ the consensus engine accepts only transactions in the form of raw bytes.
|
||||
* The `TxDecoder` object performs the decoding.
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/tx_msg.go#L91-L95
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/types/tx_msg.go#L91-L95
|
||||
```
|
||||
|
||||
A standard implementation of both these objects can be found in the [`auth/tx` module](https://docs.cosmos.network/main/build/modules/auth#transactions):
|
||||
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/tx/decoder.go
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/x/auth/tx/decoder.go
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/tx/encoder.go
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/x/auth/tx/encoder.go
|
||||
```
|
||||
|
||||
See [ADR-020](../../architecture/adr-020-protobuf-transaction-encoding.md) for details of how a transaction is encoded.
|
||||
@@ -245,39 +245,3 @@ Protobuf types can be defined to encode:
|
||||
|
||||
We encourage developers to follow industry guidelines: [Protocol Buffers style guide](https://developers.google.com/protocol-buffers/docs/style)
|
||||
and [Buf](https://buf.build/docs/style-guide), see more details in [ADR 023](../../architecture/adr-023-protobuf-naming.md)
|
||||
|
||||
### How to update modules to protobuf encoding
|
||||
|
||||
If modules do not contain any interfaces (e.g. `Account` or `Content`), then they
|
||||
may simply migrate any existing types that
|
||||
are encoded and persisted via their concrete Amino codec to Protobuf (see 1. for further guidelines) and accept a `Marshaler` as the codec which is implemented via the `ProtoCodec`
|
||||
without any further customization.
|
||||
|
||||
However, if a module type composes an interface, it must wrap it in the `sdk.Any` (from `/types` package) type. To do that, a module-level .proto file must use [`google.protobuf.Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto) for respective message type interface types.
|
||||
|
||||
For example, in the `x/evidence` module defines an `Evidence` interface, which is used by the `MsgSubmitEvidence`. The structure definition must use `sdk.Any` to wrap the evidence file. In the proto file we define it as follows:
|
||||
|
||||
```protobuf
|
||||
// proto/cosmos/evidence/v1beta1/tx.proto
|
||||
|
||||
message MsgSubmitEvidence {
|
||||
string submitter = 1;
|
||||
google.protobuf.Any evidence = 2 [(cosmos_proto.accepts_interface) = "cosmos.evidence.v1beta1.Evidence"];
|
||||
}
|
||||
```
|
||||
|
||||
The Cosmos SDK `codec.Codec` interface provides support methods `MarshalInterface` and `UnmarshalInterface` to easy encoding of state to `Any`.
|
||||
|
||||
Module should register interfaces using `InterfaceRegistry` which provides a mechanism for registering interfaces: `RegisterInterface(protoName string, iface interface{}, impls ...proto.Message)` and implementations: `RegisterImplementations(iface interface{}, impls ...proto.Message)` that can be safely unpacked from Any, similarly to type registration with Amino:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/codec/types/interface_registry.go#L28-L75
|
||||
```
|
||||
|
||||
In addition, an `UnpackInterfaces` phase should be introduced to deserialization to unpack interfaces before they're needed. Protobuf types that contain a protobuf `Any` either directly or via one of their members should implement the `UnpackInterfacesMessage` interface:
|
||||
|
||||
```go
|
||||
type UnpackInterfacesMessage interface {
|
||||
UnpackInterfaces(InterfaceUnpacker) error
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user