Skip to main content
This document explains the various protobuf scalars that have been added to make working with protobuf easier for Cosmos SDK application developers

​
Gogoproto

Modules are encouraged to utilize Protobuf encoding for their respective types. In the Cosmos SDK, we use the Gogoproto specific implementation of the Protobuf spec that offers speed and developer experience improvements compared to the official Google protobuf implementation.

​
Guidelines for protobuf message definitions

In addition to following official Protocol Buffer guidelines, we recommend using these annotations in .proto files when dealing with interfaces:
  • Use cosmos_proto.accepts_interface to annotate Any fields that accept interfaces:
    • Pass the same fully qualified name as protoName to InterfaceRegistry.RegisterInterface.
    • Example: (cosmos_proto.accepts_interface) = "cosmos.gov.v1beta1.Content" (not just Content).
  • Annotate interface implementations with cosmos_proto.implements_interface:
    • Pass the same fully qualified name as protoName to InterfaceRegistry.RegisterInterface.
    • Example: (cosmos_proto.implements_interface) = "cosmos.authz.v1beta1.Authorization" (not just Authorization).
Code generators can then match the accepts_interface and implements_interface annotations to determine whether some Protobuf messages are allowed to be packed in a given Any field.

​
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. 
// Reference: https://github.com/cosmos/cosmos-sdk/blob/release/v0.54.x/proto/cosmos/bank/v1beta1/tx.proto#L40
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. 
(cosmos_proto.scalar) = "cosmos.AddressString"
Example of account address string scalar: 
// https://github.com/cosmos/cosmos-sdk/blob/release/v0.54.x/proto/cosmos/bank/v1beta1/tx.proto#L46
string from_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
Example of validator address string scalar: 
// https://github.com/cosmos/cosmos-sdk/blob/release/v0.54.x/proto/cosmos/distribution/v1beta1/query.proto#L108
string validator_address = 1 [(cosmos_proto.scalar) = "cosmos.ValidatorAddressString"];
Example of Dec scalar: 
// https://github.com/cosmos/cosmos-sdk/blob/release/v0.54.x/proto/cosmos/distribution/v1beta1/distribution.proto#L17
string community_tax = 1 [(cosmos_proto.scalar) = "cosmos.Dec"];
Example of Int scalar: 
// https://github.com/cosmos/cosmos-sdk/blob/release/v0.54.x/proto/cosmos/gov/v1/gov.proto#L127
string yes_count = 1 [(cosmos_proto.scalar) = "cosmos.Int"];
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 on how to encode and decode protobuf messages. 
option (cosmos_proto.implements_interface) = "cosmos.auth.v1beta1.AccountI";

​
Method,Field,Message Added In

method_added_in, field_added_in and message_added_in are annotations to indicate to clients that a method, field, or message has been supported since a later version. This is useful when new methods or fields are added in later versions and the client needs to be aware of what it can call. The annotations are used as follows: 
option (cosmos_proto.method_added_in) = "cosmos-sdk 0.50.1";
option (cosmos_proto.field_added_in) = "cosmos-sdk 0.50.1";
option (cosmos_proto.message_added_in) = "cosmos-sdk 0.50.1";

​
Amino

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

​
Name

Name specifies the amino name that would show up for the user in order for them see which message they are signing. 
// https://github.com/cosmos/cosmos-sdk/blob/release/v0.54.x/proto/cosmos/bank/v1beta1/tx.proto#L41
option (amino.name) = "cosmos-sdk/MsgSend";

​
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. 
// https://github.com/cosmos/cosmos-sdk/blob/release/v0.54.x/proto/cosmos/distribution/v1beta1/distribution.proto#L165
uint64 height = 3 [(amino.field_name) = "creation_height"];

​
Dont_OmitEmpty

Dont omitempty specifies that the field should not be omitted when encoding to amino. 
// https://github.com/cosmos/cosmos-sdk/blob/release/v0.54.x/proto/cosmos/bank/v1beta1/tx.proto#L48
repeated cosmos.base.v1beta1.Coin amount = 3 [(amino.dont_omitempty) = true];

​
Encoding

Encoding instructs the amino json marshaler how to encode certain fields that may differ from the standard encoding behavior. 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 of cosmos.base.v1beta1.Coin. 
// https://github.com/cosmos/cosmos-sdk/blob/release/v0.54.x/proto/cosmos/bank/v1beta1/genesis.proto#L23
(amino.encoding) = "legacy_coins",

​
Module Query Safe

The cosmos.query.v1.module_query_safe annotation (source) marks a query method as safe to call from within the state machine — for example from another module’s keeper, via ADR-033 intermodule calls, or from CosmWasm contracts. 
rpc Balance(QueryBalanceRequest) returns (QueryBalanceResponse) {
  option (cosmos.query.v1.module_query_safe) = true;
}
When set to true, the annotation asserts that the query is:
  1. Deterministic: given a block height, it returns the exact same response on every call and does not introduce state-machine-breaking changes across SDK patch versions.
  2. Gas-tracked: gas consumption is correctly accounted for, preventing attack vectors where high-computation queries consume no gas.
If you add this annotation to your own query, you must ensure both conditions hold. For queries that may consume significant gas (for example those with pagination that could be misconfigured), add a Protobuf comment warning downstream module developers. This annotation was introduced in v0.47.