🔩x/staking Module EVM Extension

Solidity Interface & ABI​

Staking.sol provides an interface for Solidity contracts to interact with Cosmos SDK staking. This simplifies the process for developers, as they do not need to understand the implementation details of the Cosmos SDK's x/staking module. Instead, they can use the familiar Ethereum interface to access staking functions.

Interface Staking.sol​

ABI​

Transactions​

The Staking solidity interface includes the following transactions

• delegate

  delegate defines a method for performing a delegation of coins from a delegator to a validator.

  Copy

  function delegate(
      address delegatorAddress,
      string memory validatorAddress,
      uint256 amount
  ) external returns (bool success);

• undelegate

  The undelegate method facilitates the process of undelegating from a delegate and a validator.

  Copy

  function undelegate(
      address delegatorAddress,
      string memory validatorAddress,
      uint256 amount
  ) external returns (int64 completionTime);

• redelegate

  The redelegate method facilitates the redelegation of coins from a delegator and source validator to a destination validator.

  Copy

  function redelegate(
      address delegatorAddress,
      string memory validatorSrcAddress,
      string memory validatorDstAddress,
      uint256 amount
  ) external returns (int64 completionTime);

• cancelUnbondingDelegation

  The cancelUnbondingDelegation method allows delegators to cancel an unbonding delegation entry and redelegate to a previous validator.

  Copy

  function cancelUnbondingDelegation(
      address delegatorAddress,
      string memory validatorAddress,
      uint256 amount,
      uint256 creationHeight
  ) external returns (bool success);

Queries​

• delegation

  Retrieve the specified amount of the bond denomination for a validator.

  Copy

  function delegation(
          address delegatorAddress,
          string memory validatorAddress
      ) external view returns (uint256 shares, Coin calldata balance);

• unbondingDelegation

  The unbondingDelegation method returns the current unbonding delegation.

  Copy

  function unbondingDelegation(
          address delegatorAddress,
          string memory validatorAddress
      ) external view returns (UnbondingDelegationEntry[] calldata entries);

• validator

  The validator method retrieves validator information for a specified validator address.

  Copy

  function validator(
          string memory validatorAddress
      )
      external view returns (
          Validator calldata validator
      );

• validators

  The validators method retrieves all validators matching the specified status.

  Copy

  function validators(
          string memory status,
          PageRequest calldata pageRequest
      ) external view returns (
          Validator[] calldata validators,
          PageResponse calldata pageResponse
      );

• redelegation

  The redelegation method retrieves all redelegations from a source validator to a destination validator for a specified delegator.

  Copy

  function redelegation(
          address delegatorAddress,
          string memory srcValidatorAddress,
          string memory dstValidatorAddress
      ) external view returns (RedelegationEntry[] calldata entries);

• redelegations

  The redelegations method retrieves all redelegations based on specified criteria, including a given delegator, origin validator address, and/or destination validator address, with support for pagination.

  Copy

  function redelegations(
      address delegatorAddress,
      string memory srcValidatorAddress,
      string memory dstValidatorAddress,
      PageRequest calldata pageRequest
  )
      external
      view
      returns (
          RedelegationResponse[] calldata response,
          PageResponse calldata pageResponse
      );

Events​

Each transaction emits a corresponding event. These events include:

• Delegate

  The Delegate event is emitted when a specified amount of tokens are delegated from the delegator address to the validator address.

  Copy

  event Delegate(
          address indexed delegatorAddress,
          string indexed validatorAddress,
          uint256 amount,
          uint256 newShares
      );

• Unbond

  The Unbond event is emitted when a specified amount of tokens are unbonded from the validator address to the delegator address.

  Copy

  event Unbond(
          address indexed delegatorAddress,
          string indexed validatorAddress,
          uint256 amount,
          uint256 completionTime
      );

• Redelegate

  The Redelegate event is defined to be emitted when a specified amount of tokens are redelegated from the source validator address to the destination validator address.

  Copy

  event Redelegate(
          address indexed delegatorAddress,
          string indexed validatorSrcAddress,
          string indexed validatorDstAddress,
          uint256 amount,
          uint256 completionTime
      );

• CancelUnbondingDelegation

  The CancelUnbondingDelegation event is defined to be emitted when tokens in the process of unbonding from the validator address are bonded again with a specified amount.

  Copy

  event CancelUnbondingDelegation(
          address indexed delegatorAddress,
          string indexed validatorAddress,
          uint256 amount,
          uint256 creationHeight
      );

Utilize the Solidity Interface:

Below are examples demonstrating interaction with this Solidity interface from your smart contracts.

Ensure to import the precompiled interface, for instance:

Grant Approval for Desired Messages:

Refer to the function below, which grants approval to the smart contract for sending all x/staking module messages on behalf of the sender account. In this instance, the allowance amount is set to the maximum possible. You may adjust this function to approve specific messages and amounts as needed.

Copy

