github.com/cosmos/cosmos-sdk@v0.50.10/docs/docs/build/building-modules/05-protobuf-annotations.md (about)

     1  ---
     2  sidebar_position: 1
     3  ---
     4  
     5  # ProtocolBuffer Annotations
     6  
     7  This document explains the various protobuf scalars that have been added to make working with protobuf easier for Cosmos SDK application developers
     8  
     9  ## Signer
    10  
    11  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.
    12  
    13  Read more about the signer field [here](./02-messages-and-queries.md).
    14  
    15  ```protobuf reference 
    16  https://github.com/cosmos/cosmos-sdk/blob/e6848d99b55a65d014375b295bdd7f9641aac95e/proto/cosmos/bank/v1beta1/tx.proto#L40
    17  ```
    18  
    19  ```proto
    20  option (cosmos.msg.v1.signer) = "from_address";
    21  ```
    22  
    23  ## Scalar
    24  
    25  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.
    26  
    27  ```proto
    28  (cosmos_proto.scalar) = "cosmos.AddressString"
    29  ```
    30  
    31  Example of account address string scalar:
    32  
    33  ```proto reference 
    34  https://github.com/cosmos/cosmos-sdk/blob/e6848d99b55a65d014375b295bdd7f9641aac95e/proto/cosmos/bank/v1beta1/tx.proto#L46
    35  ```
    36  
    37  Example of validator address string scalar: 
    38  
    39  ```proto reference 
    40  https://github.com/cosmos/cosmos-sdk/blob/e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6/proto/cosmos/distribution/v1beta1/query.proto#L87
    41  ```
    42  
    43  Example of Decimals scalar: 
    44  
    45  ```proto reference
    46  https://github.com/cosmos/cosmos-sdk/blob/e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6/proto/cosmos/distribution/v1beta1/distribution.proto#L26
    47  ```
    48  
    49  Example of Int scalar: 
    50  
    51  ```proto reference
    52  https://github.com/cosmos/cosmos-sdk/blob/e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6/proto/cosmos/gov/v1/gov.proto#L137
    53  ```
    54  
    55  There are a few options for what can be provided as a scalar: `cosmos.AddressString`, `cosmos.ValidatorAddressString`, `cosmos.ConsensusAddressString`, `cosmos.Int`, `cosmos.Dec`. 
    56  
    57  ## Implements_Interface
    58  
    59  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. 
    60  
    61  ```proto
    62  option (cosmos_proto.implements_interface) = "cosmos.auth.v1beta1.AccountI";
    63  ```
    64  
    65  ## Method,Field,Message Added In
    66  
    67  `method_added_in`, `field_added_in` and `message_added_in` are annotations to denotate to clients that a field has been supported in a later version. This is useful when new methods or fields are added in later versions and that the client needs to be aware of what it can call.
    68  
    69  The annotation should be worded as follow:
    70  
    71  ```proto
    72  option (cosmos_proto.method_added_in) = "cosmos-sdk v0.50.1";
    73  option (cosmos_proto.method_added_in) = "x/epochs v1.0.0";
    74  option (cosmos_proto.method_added_in) = "simapp v24.0.0";
    75  ```
    76  
    77  ## Amino
    78  
    79  The amino codec was removed in `v0.50+`, 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. 
    80  
    81  :::note
    82  Amino annotations are only used for backwards compatibility with amino. New modules are not required use amino annotations.
    83  :::
    84  
    85  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. 
    86  
    87  ### Name
    88  
    89  Name specifies the amino name that would show up for the user in order for them see which message they are signing.
    90  
    91  ```proto
    92  option (amino.name) = "cosmos-sdk/BaseAccount";
    93  ```
    94  
    95  ```proto reference
    96  https://github.com/cosmos/cosmos-sdk/blob/e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6/proto/cosmos/bank/v1beta1/tx.proto#L41
    97  ```
    98  
    99  ### Field_Name
   100  
   101  Field name specifies the amino name that would show up for the user in order for them see which field they are signing.
   102  
   103  ```proto
   104  uint64 height = 1 [(amino.field_name) = "public_key"];
   105  ```
   106  
   107  ```proto reference
   108  https://github.com/cosmos/cosmos-sdk/blob/e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6/proto/cosmos/distribution/v1beta1/distribution.proto#L166
   109  ```
   110  
   111  ### Dont_OmitEmpty 
   112  
   113  Dont omitempty specifies that the field should not be omitted when encoding to amino. 
   114  
   115  ```proto
   116  repeated cosmos.base.v1beta1.Coin amount = 3 [(amino.dont_omitempty)   = true];
   117  ```
   118  
   119  ```proto reference
   120  https://github.com/cosmos/cosmos-sdk/blob/e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6/proto/cosmos/bank/v1beta1/bank.proto#L56
   121  ```
   122  
   123  ### Encoding 
   124  
   125  Encoding instructs the amino json marshaler how to encode certain fields that may differ from the standard encoding behaviour. The most common example of this is how `repeated cosmos.base.v1beta1.Coin` is encoded when using the amino json encoding format. The `legacy_coins` option tells the json marshaler [how to encode a null slice](https://github.com/cosmos/cosmos-sdk/blob/e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6/x/tx/signing/aminojson/json_marshal.go#L65) of `cosmos.base.v1beta1.Coin`.
   126  
   127  ```proto
   128  (amino.encoding)         = "legacy_coins",
   129  ```
   130  
   131  ```proto reference
   132  https://github.com/cosmos/cosmos-sdk/blob/e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6/proto/cosmos/bank/v1beta1/genesis.proto#L23
   133  ```