Distribution.sol serves as an interface for Solidity contracts to interact with Cosmos SDK distribution. This offers convenience to developers, as they are not required to understand the implementation intricacies of the x/distribution module within the Cosmos SDK. Instead, they can utilize distribution functions through the familiar Ethereum interface.
/// @dev Change the address, that can withdraw the rewards of a delegator.
/// Note that this address cannot be a module account.
/// @param delegatorAddress The address of the delegator
/// @param withdrawerAddress The address that will be capable of withdrawing rewards for
/// the given delegator address
function setWithdrawAddress(
address delegatorAddress,
string memory withdrawerAddress
) external returns (bool success);
withdrawDelegatorRewards
Copy
/// @dev Withdraw the rewards of a delegator from a validator
/// @param delegatorAddress The address of the delegator
/// @param validatorAddress The address of the validator
/// @return amount The amount of Coin withdrawn
function withdrawDelegatorRewards(
address delegatorAddress,
string memory validatorAddress
)
external
returns (
Coin[] calldata amount
);
withdrawValidatorCommission
Copy
/// @dev Withdraws the rewards commission of a validator.
/// @param validatorAddress The address of the validator
/// @return amount The amount of Coin withdrawn
function withdrawValidatorCommission(
string memory validatorAddress
)
external
returns (
Coin[] calldata amount
);
/// @dev Queries validator commission and self-delegation rewards for validator.
/// @param validatorAddress The address of the validator
/// @return distributionInfo The validator's distribution info
function validatorDistributionInfo(
string memory validatorAddress
)
external
view
returns (
ValidatorDistributionInfo calldata distributionInfo
);
validatorOutstandingRewards
Copy
/// @dev Queries the outstanding rewards of a validator address.
/// @param validatorAddress The address of the validator
/// @return rewards The validator's outstanding rewards
function validatorOutstandingRewards(
string memory validatorAddress
)
external
view
returns (
DecCoin[] calldata rewards
);
validatorCommission
Copy
/// @dev Queries the accumulated commission for a validator.
/// @param validatorAddress The address of the validator
/// @return commission The validator's commission
function validatorCommission(
string memory validatorAddress
)
external
view
returns (
DecCoin[] calldata commission
);
validatorSlashes
Copy
/// @dev Queries the slashing events for a validator in a given height interval
/// defined by the starting and ending height.
/// @param validatorAddress The address of the validator
/// @param startingHeight The starting height
/// @param endingHeight The ending height
/// @return slashes The validator's slash events
/// @return pageResponse The pagination response for the query
function validatorSlashes(
string memory validatorAddress,
uint64 startingHeight,
uint64 endingHeight
)
external
view
returns (
ValidatorSlashEvent[] calldata slashes,
PageResponse calldata pageResponse
);
delegationRewards
Copy
/// @dev Queries the total rewards accrued by a delegation from a specific address to a given validator.
/// @param delegatorAddress The address of the delegator
/// @param validatorAddress The address of the validator
/// @return rewards The total rewards accrued by a delegation.
function delegationRewards(
address delegatorAddress,
string memory validatorAddress
)
external
view
returns (
DecCoin[] calldata rewards
);
delegationTotalRewards
Copy
/// @dev Queries the total rewards accrued by each validator, that a given
/// address has delegated to.
/// @param delegatorAddress The address of the delegator
/// @return rewards The total rewards accrued by each validator for a delegator.
/// @return total The total rewards accrued by a delegator.
function delegationTotalRewards(
address delegatorAddress
)
external
view
returns (
DelegationDelegatorReward[] calldata rewards,
DecCoin[] calldata total
);
delegatorValidators
Copy
/// @dev Queries all validators, that a given address has delegated to.
/// @param delegatorAddress The address of the delegator
/// @return validators The addresses of all validators, that were delegated to by the given address.
function delegatorValidators(
address delegatorAddress
) external view returns (string[] calldata validators);
delegatorWithdrawAddress
delegatorWithdrawAddress queries withdraw address of a delegator
Copy
/// @dev Queries the address capable of withdrawing rewards for a given delegator.
/// @param delegatorAddress The address of the delegator
/// @return withdrawAddress The address capable of withdrawing rewards for the delegator.
function delegatorWithdrawAddress(
address delegatorAddress
) external view returns (string memory withdrawAddress);
Each of the transactions emits its corresponding event. These are:
SetWithdrawerAddress
Copy
/// @dev SetWithdrawerAddress defines an Event emitted when a new withdrawer address is being set
/// @param caller the caller of the transaction
/// @param withdrawerAddress the newly set withdrawer address
event SetWithdrawerAddress(
address indexed caller,
string withdrawerAddress
);
WithdrawDelegatorRewards
Copy
/// @dev WithdrawDelegatorRewards defines an Event emitted when rewards from a delegation are withdrawn
/// @param delegatorAddress the address of the delegator
/// @param validatorAddress the address of the validator
/// @param amount the amount being withdrawn from the delegation
event WithdrawDelegatorRewards(
address indexed delegatorAddress,
string indexed validatorAddress,
uint256 amount
);
WithdrawValidatorCommission
Copy
/// @dev WithdrawValidatorCommission defines an Event emitted when validator commissions are being withdrawn
/// @param validatorAddress is the address of the validator
/// @param commission is the total commission earned by the validator
event WithdrawValidatorCommission(
string indexed validatorAddress,
uint256 commission
);
Utilize the Solidity Interface:
Here are examples demonstrating interaction with this Solidity interface from your smart contracts. Ensure to import the precompiled interface, such as:
Set Withdraw Address:
The changeWithdrawAddress function enables a user to set a new withdraw address in the Cosmos x/distribution module. To ensure the success of this transaction, ensure that the user has previously approved the MSG_SET_WITHDRAWER_ADDRESS message.
Copy
function changeWithdrawAddress(
string memory _withdrawAddr
) public returns (bool) {
return
distribution.DISTRIBUTION_CONTRACT.setWithdrawAddress(
msg.sender,
_withdrawAddr
);
}
The withdrawStakingRewards function permits a user to withdraw their rewards associated with a specified validator. To execute this transaction successfully, ensure that the user has previously approved the MSG_WITHDRAW_DELEGATOR_REWARD message.
Copy
function withdrawStakingRewards(
string memory _valAddr
) public returns (types.Coin[] memory) {
return
distribution.DISTRIBUTION_CONTRACT.withdrawDelegatorRewards(
msg.sender,
_valAddr
);
}
If the user operates a validator, they can withdraw the corresponding commission through a smart contract. A function similar to withdrawCommission can be utilized for this purpose. To ensure the transaction's success, the user must have previously approved the MSG_WITHDRAW_VALIDATOR_COMMISSION message.
Copy
function withdrawCommission(
string memory _valAddr
) public returns (types.Coin[] memory) {
return
distribution.DISTRIBUTION_CONTRACT.withdrawValidatorCommission(
_valAddr
);
}
Similar to transactions, smart contracts can utilize query methods, which are read-only. Examples include the getDelegationRewards and getValidatorCommission functions, which retrieve information for the specified validator address.