> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmos.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Protobuf Annotations

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

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](https://github.com/cosmos/gogoproto) specific implementation of the Protobuf spec that offers speed and developer experience improvements compared to the official [Google protobuf implementation](https://github.com/protocolbuffers/protobuf).

### Guidelines for protobuf message definitions

In addition to [following official Protocol Buffer guidelines](https://developers.google.com/protocol-buffers/docs/proto3#simple), 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](/sdk/latest/learn/concepts/encoding#message-signers).

```proto theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
// 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.

```proto theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
(cosmos_proto.scalar) = "cosmos.AddressString"
```

Example of account address string scalar:

```proto theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
// 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:

```proto theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
// 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:

```proto theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
// 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:

```proto theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
// 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](https://github.com/cosmology-tech/telescope) on how to encode and decode protobuf messages.

```proto theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
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:

```proto theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
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.

<Note>
  Amino annotations are only used for backwards compatibility with amino. New modules are not required use amino annotations.
</Note>

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 theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
// 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.

```proto theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
// 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.

```proto theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
// 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](https://github.com/cosmos/cosmos-sdk/blob/release/v0.54.x/x/tx/signing/aminojson/json_marshal.go#L85) of `cosmos.base.v1beta1.Coin`.

```proto theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
// 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](https://github.com/cosmos/cosmos-sdk/blob/release/v0.54.x/proto/cosmos/query/v1/query.proto)) 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.

```proto theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
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.