string[] private stakingMethods = [
    MSG_DELEGATE,
    MSG_UNDELEGATE,
    MSG_REDELEGATE,
    MSG_CANCEL_UNDELEGATION
];

/// @dev Approves this smart contract to perform all staking transactions with the maximum amount of tokens on behalf of the transaction signer.
/// @dev This creates a Cosmos Authorization Grant for the given methods.
/// @dev This emits an Approval event.
function approveAllStakingMethodsWithMaxAmount() public {
    bool success = STAKING_CONTRACT.approve(
        address(this),
        type(uint256).max,
        stakingMethods
    );
    require(success, "Failed to approve staking methods");
}

Delegate to a validator​

The stakeTokens function enables the transaction sender to delegate the specified amount to their preferred validator. It's important to note that for this transaction to succeed, the user must have previously approved the MSG_DELEGATE (as exemplified by the approveAllStakingMethodsWithMaxAmount in the provided code snippet). Upon execution, this function provides the completion time of the staking transaction and emits a Delegate event.

Copy

/// @dev stake a given amount of tokens. Returns the completion time of the staking transaction.
/// @dev This emits an Delegate event.
/// @param _validatorAddr The address of the validator.
/// @param _amount The amount of tokens to stake in aegaxd.
/// @return success Boolean to inform if the operation was successful or not.
function stakeTokens(
    string memory _validatorAddr,
    uint256 _amount
) public returns (bool success) {
    return STAKING_CONTRACT.delegate(msg.sender, _validatorAddr, _amount);
}

Undelegate from a validator​

The unstakeTokens function permits a user to unstake a specified amount of tokens. Upon execution, it provides the completion time of the unstaking transaction and emits an Undelegate event.

Copy

/// @dev unstake a given amount of tokens. Returns the completion time of the unstaking transaction.
/// @dev This emits an Undelegate event.
/// @param _validatorAddr The address of the validator.
/// @param _amount The amount of tokens to unstake in aevmos.
/// @return completionTime The completion time of the unstaking transaction.
function unstakeTokens(
    string memory _validatorAddr,
    uint256 _amount
) public returns (int64 completionTime) {
    return STAKING_CONTRACT.undelegate(msg.sender, _validatorAddr, _amount);
}

Redelegate to another validator​

The redelegateTokens function enables a user to redelegate a specified amount of tokens. Upon execution, it provides the completion time of the redelegation transaction and emits a Redelegate event.

Copy

/// @dev redelegate a given amount of tokens. Returns the completion time of the redelegate transaction.
/// @dev This emits a Redelegate event.
/// @param _validatorSrcAddr The address of the source validator.
/// @param _validatorDstAddr The address of the destination validator.
/// @param _amount The amount of tokens to redelegate in aegaxd.
/// @return completionTime The completion time of the redelegate transaction.
function redelegateTokens(
    string memory _validatorSrcAddr,
    string memory _validatorDstAddr,
    uint256 _amount
) public returns (int64 completionTime) {
    return
        STAKING_CONTRACT.redelegate(
            msg.sender,
            _validatorSrcAddr,
            _validatorDstAddr,
            _amount
        );
}

Cancel unbonding from a validator​

The cancelUnbondingDelegation function allows a user to cancel an unbonding delegation. This function returns the completion time of the unbonding delegation cancellation transaction and emits a CancelUnbondingDelegation event.

Copy

/// @dev cancel an unbonding delegation. Returns the completion time of the unbonding delegation cancellation transaction.
/// @dev This emits an CancelUnbondingDelegation event.
/// @param _validatorAddr The address of the validator.
/// @param _amount The amount of tokens to cancel the unbonding delegation in aegaxd.
/// @param _creationHeight The creation height of the unbonding delegation.
function cancelUnbondingDelegation(
    string memory _validatorAddr,
    uint256 _amount,
    uint256 _creationHeight
) public returns (bool success) {
    return
        STAKING_CONTRACT.cancelUnbondingDelegation(
            msg.sender,
            _validatorAddr,
            _amount,
            _creationHeight
        );
}

Queries​

Similar to transactions, smart contracts can utilize query methods. Authorization is not required for these read-only methods. Examples include the getDelegation and getUnbondingDelegation functions, which retrieve information for the specified validator address.

Copy

/// @dev Returns the delegation information for a given validator for the msg sender.
/// @param _validatorAddr The address of the validator.
/// @return shares and balance. The delegation information for a given validator for the msg sender.
function getDelegation(
    string memory _validatorAddr
) public view returns (uint256 shares, Coin memory balance) {
    return STAKING_CONTRACT.delegation(msg.sender, _validatorAddr);
}

/// @dev Returns the unbonding delegation information for a given validator for the msg sender.
/// @param _validatorAddr The address of the validator.
/// @return entries The unbonding delegation entries for a given validator for the msg sender.
function getUnbondingDelegation(
    string memory _validatorAddr
) public view returns (UnbondingDelegationEntry[] memory entries) {
    return STAKING_CONTRACT.unbondingDelegation(msg.sender, _validatorAddr);
}