🐻⛓️ Berachain Docs

Appearance

Staking Polaris ​

Git Source

The Cosmos SDK staking module is responsible for managing the delegation, redelegation, and unbonding of tokens in the Cosmos ecosystem. It provides an interface for users to delegate tokens to validators, redelegate tokens from one validator to another, and unbond tokens from validators. The module tracks the delegation state, validator information, and unbonding state for each user and validator

The staking module can be used to participate in the consensus process of the Cosmos network by delegating tokens to validators, who are responsible for proposing and validating blocks. Users can also redelegate their tokens to different validators if they wish to change their delegation preferences. Additionally, users can unbond their tokens from validators if they want to withdraw their tokens or stop participating in the consensus process.

The module provides various functions to query validator and delegation information, such as getting a list of all active validators, bonded validator addresses, and delegator validators. It also allows users to perform actions like delegating, undelegating, and redelegating tokens, as well as canceling unbonding delegations.

Note: Link to existing contract ABI's can be found on Github here.

Interface of the staking module's precompiled contract

Functions ​

getValAddressFromConsAddress ​

Returns the operator address of the validator for the given consensus address.

solidity
function getValAddressFromConsAddress(bytes calldata consAddr) external pure returns (address);
function getValAddressFromConsAddress(bytes calldata consAddr) external pure returns (address);

Parameters

NameTypeDescription
consAddrbytesThe consensus address (as bytes) of the validator

getValidators ​

Accepts pagination request (empty == no pagination returned).

Returns a list of all active validators.

solidity
function getValidators(Cosmos.PageRequest calldata pagination)
    external
    view
    returns (Validator[] memory, Cosmos.PageResponse memory);
function getValidators(Cosmos.PageRequest calldata pagination)
    external
    view
    returns (Validator[] memory, Cosmos.PageResponse memory);

getBondedValidators ​

Accepts pagination request (empty == no pagination returned).

Returns a list of bonded validator (operator) addresses.

solidity
function getBondedValidators(Cosmos.PageRequest calldata pagination)
    external
    view
    returns (Validator[] memory, Cosmos.PageResponse memory);
function getBondedValidators(Cosmos.PageRequest calldata pagination)
    external
    view
    returns (Validator[] memory, Cosmos.PageResponse memory);

getBondedValidatorsByPower ​

Returns a list of bonded validator (operator) addresses, sorted by power (stake) in descending order.

solidity
function getBondedValidatorsByPower() external view returns (address[] memory);
function getBondedValidatorsByPower() external view returns (address[] memory);

getValidator ​

Returns the validator at the given address.

solidity
function getValidator(address validatorAddress) external view returns (Validator memory);
function getValidator(address validatorAddress) external view returns (Validator memory);

Parameters

NameTypeDescription
validatorAddressaddressThe validator operator address

getDelegatorValidators ​

Accepts pagination request (empty == no pagination returned).

Returns all the validators delegated to by the given delegator.

solidity
function getDelegatorValidators(address delegatorAddress, Cosmos.PageRequest calldata pagination)
    external
    view
    returns (Validator[] memory, Cosmos.PageResponse memory);
function getDelegatorValidators(address delegatorAddress, Cosmos.PageRequest calldata pagination)
    external
    view
    returns (Validator[] memory, Cosmos.PageResponse memory);

Parameters

NameTypeDescription
delegatorAddressaddressThe delegator address to query validators for.
paginationCosmos.PageRequest

getValidatorDelegations ​

Accepts pagination request (empty == no pagination returned).

Returns all the delegations delegated to the given validator.

solidity
function getValidatorDelegations(address validatorAddress, Cosmos.PageRequest calldata pagination)
    external
    view
    returns (Delegation[] memory, Cosmos.PageResponse memory);
function getValidatorDelegations(address validatorAddress, Cosmos.PageRequest calldata pagination)
    external
    view
    returns (Delegation[] memory, Cosmos.PageResponse memory);

Parameters

NameTypeDescription
validatorAddressaddressThe validator operator address to query delegations for.
paginationCosmos.PageRequest

getDelegation ​

Returns the amount of tokens currently delegated by delegatorAddress to validatorAddress

solidity
function getDelegation(address delegatorAddress, address validatorAddress) external view returns (uint256);
function getDelegation(address delegatorAddress, address validatorAddress) external view returns (uint256);

Parameters

NameTypeDescription
delegatorAddressaddressThe delegator address
validatorAddressaddressThe validator operator address

getUnbondingDelegation ​

Returns a time-ordered list of all UnbondingDelegationEntries between delegatorAddress and validatorAddress

