From e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6 Mon Sep 17 00:00:00 2001 From: marbar3778 Date: Wed, 6 Sep 2023 16:35:48 +0200 Subject: [PATCH] add docs on proto annotations --- .../building-apps/05-protobuf-annotations.md | 81 +++++++++++++++++++ .../02-messages-and-queries.md | 4 +- .../building-apps/03-protobuf-annotations.md | 35 -------- 3 files changed, 83 insertions(+), 37 deletions(-) create mode 100644 docs/docs/build/building-apps/05-protobuf-annotations.md delete mode 100644 docs/docs/building-apps/03-protobuf-annotations.md diff --git a/docs/docs/build/building-apps/05-protobuf-annotations.md b/docs/docs/build/building-apps/05-protobuf-annotations.md new file mode 100644 index 000000000000..91f443494c0b --- /dev/null +++ b/docs/docs/build/building-apps/05-protobuf-annotations.md @@ -0,0 +1,81 @@ +--- +sidebar_position: 1 +--- + +# ProtocolBuffer Annotations + +This document explains the various protobuf scalars that have been added to make working with protobuf easier for Cosmos SDK application developers + +## Signer + +Signer specifies which field should be used to determine the signer of a message for the Cosmos SDK. This field can be used for clients as well to infer which field should be used to determine the signer of a message. + +Read more about the signer field [here](../building-modules/02-messages-and-queries.md). + +```protobuf reference +https://github.com/cosmos/cosmos-sdk/blob/e6848d99b55a65d014375b295bdd7f9641aac95e/proto/cosmos/bank/v1beta1/tx.proto#L40 +``` + +```proto +option (cosmos.msg.v1.signer) = "from_address"; +``` + +## Scalar + +The scalar type defines a way for clients to understand how to construct protobuf messages according to what is expected by the module and sdk. + +```proto +(cosmos_proto.scalar) = "cosmos.AddressString" +``` + +There are a few options for what can be provided as a scalar: cosmos.AddressString, cosmos.ValidatorAddressString, cosmos.ConsensusAddressString, cosmos.Int, cosmos.Dec. + +## Implements_Interface + +Implement interface is used to provide information to client tooling like [telescope](https://github.com/cosmology-tech/telescope) on how to encode and decode protobuf messages. + +```proto +option (cosmos_proto.implements_interface) = "cosmos.auth.v1beta1.AccountI"; +``` + +## Amino + +The amino codec was removed in 0.50.0, this means there is not a need register `legacyAminoCodec`. To replace the amino codec, Amino protobuf annotations are used to provide information to the amino codec on how to encode and decode protobuf messages. + +:::Note +Amino annotations are only used for backwards compatibility with amino. New modules should not use amino annotations. The +::: + +The below annotations are used to provide information to the amino codec on how to encode and decode protobuf messages in a backwards compatible manner. + +### Name + +Name specifies the amino name that would show up for the user in order for them see which message they are signing. + +```proto +option (amino.name) = "cosmos-sdk/BaseAccount"; +``` + +### Field_Name + +Field name specifies the amino name that would show up for the user in order for them see which field they are signing. + +```proto +(amino.field_name) = "public_key" +``` + +### Dont_OmitEmpty + +Dont omitempty specifies that the field should not be omitted when encoding to amino. + +```proto +(amino.dont_omitempty) = true, +``` + +### Encoding + +Encoding specifies the amino encoding that should be used when encoding to amino. + +```proto +(amino.encoding) = "legacy_coins", +``` diff --git a/docs/docs/build/building-modules/02-messages-and-queries.md b/docs/docs/build/building-modules/02-messages-and-queries.md index 69465ab5e576..88b4bfabb14b 100644 --- a/docs/docs/build/building-modules/02-messages-and-queries.md +++ b/docs/docs/build/building-modules/02-messages-and-queries.md @@ -49,10 +49,10 @@ https://github.com/cosmos/cosmos-sdk/blob/9c1e8b247cd47b5d3decda6e86fbc3bc996ee5 In 0.50+ signers from the `GetSigners()` call is automated via a protobuf annotation. - +Read more about the signer field [here](../building-apps/05-protobuf-annotations.md). ```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/e6848d99b55a65d014375b295bdd7f9641aac95e/proto/cosmos/bank/v1beta1/tx.proto#L41 +https://github.com/cosmos/cosmos-sdk/blob/e6848d99b55a65d014375b295bdd7f9641aac95e/proto/cosmos/bank/v1beta1/tx.proto#L40 ``` If there is a need for custom signers then there is an alternative path which can be taken. A function which returns `signing.CustomGetSigner` for a specific message can be defined. diff --git a/docs/docs/building-apps/03-protobuf-annotations.md b/docs/docs/building-apps/03-protobuf-annotations.md deleted file mode 100644 index c690ef18072a..000000000000 --- a/docs/docs/building-apps/03-protobuf-annotations.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -sidebar_position: 1 ---- - -# ProtocolBuffer Annotations - -This document explains the various protobuf scalars that have been added to make working with protobuf easier for Cosmos SDK application developers - -## Scalar - -(cosmos_proto.scalar) = "cosmos.AddressString"; - -## Implements_Interface - -Implement interface is - -option (cosmos_proto.implements_interface) = "cosmos.auth.v1beta1.AccountI"; - -## Amino - -### Name - -option (amino.name) = "cosmos-sdk/BaseAccount"; - -### Field_Name - -(amino.field_name) = "public_key" - -### Dont_OmitEmpty - -(amino.dont_omitempty) = true, - -### Encoding - -(amino.encoding) = "legacy_coins",