> ## 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.
# Staking
> gRPC queries and transaction messages defined by the staking module in Cosmos SDK v0.55 (unreleased).
Generated from [`cosmos/cosmos-sdk@c1126e4e5460`](https://github.com/cosmos/cosmos-sdk/tree/c1126e4e5460571378bf9bd9c49cce476b0791e2/proto) on ref `main`.
## Queries
A node exposes only the services its application registers:
* gRPC on port 9090
* REST on port 1317, if the method has an HTTP binding
Run `grpcurl -plaintext localhost:9090 list` to see what a node serves.
Queries are read-only and never pass through consensus. See [Queries](/sdk/next/learn/concepts/transactions#queries).
Replace `` placeholders with real values and omit unused filters. Payloads use protobuf JSON, and some `string` fields accept enum constants listed under Types. Field tables give the encoding each value takes.
Examples assume a local node. For TLS endpoints, use port 443 and omit `-plaintext`. See [gRPC services](/sdk/next/api-reference/grpc/index) for reflection, address formats, and decimal encoding.
### Delegation
Delegation queries delegate info for given validator delegator pair.
| | |
| ---- | ------------------------------------------------------------------------------------ |
| gRPC | `cosmos.staking.v1beta1.Query/Delegation` |
| REST | `GET /cosmos/staking/v1beta1/validators/{validatorAddr}/delegations/{delegatorAddr}` |
Request `QueryDelegationRequest`:
| Field | Type | Description |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `delegator_addr` | `string` | delegator\_addr defines the delegator address to query for. Encoded as cosmos.AddressString. |
| `validator_addr` | `string` | validator\_addr defines the validator address to query for. Encoded as cosmos.ValidatorAddressString. |
Response `QueryDelegationResponse`:
| Field | Type | Description |
| --------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `delegation_response` | [`DelegationResponse`](#cosmos-staking-v1beta1-delegationresponse) | delegation\_responses defines the delegation info of a delegation. |
```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext -d '{"delegator_addr":"","validator_addr":""}' \
localhost:9090 cosmos.staking.v1beta1.Query/Delegation
```
### DelegatorDelegations
DelegatorDelegations queries all delegations of a given delegator address.
When called from another module, this query might consume a high amount of gas if the pagination field is incorrectly set.
| | |
| ---- | --------------------------------------------------------- |
| gRPC | `cosmos.staking.v1beta1.Query/DelegatorDelegations` |
| REST | `GET /cosmos/staking/v1beta1/delegations/{delegatorAddr}` |
Request `QueryDelegatorDelegationsRequest`:
| Field | Type | Description |
| ---------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `delegator_addr` | `string` | delegator\_addr defines the delegator address to query for. Encoded as cosmos.AddressString. |
| `pagination` | [`PageRequest`](#cosmos-base-query-v1beta1-pagerequest) | pagination defines an optional pagination for the request. |
Response `QueryDelegatorDelegationsResponse`:
| Field | Type | Description |
| ---------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `delegation_responses` | [`DelegationResponse`](#cosmos-staking-v1beta1-delegationresponse)\[] | delegation\_responses defines all the delegations' info of a delegator. |
| `pagination` | [`PageResponse`](#cosmos-base-query-v1beta1-pageresponse) | pagination defines the pagination in the response. |
```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext -d '{"delegator_addr":"","pagination":{"limit":"1"}}' \
localhost:9090 cosmos.staking.v1beta1.Query/DelegatorDelegations
```
### DelegatorUnbondingDelegations
DelegatorUnbondingDelegations queries all unbonding delegations of a given delegator address.
When called from another module, this query might consume a high amount of gas if the pagination field is incorrectly set.
| | |
| ---- | ------------------------------------------------------------------------------ |
| gRPC | `cosmos.staking.v1beta1.Query/DelegatorUnbondingDelegations` |
| REST | `GET /cosmos/staking/v1beta1/delegators/{delegatorAddr}/unbonding_delegations` |
Request `QueryDelegatorUnbondingDelegationsRequest`:
| Field | Type | Description |
| ---------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `delegator_addr` | `string` | delegator\_addr defines the delegator address to query for. Encoded as cosmos.AddressString. |
| `pagination` | [`PageRequest`](#cosmos-base-query-v1beta1-pagerequest) | pagination defines an optional pagination for the request. |
Response `QueryDelegatorUnbondingDelegationsResponse`:
| Field | Type | Description |
| --------------------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
| `unbonding_responses` | [`UnbondingDelegation`](#cosmos-staking-v1beta1-unbondingdelegation)\[] | |
| `pagination` | [`PageResponse`](#cosmos-base-query-v1beta1-pageresponse) | pagination defines the pagination in the response. |
```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext -d '{"delegator_addr":"","pagination":{"limit":"1"}}' \
localhost:9090 cosmos.staking.v1beta1.Query/DelegatorUnbondingDelegations
```
### DelegatorValidator
DelegatorValidator queries validator info for given delegator validator pair.
| | |
| ---- | ----------------------------------------------------------------------------------- |
| gRPC | `cosmos.staking.v1beta1.Query/DelegatorValidator` |
| REST | `GET /cosmos/staking/v1beta1/delegators/{delegatorAddr}/validators/{validatorAddr}` |
Request `QueryDelegatorValidatorRequest`:
| Field | Type | Description |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `delegator_addr` | `string` | delegator\_addr defines the delegator address to query for. Encoded as cosmos.AddressString. |
| `validator_addr` | `string` | validator\_addr defines the validator address to query for. Encoded as cosmos.ValidatorAddressString. |
Response `QueryDelegatorValidatorResponse`:
| Field | Type | Description |
| ----------- | ------------------------------------------------ | ------------------------------------- |
| `validator` | [`Validator`](#cosmos-staking-v1beta1-validator) | validator defines the validator info. |
```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext -d '{"delegator_addr":"","validator_addr":""}' \
localhost:9090 cosmos.staking.v1beta1.Query/DelegatorValidator
```
### DelegatorValidators
DelegatorValidators queries all validators info for given delegator address.
When called from another module, this query might consume a high amount of gas if the pagination field is incorrectly set.
| | |
| ---- | ------------------------------------------------------------------- |
| gRPC | `cosmos.staking.v1beta1.Query/DelegatorValidators` |
| REST | `GET /cosmos/staking/v1beta1/delegators/{delegatorAddr}/validators` |
Request `QueryDelegatorValidatorsRequest`:
| Field | Type | Description |
| ---------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `delegator_addr` | `string` | delegator\_addr defines the delegator address to query for. Encoded as cosmos.AddressString. |
| `pagination` | [`PageRequest`](#cosmos-base-query-v1beta1-pagerequest) | pagination defines an optional pagination for the request. |
Response `QueryDelegatorValidatorsResponse`:
| Field | Type | Description |
| ------------ | --------------------------------------------------------- | ------------------------------------------------------- |
| `validators` | [`Validator`](#cosmos-staking-v1beta1-validator)\[] | validators defines the validators' info of a delegator. |
| `pagination` | [`PageResponse`](#cosmos-base-query-v1beta1-pageresponse) | pagination defines the pagination in the response. |
```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext -d '{"delegator_addr":"","pagination":{"limit":"1"}}' \
localhost:9090 cosmos.staking.v1beta1.Query/DelegatorValidators
```
### HistoricalInfo
HistoricalInfo queries the historical info for given height.
| | |
| ---- | ------------------------------------------------------ |
| gRPC | `cosmos.staking.v1beta1.Query/HistoricalInfo` |
| REST | `GET /cosmos/staking/v1beta1/historical_info/{height}` |
Request `QueryHistoricalInfoRequest`:
| Field | Type | Description |
| -------- | ------- | ------------------------------------------------------------ |
| `height` | `int64` | height defines at which height to query the historical info. |
Response `QueryHistoricalInfoResponse`:
| Field | Type | Description |
| ------ | ---------------------------------------------------------- | ----------------------------------------------------- |
| `hist` | [`HistoricalInfo`](#cosmos-staking-v1beta1-historicalinfo) | hist defines the historical info at the given height. |
```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext -d '{"height":"1"}' \
localhost:9090 cosmos.staking.v1beta1.Query/HistoricalInfo
```
### Params
Parameters queries the staking parameters.
| | |
| ---- | ------------------------------------- |
| gRPC | `cosmos.staking.v1beta1.Query/Params` |
| REST | `GET /cosmos/staking/v1beta1/params` |
Request `QueryParamsRequest`:
This message has no fields.
Response `QueryParamsResponse`:
| Field | Type | Description |
| -------- | ------------------------------------------ | ----------------------------------------------- |
| `params` | [`Params`](#cosmos-staking-v1beta1-params) | params holds all the parameters of this module. |
```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext localhost:9090 cosmos.staking.v1beta1.Query/Params
```
### Pool
Pool queries the pool info.
| | |
| ---- | ----------------------------------- |
| gRPC | `cosmos.staking.v1beta1.Query/Pool` |
| REST | `GET /cosmos/staking/v1beta1/pool` |
Request `QueryPoolRequest`:
This message has no fields.
Response `QueryPoolResponse`:
| Field | Type | Description |
| ------ | -------------------------------------- | --------------------------- |
| `pool` | [`Pool`](#cosmos-staking-v1beta1-pool) | pool defines the pool info. |
```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext localhost:9090 cosmos.staking.v1beta1.Query/Pool
```
### Redelegations
Redelegations queries redelegations of given address.
When called from another module, this query might consume a high amount of gas if the pagination field is incorrectly set.
| | |
| ---- | ---------------------------------------------------------------------- |
| gRPC | `cosmos.staking.v1beta1.Query/Redelegations` |
| REST | `GET /cosmos/staking/v1beta1/delegators/{delegatorAddr}/redelegations` |
Request `QueryRedelegationsRequest`:
| Field | Type | Description |
| -------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `delegator_addr` | `string` | delegator\_addr defines the delegator address to query for. Encoded as cosmos.AddressString. |
| `src_validator_addr` | `string` | src\_validator\_addr defines the validator address to redelegate from. Encoded as cosmos.ValidatorAddressString. |
| `dst_validator_addr` | `string` | dst\_validator\_addr defines the validator address to redelegate to. Encoded as cosmos.ValidatorAddressString. |
| `pagination` | [`PageRequest`](#cosmos-base-query-v1beta1-pagerequest) | pagination defines an optional pagination for the request. |
Response `QueryRedelegationsResponse`:
| Field | Type | Description |
| ------------------------ | ------------------------------------------------------------------------- | -------------------------------------------------- |
| `redelegation_responses` | [`RedelegationResponse`](#cosmos-staking-v1beta1-redelegationresponse)\[] | |
| `pagination` | [`PageResponse`](#cosmos-base-query-v1beta1-pageresponse) | pagination defines the pagination in the response. |
```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext -d '{"delegator_addr":"","src_validator_addr":"","dst_validator_addr":"","pagination":{"limit":"1"}}' \
localhost:9090 cosmos.staking.v1beta1.Query/Redelegations
```
### UnbondingDelegation
UnbondingDelegation queries unbonding info for given validator delegator pair.
| | |
| ---- | --------------------------------------------------------------------------------------------------------- |
| gRPC | `cosmos.staking.v1beta1.Query/UnbondingDelegation` |
| REST | `GET /cosmos/staking/v1beta1/validators/{validatorAddr}/delegations/{delegatorAddr}/unbonding_delegation` |
Request `QueryUnbondingDelegationRequest`:
| Field | Type | Description |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `delegator_addr` | `string` | delegator\_addr defines the delegator address to query for. Encoded as cosmos.AddressString. |
| `validator_addr` | `string` | validator\_addr defines the validator address to query for. Encoded as cosmos.ValidatorAddressString. |
Response `QueryUnbondingDelegationResponse`:
| Field | Type | Description |
| -------- | -------------------------------------------------------------------- | --------------------------------------------------------- |
| `unbond` | [`UnbondingDelegation`](#cosmos-staking-v1beta1-unbondingdelegation) | unbond defines the unbonding information of a delegation. |
```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext -d '{"delegator_addr":"","validator_addr":""}' \
localhost:9090 cosmos.staking.v1beta1.Query/UnbondingDelegation
```
### Validator
Validator queries validator info for given validator address.
| | |
| ---- | -------------------------------------------------------- |
| gRPC | `cosmos.staking.v1beta1.Query/Validator` |
| REST | `GET /cosmos/staking/v1beta1/validators/{validatorAddr}` |
Request `QueryValidatorRequest`:
| Field | Type | Description |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `validator_addr` | `string` | validator\_addr defines the validator address to query for. Encoded as cosmos.ValidatorAddressString. |
Response `QueryValidatorResponse`:
| Field | Type | Description |
| ----------- | ------------------------------------------------ | ------------------------------------- |
| `validator` | [`Validator`](#cosmos-staking-v1beta1-validator) | validator defines the validator info. |
```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext -d '{"validator_addr":""}' \
localhost:9090 cosmos.staking.v1beta1.Query/Validator
```
### ValidatorDelegations
ValidatorDelegations queries delegate info for given validator.
When called from another module, this query might consume a high amount of gas if the pagination field is incorrectly set.
| | |
| ---- | -------------------------------------------------------------------- |
| gRPC | `cosmos.staking.v1beta1.Query/ValidatorDelegations` |
| REST | `GET /cosmos/staking/v1beta1/validators/{validatorAddr}/delegations` |
Request `QueryValidatorDelegationsRequest`:
| Field | Type | Description |
| ---------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `validator_addr` | `string` | validator\_addr defines the validator address to query for. Encoded as cosmos.ValidatorAddressString. |
| `pagination` | [`PageRequest`](#cosmos-base-query-v1beta1-pagerequest) | pagination defines an optional pagination for the request. |
Response `QueryValidatorDelegationsResponse`:
| Field | Type | Description |
| ---------------------- | --------------------------------------------------------------------- | -------------------------------------------------- |
| `delegation_responses` | [`DelegationResponse`](#cosmos-staking-v1beta1-delegationresponse)\[] | |
| `pagination` | [`PageResponse`](#cosmos-base-query-v1beta1-pageresponse) | pagination defines the pagination in the response. |
```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext -d '{"validator_addr":"","pagination":{"limit":"1"}}' \
localhost:9090 cosmos.staking.v1beta1.Query/ValidatorDelegations
```
### Validators
Validators queries all validators that match the given status.
When called from another module, this query might consume a high amount of gas if the pagination field is incorrectly set.
| | |
| ---- | ----------------------------------------- |
| gRPC | `cosmos.staking.v1beta1.Query/Validators` |
| REST | `GET /cosmos/staking/v1beta1/validators` |
Request `QueryValidatorsRequest`:
| Field | Type | Description |
| ------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | `string` | status enables to query for validators matching a given status. One of the [`BondStatus`](#cosmos-staking-v1beta1-bondstatus) values. |
| `pagination` | [`PageRequest`](#cosmos-base-query-v1beta1-pagerequest) | pagination defines an optional pagination for the request. |
Response `QueryValidatorsResponse`:
| Field | Type | Description |
| ------------ | --------------------------------------------------------- | -------------------------------------------------- |
| `validators` | [`Validator`](#cosmos-staking-v1beta1-validator)\[] | validators contains all the queried validators. |
| `pagination` | [`PageResponse`](#cosmos-base-query-v1beta1-pageresponse) | pagination defines the pagination in the response. |
```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext -d '{"status":"BOND_STATUS_UNBONDED","pagination":{"limit":"1"}}' \
localhost:9090 cosmos.staking.v1beta1.Query/Validators
```
### ValidatorUnbondingDelegations
ValidatorUnbondingDelegations queries unbonding delegations of a validator.
When called from another module, this query might consume a high amount of gas if the pagination field is incorrectly set.
| | |
| ---- | ------------------------------------------------------------------------------ |
| gRPC | `cosmos.staking.v1beta1.Query/ValidatorUnbondingDelegations` |
| REST | `GET /cosmos/staking/v1beta1/validators/{validatorAddr}/unbonding_delegations` |
Request `QueryValidatorUnbondingDelegationsRequest`:
| Field | Type | Description |
| ---------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `validator_addr` | `string` | validator\_addr defines the validator address to query for. Encoded as cosmos.ValidatorAddressString. |
| `pagination` | [`PageRequest`](#cosmos-base-query-v1beta1-pagerequest) | pagination defines an optional pagination for the request. |
Response `QueryValidatorUnbondingDelegationsResponse`:
| Field | Type | Description |
| --------------------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
| `unbonding_responses` | [`UnbondingDelegation`](#cosmos-staking-v1beta1-unbondingdelegation)\[] | |
| `pagination` | [`PageResponse`](#cosmos-base-query-v1beta1-pageresponse) | pagination defines the pagination in the response. |
```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext -d '{"validator_addr":"","pagination":{"limit":"1"}}' \
localhost:9090 cosmos.staking.v1beta1.Query/ValidatorUnbondingDelegations
```
## Transaction messages
These messages are included in signed transactions, not called as endpoints. See [Transactions](/sdk/next/learn/concepts/transactions#transactions) for the execution model, and [Sending transactions](/sdk/next/api-reference/transactions) for the envelope they go into.
Examples use CLI transaction JSON. Decimal fields use values such as `"0.05"`, even when their proto type is `bytes`. The gRPC `TxEncode` method instead requires the scaled value `"50000000000000000"`. See [scalar encodings](/sdk/next/api-reference/grpc/index#scalar-encodings).
* Handler: Generated client method
* Signer: Account that must sign
* Amino name: Legacy identifier used by hardware wallets and other Amino signers
### BeginRedelegate
BeginRedelegate defines a method for performing a redelegation of coins from a delegator and source validator to a destination validator.
| | |
| ---------- | -------------------------------------------- |
| Type URL | `/cosmos.staking.v1beta1.MsgBeginRedelegate` |
| Handler | `cosmos.staking.v1beta1.Msg/BeginRedelegate` |
| Signer | `delegator_address` |
| Amino name | `cosmos-sdk/MsgBeginRedelegate` |
| Field | Type | Description |
| ----------------------- | ----------------------------------- | ----------------------------------------- |
| `delegator_address` | `string` | Encoded as cosmos.AddressString. |
| `validator_src_address` | `string` | Encoded as cosmos.ValidatorAddressString. |
| `validator_dst_address` | `string` | Encoded as cosmos.ValidatorAddressString. |
| `amount` | [`Coin`](#cosmos-base-v1beta1-coin) | |
In a transaction:
```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
"@type": "/cosmos.staking.v1beta1.MsgBeginRedelegate",
"delegator_address": "",
"validator_src_address": "",
"validator_dst_address": "",
"amount": {
"denom": "",
"amount": ""
}
}
```
Response `MsgBeginRedelegateResponse`:
| Field | Type | Description |
| ----------------- | ----------- | ----------- |
| `completion_time` | `Timestamp` | |
### CancelUnbondingDelegation
CancelUnbondingDelegation defines a method for performing canceling the unbonding delegation and delegate back to previous validator.
| | |
| ---------- | ------------------------------------------------------ |
| Type URL | `/cosmos.staking.v1beta1.MsgCancelUnbondingDelegation` |
| Handler | `cosmos.staking.v1beta1.Msg/CancelUnbondingDelegation` |
| Signer | `delegator_address` |
| Amino name | `cosmos-sdk/MsgCancelUnbondingDelegation` |
| Field | Type | Description |
| ------------------- | ----------------------------------- | ------------------------------------------------------------------------- |
| `delegator_address` | `string` | Encoded as cosmos.AddressString. |
| `validator_address` | `string` | Encoded as cosmos.ValidatorAddressString. |
| `amount` | [`Coin`](#cosmos-base-v1beta1-coin) | amount is always less than or equal to unbonding delegation entry balance |
| `creation_height` | `int64` | creation\_height is the height which the unbonding took place. |
In a transaction:
```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
"@type": "/cosmos.staking.v1beta1.MsgCancelUnbondingDelegation",
"delegator_address": "",
"validator_address": "",
"amount": {
"denom": "",
"amount": ""
},
"creation_height": "1"
}
```
Response `MsgCancelUnbondingDelegationResponse`:
This message has no fields.
### CreateValidator
CreateValidator defines a method for creating a new validator.
| | |
| ---------- | -------------------------------------------- |
| Type URL | `/cosmos.staking.v1beta1.MsgCreateValidator` |
| Handler | `cosmos.staking.v1beta1.Msg/CreateValidator` |
| Signer | `validator_address` |
| Amino name | `cosmos-sdk/MsgCreateValidator` |
| Field | Type | Description |
| --------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `description` | [`Description`](#cosmos-staking-v1beta1-description) | |
| `commission` | [`CommissionRates`](#cosmos-staking-v1beta1-commissionrates) | |
| `min_self_delegation` | `string` | Encoded as cosmos.Int. |
| `delegator_address` | `string` | Deprecated: Use of Delegator Address in MsgCreateValidator is deprecated. The validator address bytes and delegator address bytes refer to the same account while creating validator (defer only in bech32 notation). Deprecated. Encoded as cosmos.AddressString. |
| `validator_address` | `string` | Encoded as cosmos.ValidatorAddressString. |
| `pubkey` | `Any` | Accepts any message implementing cosmos.crypto.PubKey. |
| `value` | [`Coin`](#cosmos-base-v1beta1-coin) | |
In a transaction:
```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
"@type": "/cosmos.staking.v1beta1.MsgCreateValidator",
"description": {
"moniker": "",
"identity": "",
"website": "",
"security_contact": "",
"details": ""
},
"commission": {
"rate": "",
"max_rate": "",
"max_change_rate": ""
},
"min_self_delegation": "",
"validator_address": "",
"pubkey": {
"@type": "/cosmos.example.v1.MsgExample",
"...": "the fields of that message, inline"
},
"value": {
"denom": "",
"amount": ""
}
}
```
Response `MsgCreateValidatorResponse`:
This message has no fields.
### Delegate
Delegate defines a method for performing a delegation of coins from a delegator to a validator.
| | |
| ---------- | ------------------------------------- |
| Type URL | `/cosmos.staking.v1beta1.MsgDelegate` |
| Handler | `cosmos.staking.v1beta1.Msg/Delegate` |
| Signer | `delegator_address` |
| Amino name | `cosmos-sdk/MsgDelegate` |
| Field | Type | Description |
| ------------------- | ----------------------------------- | ----------------------------------------- |
| `delegator_address` | `string` | Encoded as cosmos.AddressString. |
| `validator_address` | `string` | Encoded as cosmos.ValidatorAddressString. |
| `amount` | [`Coin`](#cosmos-base-v1beta1-coin) | |
In a transaction:
```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
"@type": "/cosmos.staking.v1beta1.MsgDelegate",
"delegator_address": "",
"validator_address": "",
"amount": {
"denom": "",
"amount": ""
}
}
```
Response `MsgDelegateResponse`:
This message has no fields.
### EditValidator
EditValidator defines a method for editing an existing validator.
| | |
| ---------- | ------------------------------------------ |
| Type URL | `/cosmos.staking.v1beta1.MsgEditValidator` |
| Handler | `cosmos.staking.v1beta1.Msg/EditValidator` |
| Signer | `validator_address` |
| Amino name | `cosmos-sdk/MsgEditValidator` |
| Field | Type | Description |
| --------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `description` | [`Description`](#cosmos-staking-v1beta1-description) | |
| `validator_address` | `string` | Encoded as cosmos.ValidatorAddressString. |
| `commission_rate` | `string` | We pass a reference to the new commission rate and min self delegation as it's not mandatory to update. If not updated, the deserialized rate will be zero with no way to distinguish if an update was intended. REF: #2373 Encoded as cosmos.Dec, read back as an integer string scaled by 10^18 over gRPC. |
| `min_self_delegation` | `string` | Encoded as cosmos.Int. |
In a transaction:
```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
"@type": "/cosmos.staking.v1beta1.MsgEditValidator",
"description": {
"moniker": "",
"identity": "",
"website": "",
"security_contact": "",
"details": ""
},
"validator_address": "",
"commission_rate": "",
"min_self_delegation": ""
}
```
Response `MsgEditValidatorResponse`:
This message has no fields.
### RotateConsPubKey
RotateConsPubKey defines an operation for rotating the consensus keys of a validator.
| | |
| ---------- | --------------------------------------------- |
| Type URL | `/cosmos.staking.v1beta1.MsgRotateConsPubKey` |
| Handler | `cosmos.staking.v1beta1.Msg/RotateConsPubKey` |
| Signer | `validator_address` |
| Amino name | `cosmos-sdk/MsgRotateConsPubKey` |
| Field | Type | Description |
| ------------------- | -------- | ------------------------------------------------------ |
| `validator_address` | `string` | Encoded as cosmos.ValidatorAddressString. |
| `new_pubkey` | `Any` | Accepts any message implementing cosmos.crypto.PubKey. |
In a transaction:
```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
"@type": "/cosmos.staking.v1beta1.MsgRotateConsPubKey",
"validator_address": "",
"new_pubkey": {
"@type": "/cosmos.example.v1.MsgExample",
"...": "the fields of that message, inline"
}
}
```
Response `MsgRotateConsPubKeyResponse`:
This message has no fields.
### Undelegate
Undelegate defines a method for performing an undelegation from a delegate and a validator.
| | |
| ---------- | --------------------------------------- |
| Type URL | `/cosmos.staking.v1beta1.MsgUndelegate` |
| Handler | `cosmos.staking.v1beta1.Msg/Undelegate` |
| Signer | `delegator_address` |
| Amino name | `cosmos-sdk/MsgUndelegate` |
| Field | Type | Description |
| ------------------- | ----------------------------------- | ----------------------------------------- |
| `delegator_address` | `string` | Encoded as cosmos.AddressString. |
| `validator_address` | `string` | Encoded as cosmos.ValidatorAddressString. |
| `amount` | [`Coin`](#cosmos-base-v1beta1-coin) | |
In a transaction:
```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
"@type": "/cosmos.staking.v1beta1.MsgUndelegate",
"delegator_address": "",
"validator_address": "",
"amount": {
"denom": "",
"amount": ""
}
}
```
Response `MsgUndelegateResponse`:
| Field | Type | Description |
| ----------------- | ----------------------------------- | ---------------------------------------------- |
| `completion_time` | `Timestamp` | |
| `amount` | [`Coin`](#cosmos-base-v1beta1-coin) | amount returns the amount of undelegated coins |
### UpdateParams
UpdateParams defines an operation for updating the x/staking module parameters.
| | |
| ---------- | ----------------------------------------- |
| Type URL | `/cosmos.staking.v1beta1.MsgUpdateParams` |
| Handler | `cosmos.staking.v1beta1.Msg/UpdateParams` |
| Signer | `authority` |
| Amino name | `cosmos-sdk/x/staking/MsgUpdateParams` |
The signer is the governance module account, which no user holds a key for. This message executes only through a passed governance proposal, not as a transaction you submit directly.
| Field | Type | Description |
| ----------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `authority` | `string` | authority is the address that controls the module (defaults to x/gov unless overwritten). Encoded as cosmos.AddressString. |
| `params` | [`Params`](#cosmos-staking-v1beta1-params) | params defines the x/staking parameters to update. NOTE: All parameters must be supplied. |
In a transaction:
```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
"@type": "/cosmos.staking.v1beta1.MsgUpdateParams",
"authority": "",
"params": {
"unbonding_time": "0s",
"max_validators": 0,
"max_entries": 0,
"historical_entries": 0,
"bond_denom": "",
"min_commission_rate": "",
"key_rotation_fee": {
"denom": "",
"amount": ""
}
}
}
```
Response `MsgUpdateParamsResponse`:
This message has no fields.
## Types
Messages referenced by the fields above. Protocol buffers version 3 has no required fields, so every field is optional on the wire, and a `[]` suffix marks a repeated field.
### cosmos.base.query.v1beta1.PageRequest
PageRequest is to be embedded in gRPC request messages for efficient pagination. Ex:
`message SomeRequest { Foo some_parameter = 1; PageRequest pagination = 2; }`
| Field | Type | Description |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `key` | `bytes` | key is a value returned in PageResponse.next\_key to begin querying the next page most efficiently. Only one of offset or key should be set. |
| `offset` | `uint64` | offset is a numeric offset that can be used when key is unavailable. It is less efficient than using key. Only one of offset or key should be set. |
| `limit` | `uint64` | limit is the total number of results to be returned in the result page. If left empty it will default to a value to be set by each app. |
| `count_total` | `bool` | count\_total is set to true to indicate that the result set should include a count of the total number of items available for pagination in UIs. count\_total is only respected when offset is used. It is ignored when key is set. |
| `reverse` | `bool` | reverse is set to true if results are to be returned in the descending order. |
### cosmos.base.query.v1beta1.PageResponse
PageResponse is to be embedded in gRPC response messages where the corresponding request message has used PageRequest.
`message SomeResponse { repeated Bar results = 1; PageResponse page = 2; }`
| Field | Type | Description |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `next_key` | `bytes` | next\_key is the key to be passed to PageRequest.key to query the next page most efficiently. It will be empty if there are no more results. |
| `total` | `uint64` | total is total number of results available if PageRequest.count\_total was set, its value is undefined otherwise |
### cosmos.base.v1beta1.Coin
Coin defines a token with a denomination and an amount.
NOTE: The amount field is an Int which implements the custom method signatures required by gogoproto.
| Field | Type | Description |
| -------- | -------- | ---------------------- |
| `denom` | `string` | |
| `amount` | `string` | Encoded as cosmos.Int. |
### cosmos.staking.v1beta1.BondStatus
Written as a quoted string in JSON.
| Value | |
| ------------------------- | ------------------------------- |
| `BOND_STATUS_UNSPECIFIED` | Zero value. Handlers reject it. |
| `BOND_STATUS_UNBONDED` | |
| `BOND_STATUS_UNBONDING` | |
| `BOND_STATUS_BONDED` | |
### cosmos.staking.v1beta1.Commission
Commission defines commission parameters for a given validator.
| Field | Type | Description |
| ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| `commission_rates` | [`CommissionRates`](#cosmos-staking-v1beta1-commissionrates) | commission\_rates defines the initial commission rates to be used for creating a validator. |
| `update_time` | `Timestamp` | update\_time is the last time the commission rate was changed. |
### cosmos.staking.v1beta1.CommissionRates
CommissionRates defines the initial commission rates to be used for creating a validator.
| Field | Type | Description |
| ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rate` | `string` | rate is the commission rate charged to delegators, as a fraction. Encoded as cosmos.Dec, read back as an integer string scaled by 10^18 over gRPC. |
| `max_rate` | `string` | max\_rate defines the maximum commission rate which validator can ever charge, as a fraction. Encoded as cosmos.Dec, read back as an integer string scaled by 10^18 over gRPC. |
| `max_change_rate` | `string` | max\_change\_rate defines the maximum daily increase of the validator commission, as a fraction. Encoded as cosmos.Dec, read back as an integer string scaled by 10^18 over gRPC. |
### cosmos.staking.v1beta1.Delegation
Delegation represents the bond with tokens held by an account. It is owned by one delegator, and is associated with the voting power of one validator.
| Field | Type | Description |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `delegator_address` | `string` | delegator\_address is the encoded address of the delegator. Encoded as cosmos.AddressString. |
| `validator_address` | `string` | validator\_address is the encoded address of the validator. Encoded as cosmos.ValidatorAddressString. |
| `shares` | `string` | shares define the delegation shares received. Encoded as cosmos.Dec, read back as an integer string scaled by 10^18 over gRPC. |
### cosmos.staking.v1beta1.DelegationResponse
DelegationResponse is equivalent to Delegation except that it contains a balance in addition to shares which is more suitable for client responses.
| Field | Type | Description |
| ------------ | -------------------------------------------------- | ----------- |
| `delegation` | [`Delegation`](#cosmos-staking-v1beta1-delegation) | |
| `balance` | [`Coin`](#cosmos-base-v1beta1-coin) | |
### cosmos.staking.v1beta1.Description
Description defines a validator description.
| Field | Type | Description |
| ------------------ | -------- | ----------------------------------------------------------------------- |
| `moniker` | `string` | moniker defines a human-readable name for the validator. |
| `identity` | `string` | identity defines an optional identity signature (ex. UPort or Keybase). |
| `website` | `string` | website defines an optional website link. |
| `security_contact` | `string` | security\_contact defines an optional email for security contact. |
| `details` | `string` | details define other optional details. |
### cosmos.staking.v1beta1.HistoricalInfo
HistoricalInfo contains header and validator information for a given block. It is stored as part of staking module's state, which persists the `n` most recent HistoricalInfo (`n` is set by the staking module's `historical_entries` parameter).
| Field | Type | Description |
| -------- | --------------------------------------------------- | ----------- |
| `header` | `Header` | |
| `valset` | [`Validator`](#cosmos-staking-v1beta1-validator)\[] | |
### cosmos.staking.v1beta1.Params
Params defines the parameters for the x/staking module.
| Field | Type | Description |
| --------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `unbonding_time` | `Duration` | unbonding\_time is the time duration of unbonding. |
| `max_validators` | `uint32` | max\_validators is the maximum number of validators. |
| `max_entries` | `uint32` | max\_entries is the max entries for either unbonding delegation or redelegation (per pair/trio). |
| `historical_entries` | `uint32` | historical\_entries is the number of historical entries to persist. |
| `bond_denom` | `string` | bond\_denom defines the bondable coin denomination. |
| `min_commission_rate` | `string` | min\_commission\_rate is the chain-wide minimum commission rate that a validator can charge their delegators Encoded as cosmos.Dec, read back as an integer string scaled by 10^18 over gRPC. |
| `key_rotation_fee` | [`Coin`](#cosmos-base-v1beta1-coin) | key\_rotation\_fee is the fee charged when rotating a validator's consensus key. |
### cosmos.staking.v1beta1.Pool
Pool is used for tracking bonded and not-bonded token supply of the bond denomination.
| Field | Type | Description |
| ------------------- | -------- | ---------------------- |
| `not_bonded_tokens` | `string` | Encoded as cosmos.Int. |
| `bonded_tokens` | `string` | Encoded as cosmos.Int. |
### cosmos.staking.v1beta1.Redelegation
Redelegation contains the list of a particular delegator's redelegating bonds from a particular source validator to a particular destination validator.
| Field | Type | Description |
| ----------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `delegator_address` | `string` | delegator\_address is the bech32-encoded address of the delegator. Encoded as cosmos.AddressString. |
| `validator_src_address` | `string` | validator\_src\_address is the validator redelegation source operator address. Encoded as cosmos.ValidatorAddressString. |
| `validator_dst_address` | `string` | validator\_dst\_address is the validator redelegation destination operator address. Encoded as cosmos.ValidatorAddressString. |
| `entries` | [`RedelegationEntry`](#cosmos-staking-v1beta1-redelegationentry)\[] | entries are the redelegation entries. |
### cosmos.staking.v1beta1.RedelegationEntry
RedelegationEntry defines a redelegation object with relevant metadata.
| Field | Type | Description |
| ----------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `creation_height` | `int64` | creation\_height defines the height which the redelegation took place. |
| `completion_time` | `Timestamp` | completion\_time defines the unix time for redelegation completion. |
| `initial_balance` | `string` | initial\_balance defines the initial balance when redelegation started. Encoded as cosmos.Int. |
| `shares_dst` | `string` | shares\_dst is the amount of destination-validator shares created by redelegation. Encoded as cosmos.Dec, read back as an integer string scaled by 10^18 over gRPC. |
| `unbonding_id` | `uint64` | Incrementing id that uniquely identifies this entry |
| `unbonding_on_hold_ref_count` | `int64` | Strictly positive if this entry's unbonding has been stopped by external modules |
### cosmos.staking.v1beta1.RedelegationEntryResponse
RedelegationEntryResponse is equivalent to a RedelegationEntry except that it contains a balance in addition to shares which is more suitable for client responses.
| Field | Type | Description |
| -------------------- | ---------------------------------------------------------------- | ---------------------- |
| `redelegation_entry` | [`RedelegationEntry`](#cosmos-staking-v1beta1-redelegationentry) | |
| `balance` | `string` | Encoded as cosmos.Int. |
### cosmos.staking.v1beta1.RedelegationResponse
RedelegationResponse is equivalent to a Redelegation except that its entries contain a balance in addition to shares which is more suitable for client responses.
| Field | Type | Description |
| -------------- | ----------------------------------------------------------------------------------- | ----------- |
| `redelegation` | [`Redelegation`](#cosmos-staking-v1beta1-redelegation) | |
| `entries` | [`RedelegationEntryResponse`](#cosmos-staking-v1beta1-redelegationentryresponse)\[] | |
### cosmos.staking.v1beta1.UnbondingDelegation
UnbondingDelegation stores all of a single delegator's unbonding bonds for a single validator in an time-ordered list.
| Field | Type | Description |
| ------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `delegator_address` | `string` | delegator\_address is the encoded address of the delegator. Encoded as cosmos.AddressString. |
| `validator_address` | `string` | validator\_address is the encoded address of the validator. Encoded as cosmos.ValidatorAddressString. |
| `entries` | [`UnbondingDelegationEntry`](#cosmos-staking-v1beta1-unbondingdelegationentry)\[] | entries are the unbonding delegation entries. |
### cosmos.staking.v1beta1.UnbondingDelegationEntry
UnbondingDelegationEntry defines an unbonding object with relevant metadata.
| Field | Type | Description |
| ----------------------------- | ----------- | -------------------------------------------------------------------------------------------------------- |
| `creation_height` | `int64` | creation\_height is the height which the unbonding took place. |
| `completion_time` | `Timestamp` | completion\_time is the unix time for unbonding completion. |
| `initial_balance` | `string` | initial\_balance defines the tokens initially scheduled to receive at completion. Encoded as cosmos.Int. |
| `balance` | `string` | balance defines the tokens to receive at completion. Encoded as cosmos.Int. |
| `unbonding_id` | `uint64` | Incrementing id that uniquely identifies this entry |
| `unbonding_on_hold_ref_count` | `int64` | Strictly positive if this entry's unbonding has been stopped by external modules |
### cosmos.staking.v1beta1.Validator
Validator defines a validator, together with the total amount of the Validator's bond shares and their exchange rate to coins. Slashing results in a decrease in the exchange rate, allowing correct calculation of future undelegations without iterating over delegators. When coins are delegated to this validator, the validator is credited with a delegation whose number of bond shares is based on the amount of coins delegated divided by the current exchange rate. Voting power can be calculated as total bonded shares multiplied by exchange rate.
| Field | Type | Description |
| ----------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `operator_address` | `string` | operator\_address defines the address of the validator's operator; bech encoded in JSON. Encoded as cosmos.AddressString. |
| `consensus_pubkey` | `Any` | consensus\_pubkey is the consensus public key of the validator, as a Protobuf Any. Accepts any message implementing cosmos.crypto.PubKey. |
| `jailed` | `bool` | jailed defined whether the validator has been jailed from bonded status or not. |
| `status` | [`BondStatus`](#cosmos-staking-v1beta1-bondstatus) | status is the validator status (bonded/unbonding/unbonded). |
| `tokens` | `string` | tokens define the delegated tokens (incl. self-delegation). Encoded as cosmos.Int. |
| `delegator_shares` | `string` | delegator\_shares defines total shares issued to a validator's delegators. Encoded as cosmos.Dec, read back as an integer string scaled by 10^18 over gRPC. |
| `description` | [`Description`](#cosmos-staking-v1beta1-description) | description defines the description terms for the validator. |
| `unbonding_height` | `int64` | unbonding\_height defines, if unbonding, the height at which this validator has begun unbonding. |
| `unbonding_time` | `Timestamp` | unbonding\_time defines, if unbonding, the min time for the validator to complete unbonding. |
| `commission` | [`Commission`](#cosmos-staking-v1beta1-commission) | commission defines the commission parameters. |
| `min_self_delegation` | `string` | min\_self\_delegation is the validator's self declared minimum self delegation. Encoded as cosmos.Int. |
| `unbonding_on_hold_ref_count` | `int64` | strictly positive if this validator's unbonding has been stopped by external modules |
| `unbonding_ids` | `uint64`\[] | list of unbonding ids, each uniquely identifying an unbonding of this validator |