solidity
function getUnbondingDelegation(address delegatorAddress, address validatorAddress)
    external
    view
    returns (UnbondingDelegationEntry[] memory);
function getUnbondingDelegation(address delegatorAddress, address validatorAddress)
    external
    view
    returns (UnbondingDelegationEntry[] memory);

Parameters

NameTypeDescription
delegatorAddressaddressThe delegator address
validatorAddressaddressThe validator operator address

getDelegatorUnbondingDelegations ​

Accepts pagination request (empty == no pagination returned).

Returns a list of all unbonding delegations for a given delegator

solidity
function getDelegatorUnbondingDelegations(address delegatorAddress, Cosmos.PageRequest calldata pagination)
    external
    view
    returns (UnbondingDelegation[] memory, Cosmos.PageResponse memory);
function getDelegatorUnbondingDelegations(address delegatorAddress, Cosmos.PageRequest calldata pagination)
    external
    view
    returns (UnbondingDelegation[] memory, Cosmos.PageResponse memory);

Parameters

NameTypeDescription
delegatorAddressaddressThe delegator address
paginationCosmos.PageRequest

getRedelegations ​

Accepts pagination request (empty == no pagination returned).

Returns a list of delegatorAddress's redelegating bonds from srcValidator to dstValidator

solidity
function getRedelegations(
    address delegatorAddress,
    address srcValidator,
    address dstValidator,
    Cosmos.PageRequest calldata pagination
) external view returns (RedelegationEntry[] memory, Cosmos.PageResponse memory);
function getRedelegations(
    address delegatorAddress,
    address srcValidator,
    address dstValidator,
    Cosmos.PageRequest calldata pagination
) external view returns (RedelegationEntry[] memory, Cosmos.PageResponse memory);

Parameters

NameTypeDescription
delegatorAddressaddressThe delegator address
srcValidatoraddressThe source validator operator address
dstValidatoraddressThe destination validator operator address
paginationCosmos.PageRequest

delegate ​

msg.sender delegates the amount of tokens to validatorAddress

solidity
function delegate(address validatorAddress, uint256 amount) external payable returns (bool);
function delegate(address validatorAddress, uint256 amount) external payable returns (bool);

Parameters

NameTypeDescription
validatorAddressaddressThe validator operator address
amountuint256The amount of tokens to delegate

undelegate ​

msg.sender undelegates the amount of tokens from validatorAddress

solidity
function undelegate(address validatorAddress, uint256 amount) external payable returns (bool);
function undelegate(address validatorAddress, uint256 amount) external payable returns (bool);

Parameters

NameTypeDescription
validatorAddressaddressThe validator operator address
amountuint256The amount of tokens to undelegate

beginRedelegate ​

msg.sender redelegates the amount of tokens from srcValidator to validtorDstAddr

solidity
function beginRedelegate(address srcValidator, address dstValidator, uint256 amount) external payable returns (bool);
function beginRedelegate(address srcValidator, address dstValidator, uint256 amount) external payable returns (bool);

Parameters

NameTypeDescription
srcValidatoraddressThe source validator operator address
dstValidatoraddressThe destination validator operator address
amountuint256The amount of tokens to redelegate

cancelUnbondingDelegation ​

Cancels msg.sender's unbonding delegation with validatorAddress and delegates the amount of tokens back to validatorAddress

solidity
function cancelUnbondingDelegation(address validatorAddress, uint256 amount, int64 creationHeight)
    external
    payable
    returns (bool);
function cancelUnbondingDelegation(address validatorAddress, uint256 amount, int64 creationHeight)
    external
    payable
    returns (bool);

Parameters

NameTypeDescription
validatorAddressaddressThe validator operator address
amountuint256The amount of tokens to cancel
creationHeightint64The height at which the unbonding delegation was created

Events ​

Delegate ​

Emitted by the staking module when amount tokens are delegated to validator

solidity
event Delegate(address indexed validator, Cosmos.Coin[] amount);
event Delegate(address indexed validator, Cosmos.Coin[] amount);

Parameters

NameTypeDescription
validatoraddressThe validator operator address
amountCosmos.Coin[]The amount of tokens delegated

Redelegate ​

Emitted by the staking module when amount tokens are redelegated from sourceValidator to destinationValidator

solidity
event Redelegate(address indexed sourceValidator, address indexed destinationValidator, Cosmos.Coin[] amount);
event Redelegate(address indexed sourceValidator, address indexed destinationValidator, Cosmos.Coin[] amount);

Parameters

