From 717d319493077a1e6909738dbdb421474d2ac0bd Mon Sep 17 00:00:00 2001 From: marbar3778 Date: Sun, 26 Mar 2023 22:20:16 +0200 Subject: [PATCH 1/7] init --- docs/docs/building-apps/03-protobuf-annotations.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 docs/docs/building-apps/03-protobuf-annotations.md diff --git a/docs/docs/building-apps/03-protobuf-annotations.md b/docs/docs/building-apps/03-protobuf-annotations.md new file mode 100644 index 000000000000..27758f1aa622 --- /dev/null +++ b/docs/docs/building-apps/03-protobuf-annotations.md @@ -0,0 +1,7 @@ +--- +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 From 8d3649ebee99072dc6fceeb99833f7a01f306b0a Mon Sep 17 00:00:00 2001 From: marbar3778 Date: Mon, 27 Mar 2023 12:29:54 +0200 Subject: [PATCH 2/7] add layout --- .../building-apps/03-protobuf-annotations.md | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/docs/building-apps/03-protobuf-annotations.md b/docs/docs/building-apps/03-protobuf-annotations.md index 27758f1aa622..d78b43233acf 100644 --- a/docs/docs/building-apps/03-protobuf-annotations.md +++ b/docs/docs/building-apps/03-protobuf-annotations.md @@ -5,3 +5,29 @@ 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 + +## Scalars + +(cosmos_proto.scalar) = "cosmos.AddressString"; + +## Interfaces + +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", From 76996608203f3d420ca1ff407fb7585df5414371 Mon Sep 17 00:00:00 2001 From: marbar3778 Date: Mon, 27 Mar 2023 12:46:26 +0200 Subject: [PATCH 3/7] ++ --- docs/docs/building-apps/03-protobuf-annotations.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/docs/building-apps/03-protobuf-annotations.md b/docs/docs/building-apps/03-protobuf-annotations.md index d78b43233acf..c690ef18072a 100644 --- a/docs/docs/building-apps/03-protobuf-annotations.md +++ b/docs/docs/building-apps/03-protobuf-annotations.md @@ -6,11 +6,13 @@ sidebar_position: 1 This document explains the various protobuf scalars that have been added to make working with protobuf easier for Cosmos SDK application developers -## Scalars +## Scalar (cosmos_proto.scalar) = "cosmos.AddressString"; -## Interfaces +## Implements_Interface + +Implement interface is option (cosmos_proto.implements_interface) = "cosmos.auth.v1beta1.AccountI"; @@ -20,7 +22,7 @@ option (cosmos_proto.implements_interface) = "cosmos.auth.v1beta1.AccountI"; option (amino.name) = "cosmos-sdk/BaseAccount"; -### Field Name +### Field_Name (amino.field_name) = "public_key" From e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6 Mon Sep 17 00:00:00 2001 From: marbar3778 Date: Wed, 6 Sep 2023 16:35:48 +0200 Subject: [PATCH 4/7] 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", From 0422b08a9a2f946229caf6312a282d36544d1449 Mon Sep 17 00:00:00 2001 From: marbar3778 Date: Thu, 7 Sep 2023 10:34:43 +0200 Subject: [PATCH 5/7] address comments --- .../02-messages-and-queries.md | 2 +- .../05-protobuf-annotations.md | 48 +++++++++++++++++-- ...-endblock.md => 06-beginblock-endblock.md} | 0 3 files changed, 45 insertions(+), 5 deletions(-) rename docs/docs/build/{building-apps => building-modules}/05-protobuf-annotations.md (61%) rename docs/docs/build/building-modules/{05-beginblock-endblock.md => 06-beginblock-endblock.md} (100%) 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 88b4bfabb14b..1334acb0a7d8 100644 --- a/docs/docs/build/building-modules/02-messages-and-queries.md +++ b/docs/docs/build/building-modules/02-messages-and-queries.md @@ -49,7 +49,7 @@ 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). +Read more about the signer field [here](./05-protobuf-annotations.md). ```protobuf reference https://github.com/cosmos/cosmos-sdk/blob/e6848d99b55a65d014375b295bdd7f9641aac95e/proto/cosmos/bank/v1beta1/tx.proto#L40 diff --git a/docs/docs/build/building-apps/05-protobuf-annotations.md b/docs/docs/build/building-modules/05-protobuf-annotations.md similarity index 61% rename from docs/docs/build/building-apps/05-protobuf-annotations.md rename to docs/docs/build/building-modules/05-protobuf-annotations.md index 91f443494c0b..f88cd62bf5ed 100644 --- a/docs/docs/build/building-apps/05-protobuf-annotations.md +++ b/docs/docs/build/building-modules/05-protobuf-annotations.md @@ -10,7 +10,7 @@ This document explains the various protobuf scalars that have been added to make 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). +Read more about the signer field [here](./02-messages-and-queries.md). ```protobuf reference https://github.com/cosmos/cosmos-sdk/blob/e6848d99b55a65d014375b295bdd7f9641aac95e/proto/cosmos/bank/v1beta1/tx.proto#L40 @@ -28,6 +28,30 @@ The scalar type defines a way for clients to understand how to construct protobu (cosmos_proto.scalar) = "cosmos.AddressString" ``` +Example of account address string scalar: + +```proto reference +https://github.com/cosmos/cosmos-sdk/blob/e6848d99b55a65d014375b295bdd7f9641aac95e/proto/cosmos/bank/v1beta1/tx.proto#L46 +``` + +Example of validator address string scalar: + +```proto reference +https://github.com/cosmos/cosmos-sdk/blob/e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6/proto/cosmos/distribution/v1beta1/query.proto#L87 +``` + +Example of Decimals scalar: + +```proto reference +https://github.com/cosmos/cosmos-sdk/blob/e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6/proto/cosmos/distribution/v1beta1/distribution.proto#L26 +``` + +Example of Int scalar: + +```proto reference +https://github.com/cosmos/cosmos-sdk/blob/e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6/proto/cosmos/gov/v1/gov.proto#L137 +``` + 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 @@ -42,7 +66,7 @@ option (cosmos_proto.implements_interface) = "cosmos.auth.v1beta1.AccountI"; 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 +:::note Amino annotations are only used for backwards compatibility with amino. New modules should not use amino annotations. The ::: @@ -56,12 +80,20 @@ Name specifies the amino name that would show up for the user in order for them option (amino.name) = "cosmos-sdk/BaseAccount"; ``` +```proto reference +https://github.com/cosmos/cosmos-sdk/blob/e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6/proto/cosmos/bank/v1beta1/tx.proto#L41 +``` + ### 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" +uint64 height = 1 [(amino.field_name) = "public_key"]; +``` + +```proto reference +https://github.com/cosmos/cosmos-sdk/blob/e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6/proto/cosmos/distribution/v1beta1/distribution.proto#L166 ``` ### Dont_OmitEmpty @@ -69,7 +101,11 @@ Field name specifies the amino name that would show up for the user in order for Dont omitempty specifies that the field should not be omitted when encoding to amino. ```proto -(amino.dont_omitempty) = true, +repeated cosmos.base.v1beta1.Coin amount = 3 [(amino.dont_omitempty) = true]; +``` + +```proto reference +https://github.com/cosmos/cosmos-sdk/blob/e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6/proto/cosmos/bank/v1beta1/bank.proto#L56 ``` ### Encoding @@ -79,3 +115,7 @@ Encoding specifies the amino encoding that should be used when encoding to amino ```proto (amino.encoding) = "legacy_coins", ``` + +```proto reference +https://github.com/cosmos/cosmos-sdk/blob/e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6/proto/cosmos/bank/v1beta1/genesis.proto#L23 +``` diff --git a/docs/docs/build/building-modules/05-beginblock-endblock.md b/docs/docs/build/building-modules/06-beginblock-endblock.md similarity index 100% rename from docs/docs/build/building-modules/05-beginblock-endblock.md rename to docs/docs/build/building-modules/06-beginblock-endblock.md From 7352d0bce8e72121e824297df453eb1059c28da8 Mon Sep 17 00:00:00 2001 From: marbar3778 Date: Thu, 7 Sep 2023 10:55:42 +0200 Subject: [PATCH 6/7] fix --- docs/docs/build/building-modules/05-protobuf-annotations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/build/building-modules/05-protobuf-annotations.md b/docs/docs/build/building-modules/05-protobuf-annotations.md index f88cd62bf5ed..9a0f971acf12 100644 --- a/docs/docs/build/building-modules/05-protobuf-annotations.md +++ b/docs/docs/build/building-modules/05-protobuf-annotations.md @@ -67,7 +67,7 @@ option (cosmos_proto.implements_interface) = "cosmos.auth.v1beta1.AccountI"; 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 +Amino annotations are only used for backwards compatibility with amino. New modules are not required use amino annotations. ::: 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. From 61b35c70af88538918ef57cdaf0be927e0e3f06b Mon Sep 17 00:00:00 2001 From: marbar3778 Date: Thu, 7 Sep 2023 11:00:00 +0200 Subject: [PATCH 7/7] add section to upgrading md --- UPGRADING.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/UPGRADING.md b/UPGRADING.md index 1c5c238096b6..921bdb819b93 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -356,6 +356,11 @@ In case a module requires to return `abci.ValidatorUpdate` from `EndBlock`, it c + EndBlock(context.Context) ([]abci.ValidatorUpdate, error) ``` +`GetSigners()` is no longer required to be implemented on `Msg` types. The SDK will automatically infer the signers from the `Signer` field on the message. The signer field is required on all messages unless using a custom signer function. + + +To find out more please read the [signer field](./05-protobuf-annotations.md#signer) & [here](https://github.com/cosmos/cosmos-sdk/blob/7352d0bce8e72121e824297df453eb1059c28da8/docs/docs/build/building-modules/02-messages-and-queries.md#L40)documentation. + #### `x/auth` For ante handler construction via `ante.NewAnteHandler`, the field `ante.HandlerOptions.SignModeHandler` has been updated to `x/tx/signing/HandlerMap` from `x/auth/signing/SignModeHandler`. Callers typically fetch this value from `client.TxConfig.SignModeHandler()` (which is also changed) so this change should be transparent to most users.