From faec924964107959fa7ba7abdce8d44081c9f48c Mon Sep 17 00:00:00 2001 From: Cal Bera Date: Mon, 18 Sep 2023 17:09:00 -0400 Subject: [PATCH] feat(docs): Add more documentation for the precompiled contracts (#1100) Co-authored-by: Devon Bear --- contracts/src/cosmos/precompile/Bank.sol | 52 +++++++++++------- .../src/cosmos/precompile/Distribution.sol | 5 +- .../src/cosmos/precompile/Governance.sol | 33 ++++++------ contracts/src/cosmos/precompile/Staking.sol | 53 ++++++++++++++----- 4 files changed, 97 insertions(+), 46 deletions(-) diff --git a/contracts/src/cosmos/precompile/Bank.sol b/contracts/src/cosmos/precompile/Bank.sol index 4fc529dd4..befb0fa75 100644 --- a/contracts/src/cosmos/precompile/Bank.sol +++ b/contracts/src/cosmos/precompile/Bank.sol @@ -35,93 +35,109 @@ interface IBankModule { /** * @dev Emitted by the bank module when `amount` tokens are sent to `recipient` + * @param recipient The recipient address + * @param amount The amount of Cosmos coins sent */ event Transfer(address indexed recipient, Cosmos.Coin[] amount); /** * @dev Emitted by the bank module when `sender` sends some amount of tokens + * @param sender The sender address */ event Message(address indexed sender); /** * @dev Emitted by the bank module when `amount` tokens are spent by `spender` + * @param spender The spender address + * @param amount The amount of Cosmos coins spent */ event CoinSpent(address indexed spender, Cosmos.Coin[] amount); /** * @dev Emitted by the bank module when `amount` tokens are received by `receiver` + * @param receiver The receiver address + * @param amount The amount of Cosmos coins received */ event CoinReceived(address indexed receiver, Cosmos.Coin[] amount); /** * @dev Emitted by the bank module when `amount` tokens are minted by `minter` - * - * Note: "Coinbase" refers to the Cosmos event: EventTypeCoinMint. `minter` is a module - * address. + * @param minter The minter address + * @param amount The amount of Cosmos coins minted + * @notice "Coinbase" refers to the Cosmos event: `EventTypeCoinMint` + * @notice `minter` is always a module address */ event Coinbase(address indexed minter, Cosmos.Coin[] amount); /** * @dev Emitted by the bank module when `amount` tokens are burned by `burner` - * - * Note: `burner` is a module address + * @param burner The burner address + * @param amount The amount of Cosmos coins burned + * @notice `burner` is always a module address */ event Burn(address indexed burner, Cosmos.Coin[] amount); /////////////////////////////////////// READ METHODS ////////////////////////////////////////// /** - * @dev Returns the `amount` of account balance by address for a given denomination. + * @dev Returns the `amount` of account balance by address for a given coin denomination + * @notice If the denomination is not found, returns 0 */ function getBalance(address accountAddress, string calldata denom) external view returns (uint256); /** - * @dev Returns account balance by address for all denominations. + * @dev Returns account balance by address for all denominations + * @notice If the account address is not found, returns an empty array */ function getAllBalances(address accountAddress) external view returns (Cosmos.Coin[] memory); /** - * @dev Returns the `amount` of account balance by address for a given denomination. + * @dev Returns the `amount` of account balance by address for a given coin denomination + * @notice If the denomination is not found, returns 0 */ function getSpendableBalance(address accountAddress, string calldata denom) external view returns (uint256); /** - * @dev Returns account balance by address for all denominations. + * @dev Returns account balance by address for all coin denominations + * @notice If the account address is not found, returns an empty array */ function getAllSpendableBalances(address accountAddress) external view returns (Cosmos.Coin[] memory); /** - * @dev Returns the total supply of a single coin. + * @dev Returns the total supply of a single coin */ function getSupply(string calldata denom) external view returns (uint256); /** - * @dev Returns the total supply of a all coins. + * @dev Returns the total supply of a all coins */ function getAllSupply() external view returns (Cosmos.Coin[] memory); /** - * @dev Returns the denomination's metadata. + * @dev Returns the coin denomination's metadata */ function getDenomMetadata(string calldata denom) external view returns (DenomMetadata memory); /** - * @dev Returns if the denom is enabled to send + * @dev Returns if the coin is enabled to be sent (transfered) */ function getSendEnabled(string calldata denom) external view returns (bool); ////////////////////////////////////// WRITE METHODS ////////////////////////////////////////// /** - * @dev Send coins from msg.sender to another. + * @dev Send coins from msg.sender to another + * @param toAddress The recipient address + * @param amount The amount of Cosmos coins to send + * @notice If the sender does not have enough balance, returns false */ function send(address toAddress, Cosmos.Coin[] calldata amount) external payable returns (bool); //////////////////////////////////////////// UTILS //////////////////////////////////////////// /** - * @dev Represents a denom unit. - * Note: this struct is generated in generated/i_bank_module.abigen.go + * @dev Represents a denom unit in the bank module + * @notice this struct is generated in generated/i_bank_module.abigen.go */ struct DenomUnit { string denom; @@ -130,8 +146,8 @@ interface IBankModule { } /** - * @dev Represents a denom metadata. - * Note: this struct is generated in generated/i_bank_module.abigen.go + * @dev Represents a denom metadata in the bank module + * @notice this struct is generated in generated/i_bank_module.abigen.go */ struct DenomMetadata { string description; diff --git a/contracts/src/cosmos/precompile/Distribution.sol b/contracts/src/cosmos/precompile/Distribution.sol index 1b702fa04..e959fe8a3 100644 --- a/contracts/src/cosmos/precompile/Distribution.sol +++ b/contracts/src/cosmos/precompile/Distribution.sol @@ -46,7 +46,7 @@ interface IDistributionModule { /** * @dev Withdraw the rewrads accumulated by the caller(msg.sender). Returns the rewards claimed. * @param delegator The delegator to withdraw the rewards from. - * @param validator The validator to withdraw the rewards from. + * @param validator The validator (operator address) to withdraw the rewards from. */ function withdrawDelegatorReward(address delegator, address validator) external returns (Cosmos.Coin[] memory); @@ -77,6 +77,9 @@ interface IDistributionModule { */ event SetWithdrawAddress(address indexed withdrawAddress); + /** + * @dev Represents a delegator's rewards for one particular validator. + */ struct ValidatorReward { address validator; Cosmos.Coin[] rewards; diff --git a/contracts/src/cosmos/precompile/Governance.sol b/contracts/src/cosmos/precompile/Governance.sol index d2d83f2f0..13e6ccde2 100644 --- a/contracts/src/cosmos/precompile/Governance.sol +++ b/contracts/src/cosmos/precompile/Governance.sol @@ -27,18 +27,23 @@ pragma solidity ^0.8.4; import {Cosmos} from "../CosmosTypes.sol"; +/** + * @dev Interface of the governance module's precompiled contract + */ interface IGovernanceModule { ////////////////////////////////////////// Write Methods ///////////////////////////////////////////// /** - * @dev Submit a proposal to the governance module. Returns the proposal id. - * @param proposalMsg The proposal to submit. + * @dev Submit a proposal to the governance module. + * @param proposalMsg The proposal to submit (as marshaled bytes). NOTE: use the codec to + * marshal the proposal message. + * @return The id of the proposal. */ function submitProposal(bytes calldata proposalMsg) external returns (uint64); /** - * @dev Cancel a proposal. Returns the cancled time and height. - * burned. + * @dev Cancel a proposal. * @param proposalId The id of the proposal to cancel. + * @return The time and block height the proposal was canceled. */ function cancelProposal(uint64 proposalId) external returns (uint64, uint64); @@ -82,6 +87,7 @@ interface IGovernanceModule { /** * @dev Get proposals with a given status. + * @notice Accepts pagination request (empty == no pagination returned). * @param proposalStatus The status of the proposals to get. */ function getProposals(int32 proposalStatus, Cosmos.PageRequest calldata pagination) @@ -90,12 +96,15 @@ interface IGovernanceModule { returns (Proposal[] memory, Cosmos.PageResponse memory); /** - * @dev Get the proposal tally result with the given id. + * @dev Get the proposal tally result for the given id. + * @param proposalId The id of the proposal to get the tally result for. */ function getProposalTallyResult(uint64 proposalId) external view returns (TallyResult memory); /** * @dev Get the proposal votes with the given id. + * @notice Accepts pagination request. + * @param proposalId The id of the proposal to get the votes for. */ function getProposalVotes(uint64 proposalId, Cosmos.PageRequest calldata pagination) external @@ -104,6 +113,8 @@ interface IGovernanceModule { /** * @dev Get the proposal vote information with the given id and voter. + * @param proposalId The id of the proposal to get the vote info for. + * @param voter The address of the voter to get the vote info for. */ function getProposalVotesByVoter(uint64 proposalId, address voter) external view returns (Vote memory); @@ -135,7 +146,6 @@ interface IGovernanceModule { ////////////////////////////////////////// Structs /////////////////////////////////////////////////// /** * @dev Represents a governance module `WeightedVoteOption`. - * Note: this struct is generated in generated/i_staking_module.abigen.go */ struct WeightedVoteOption { int32 voteOption; @@ -144,7 +154,6 @@ interface IGovernanceModule { /** * @dev Represents a governance module `Vote`. - * Note: this struct is generated in generated/i_staking_module.abigen.go */ struct Vote { uint64 proposalId; @@ -155,7 +164,6 @@ interface IGovernanceModule { /** * @dev Represents a governance module `Proposal`. - * Note: this struct is generated in generated/i_staking_module.abigen.go */ struct Proposal { uint64 id; @@ -175,7 +183,6 @@ interface IGovernanceModule { /** * @dev Represents the governance module's parameters. - * Note: this struct is generated in generated/i_staking_module.abigen.go */ struct Params { Cosmos.Coin[] minDeposit; @@ -197,7 +204,6 @@ interface IGovernanceModule { /** * @dev Represents the governance module's `VotingParams`. - * Note: this struct is generated in generated/i_staking_module.abigen.go */ struct VotingParams { uint64 votingPeriod; @@ -205,7 +211,6 @@ interface IGovernanceModule { /** * @dev Represents the governance module's `DepositParams`. - * Note: this struct is generated in generated/i_staking_module.abigen.go */ struct DepositParams { Cosmos.Coin[] minDeposit; @@ -214,7 +219,6 @@ interface IGovernanceModule { /** * @dev Represents the governance module's `TallyParams`. - * Note: this struct is generated in generated/i_staking_module.abigen.go */ struct TallyParams { string quorum; @@ -224,7 +228,6 @@ interface IGovernanceModule { /** * @dev Represents a governance module `TallyResult`. - * Note: this struct is generated in generated/i_staking_module.abigen.go */ struct TallyResult { string yesCount; @@ -234,7 +237,7 @@ interface IGovernanceModule { } /** - * @dev Emitted by the governance module when `submitProposal` is called. + * @dev Emitted by the governance precompile when `submitProposal` is called. * @param proposalId The id of the proposal. * @param proposalSender The sender of the submit proposal. */ @@ -248,7 +251,7 @@ interface IGovernanceModule { event ProposalDeposit(uint64 indexed proposalId, Cosmos.Coin[] amount); /** - * @dev Emitted by the governance module when `AddVote` is called in the msg server. + * @dev Emitted by the governance precompile when a proposal is voted on. * @param proposalVote The vote that was voted on for a proposal. */ event ProposalVoted(Vote proposalVote); diff --git a/contracts/src/cosmos/precompile/Staking.sol b/contracts/src/cosmos/precompile/Staking.sol index 4ac0bde88..26750e829 100644 --- a/contracts/src/cosmos/precompile/Staking.sol +++ b/contracts/src/cosmos/precompile/Staking.sol @@ -36,28 +36,41 @@ interface IStakingModule { /** * @dev Emitted by the staking module when `amount` tokens are delegated to * `validator` + * @param validator The validator operator address + * @param amount The amount of tokens delegated */ event Delegate(address indexed validator, Cosmos.Coin[] amount); /** * @dev Emitted by the staking module when `amount` tokens are redelegated from * `sourceValidator` to `destinationValidator` + * @param sourceValidator The source validator operator address + * @param destinationValidator The destination validator operator address + * @param amount The amount of tokens redelegated */ event Redelegate(address indexed sourceValidator, address indexed destinationValidator, Cosmos.Coin[] amount); /** * @dev Emitted by the staking module when `amount` tokens are used to create `validator` + * @param validator The validator operator address + * @param amount The amount of tokens used to create the validator */ event CreateValidator(address indexed validator, Cosmos.Coin[] amount); /** * @dev Emitted by the staking module when `amount` tokens are unbonded from `validator` + * @param validator The validator operator address + * @param amount The amount of tokens unbonded */ event Unbond(address indexed validator, Cosmos.Coin[] amount); /** * @dev Emitted by the staking module when `amount` tokens are canceled from `delegator`'s * unbonding delegation with `validator` + * @param validator The validator operator address + * @param delegator The delegator address + * @param amount The amount of tokens canceled + * @param creationHeight The height at which the unbonding delegation was created */ event CancelUnbondingDelegation( address indexed validator, address indexed delegator, Cosmos.Coin[] amount, int64 creationHeight @@ -67,11 +80,13 @@ interface IStakingModule { /** * @dev Returns the operator address of the validator for the given consensus address. + * @param consAddr The consensus address (as bytes) of the validator */ function getValAddressFromConsAddress(bytes calldata consAddr) external pure returns (address); /** * @dev Returns a list of all active validators. + * @notice Accepts pagination request (empty == no pagination returned). */ function getValidators(Cosmos.PageRequest calldata pagination) external @@ -80,6 +95,7 @@ interface IStakingModule { /** * @dev Returns a list of bonded validator (operator) addresses. + * @notice Accepts pagination request (empty == no pagination returned). */ function getBondedValidators(Cosmos.PageRequest calldata pagination) external @@ -94,11 +110,14 @@ interface IStakingModule { /** * @dev Returns the validator at the given address. + * @param validatorAddress The validator operator address */ function getValidator(address validatorAddress) external view returns (Validator memory); /** * @dev Returns all the validators delegated to by the given delegator. + * @notice Accepts pagination request (empty == no pagination returned). + * @param delegatorAddress The delegator address to query validators for. */ function getDelegatorValidators(address delegatorAddress, Cosmos.PageRequest calldata pagination) external @@ -107,7 +126,8 @@ interface IStakingModule { /** * @dev Returns all the delegations delegated to the given validator. - * Note: if pagination is not a valid page request, it will execute without pagination + * @notice Accepts pagination request (empty == no pagination returned). + * @param validatorAddress The validator operator address to query delegations for. */ function getValidatorDelegations(address validatorAddress, Cosmos.PageRequest calldata pagination) external @@ -117,12 +137,16 @@ interface IStakingModule { /** * @dev Returns the `amount` of tokens currently delegated by `delegatorAddress` to * `validatorAddress` + * @param delegatorAddress The delegator address + * @param validatorAddress The validator operator address */ function getDelegation(address delegatorAddress, address validatorAddress) external view returns (uint256); /** * @dev Returns a time-ordered list of all UnbondingDelegationEntries between * `delegatorAddress` and `validatorAddress` + * @param delegatorAddress The delegator address + * @param validatorAddress The validator operator address */ function getUnbondingDelegation(address delegatorAddress, address validatorAddress) external @@ -131,6 +155,8 @@ interface IStakingModule { /** * @dev Returns a list of all unbonding delegations for a given delegator + * @notice Accepts pagination request (empty == no pagination returned). + * @param delegatorAddress The delegator address */ function getDelegatorUnbondingDelegations(address delegatorAddress, Cosmos.PageRequest calldata pagination) external @@ -140,6 +166,10 @@ interface IStakingModule { /** * @dev Returns a list of `delegatorAddress`'s redelegating bonds from `srcValidator` to * `dstValidator` + * @notice Accepts pagination request (empty == no pagination returned). + * @param delegatorAddress The delegator address + * @param srcValidator The source validator operator address + * @param dstValidator The destination validator operator address */ function getRedelegations( address delegatorAddress, @@ -152,16 +182,23 @@ interface IStakingModule { /** * @dev msg.sender delegates the `amount` of tokens to `validatorAddress` + * @param validatorAddress The validator operator address + * @param amount The amount of tokens to delegate */ function delegate(address validatorAddress, uint256 amount) external payable returns (bool); /** * @dev msg.sender undelegates the `amount` of tokens from `validatorAddress` + * @param validatorAddress The validator operator address + * @param amount The amount of tokens to undelegate */ function undelegate(address validatorAddress, uint256 amount) external payable returns (bool); /** * @dev msg.sender redelegates the `amount` of tokens from `srcValidator` to `validtorDstAddr` + * @param srcValidator The source validator operator address + * @param dstValidator The destination validator operator address + * @param amount The amount of tokens to redelegate */ function beginRedelegate(address srcValidator, address dstValidator, uint256 amount) external @@ -171,8 +208,9 @@ interface IStakingModule { /** * @dev Cancels msg.sender's unbonding delegation with `validatorAddress` and delegates the * `amount` of tokens back to `validatorAddress` - * - * Provide the `creationHeight` of the original unbonding delegation + * @param validatorAddress The validator operator address + * @param amount The amount of tokens to cancel + * @param creationHeight The height at which the unbonding delegation was created */ function cancelUnbondingDelegation(address validatorAddress, uint256 amount, int64 creationHeight) external @@ -230,9 +268,6 @@ interface IStakingModule { /** * @dev Represents one entry of an unbonding delegation - * - * Note: the field names of the native struct should match these field names (by camelCase) - * Note: we are using the types in precompile/generated */ struct UnbondingDelegationEntry { // creationHeight is the height which the unbonding took place @@ -249,9 +284,6 @@ interface IStakingModule { /** * @dev Represents all unbonding bonds of a single delegator with relevant metadata - * - * Note: the field names of the native struct should match these field names (by camelCase) - * Note: we are using the types in precompile/generated */ struct UnbondingDelegation { address delegatorAddress; @@ -261,9 +293,6 @@ interface IStakingModule { /** * @dev Represents a redelegation entry with relevant metadata - * - * Note: the field names of the native struct should match these field names (by camelCase) - * Note: we are using the types in precompile/generated */ struct RedelegationEntry { // creationHeight is the height which the redelegation took place