NameTypeDescription
sourceValidatoraddressThe source validator operator address
destinationValidatoraddressThe destination validator operator address
amountCosmos.Coin[]The amount of tokens redelegated

CreateValidator ​

Emitted by the staking module when amount tokens are used to create validator

solidity
event CreateValidator(address indexed validator, Cosmos.Coin[] amount);
event CreateValidator(address indexed validator, Cosmos.Coin[] amount);

Parameters

NameTypeDescription
validatoraddressThe validator operator address
amountCosmos.Coin[]The amount of tokens used to create the validator

Unbond ​

Emitted by the staking module when amount tokens are unbonded from validator

solidity
event Unbond(address indexed validator, Cosmos.Coin[] amount);
event Unbond(address indexed validator, Cosmos.Coin[] amount);

Parameters

NameTypeDescription
validatoraddressThe validator operator address
amountCosmos.Coin[]The amount of tokens unbonded

CancelUnbondingDelegation ​

Emitted by the staking module when amount tokens are canceled from delegator's unbonding delegation with validator

solidity
event CancelUnbondingDelegation(
    address indexed validator, address indexed delegator, Cosmos.Coin[] amount, int64 creationHeight
);
event CancelUnbondingDelegation(
    address indexed validator, address indexed delegator, Cosmos.Coin[] amount, int64 creationHeight
);

Parameters

NameTypeDescription
validatoraddressThe validator operator address
delegatoraddressThe delegator address
amountCosmos.Coin[]The amount of tokens canceled
creationHeightint64The height at which the unbonding delegation was created

Structs ​

Validator ​

Represents a validator.

solidity
struct Validator {
    address operatorAddr;
    bytes consAddr;
    bool jailed;
    string status;
    uint256 tokens;
    uint256 delegatorShares;
    Description description;
    int64 unbondingHeight;
    string unbondingTime;
    Commission commission;
    uint256 minSelfDelegation;
    int64 unbondingOnHoldRefCount;
    uint64[] unbondingIds;
}
struct Validator {
    address operatorAddr;
    bytes consAddr;
    bool jailed;
    string status;
    uint256 tokens;
    uint256 delegatorShares;
    Description description;
    int64 unbondingHeight;
    string unbondingTime;
    Commission commission;
    uint256 minSelfDelegation;
    int64 unbondingOnHoldRefCount;
    uint64[] unbondingIds;
}

Commission ​

Represents the commission parameters for a given validator.

solidity
struct Commission {
    CommissionRates commissionRates;
    string updateTime;
}
struct Commission {
    CommissionRates commissionRates;
    string updateTime;
}

CommissionRates ​

Represents the initial commission rates to be used for creating a validator.

solidity
struct CommissionRates {
    uint256 rate;
    uint256 maxRate;
    uint256 maxChangeRate;
}
struct CommissionRates {
    uint256 rate;
    uint256 maxRate;
    uint256 maxChangeRate;
}

Description ​

Represents a validator description.

solidity
struct Description {
    string moniker;
    string identity;
    string website;
    string securityContact;
    string details;
}
struct Description {
    string moniker;
    string identity;
    string website;
    string securityContact;
    string details;
}

UnbondingDelegationEntry ​

Represents one entry of an unbonding delegation

solidity
struct UnbondingDelegationEntry {
    int64 creationHeight;
    string completionTime;
    uint256 initialBalance;
    uint256 balance;
    uint64 unbondingId;
}
struct UnbondingDelegationEntry {
    int64 creationHeight;
    string completionTime;
    uint256 initialBalance;
    uint256 balance;
    uint64 unbondingId;
}

UnbondingDelegation ​

Represents all unbonding bonds of a single delegator with relevant metadata

solidity
struct UnbondingDelegation {
    address delegatorAddress;
    address validatorAddress;
    UnbondingDelegationEntry[] entries;
}
struct UnbondingDelegation {
    address delegatorAddress;
    address validatorAddress;
    UnbondingDelegationEntry[] entries;
}

RedelegationEntry ​

Represents a redelegation entry with relevant metadata

solidity
struct RedelegationEntry {
    int64 creationHeight;
    string completionTime;
    uint256 initialBalance;
    uint256 sharesDst;
    uint64 unbondingId;
}
struct RedelegationEntry {
    int64 creationHeight;
    string completionTime;
    uint256 initialBalance;
    uint256 sharesDst;
    uint64 unbondingId;
}

Delegation ​

Represents a single delegation.

solidity
struct Delegation {
    address delegator;
    uint256 balance;
    uint256 shares;
}
struct Delegation {
    address delegator;
    uint256 balance;
    uint256 shares;
}