From 2411de97810eef6bc1beb168d0c105bcd5b30940 Mon Sep 17 00:00:00 2001 From: prxgr4mm3r Date: Wed, 16 Aug 2023 16:18:07 +0300 Subject: [PATCH] add inline docs to traits --- .../extensions/governor_counting/mod.rs | 6 ++++ .../extensions/governor_quorum/mod.rs | 10 ++++-- .../extensions/governor_settings/mod.rs | 8 +++++ .../src/traits/governance/governor/mod.rs | 32 ++++++++++++++++++- .../src/traits/governance/utils/votes.rs | 7 ++++ .../src/traits/psp22/extensions/votes.rs | 11 +++++++ contracts/src/traits/utils/nonces.rs | 2 ++ 7 files changed, 73 insertions(+), 3 deletions(-) diff --git a/contracts/src/traits/governance/extensions/governor_counting/mod.rs b/contracts/src/traits/governance/extensions/governor_counting/mod.rs index 5363d5ee1..edcfa07a4 100644 --- a/contracts/src/traits/governance/extensions/governor_counting/mod.rs +++ b/contracts/src/traits/governance/extensions/governor_counting/mod.rs @@ -30,14 +30,20 @@ use openbrush::traits::{ String, }; +///Extension of {Governor} for simple, 3 options, vote counting. #[openbrush::trait_definition] pub trait GovernorCounting { + ///Returns the current counting mode #[ink(message)] fn counting_mode(&self) -> String; + ///Returns `true` if the account has voted for the proposal, `false` otherwise #[ink(message)] fn has_voted(&self, proposal_id: ProposalId, account: AccountId) -> bool; + ///Returns the tuple (for, against, abstain) votes for a proposal, where `for` is the total + ///number of votes for the proposal, `against` is the total number of votes against the + ///proposal, and `abstain` is the total number of abstained votes. #[ink(message)] fn proposal_votes(&self, proposal_id: ProposalId) -> Result<(Balance, Balance, Balance), GovernanceError>; } diff --git a/contracts/src/traits/governance/extensions/governor_quorum/mod.rs b/contracts/src/traits/governance/extensions/governor_quorum/mod.rs index 5867e9d78..2f214f8f8 100644 --- a/contracts/src/traits/governance/extensions/governor_quorum/mod.rs +++ b/contracts/src/traits/governance/extensions/governor_quorum/mod.rs @@ -23,20 +23,26 @@ use crate::traits::errors::GovernanceError; use openbrush::traits::Timestamp; +///Extension of {Governor} for voting weight extraction from an {PSP22Votes} token and a quorum expressed as a +///fraction of the total supply. #[openbrush::trait_definition] pub trait Quorum { + ///Returns the current quorum numerator #[ink(message)] fn quorum_numerator(&self) -> u128; - + ///Returns the quorum numerator at a given timestamp #[ink(message)] - fn quorum_numerator_at(&self, time_point: Timestamp) -> u128; + fn quorum_numerator_at(&self, timestamp: Timestamp) -> u128; + ///Returns the current quorum denominator #[ink(message)] fn quorum_denominator(&self) -> u128; + ///Returns the quorum at a given timestamp #[ink(message)] fn quorum(&self, time_point: Timestamp) -> Result; + ///Updates the quorum numerator #[ink(message)] fn update_quorum_numerator(&mut self, numerator: u128) -> Result<(), GovernanceError>; } diff --git a/contracts/src/traits/governance/extensions/governor_settings/mod.rs b/contracts/src/traits/governance/extensions/governor_settings/mod.rs index 0e9e8c61d..5dcc0da5b 100644 --- a/contracts/src/traits/governance/extensions/governor_settings/mod.rs +++ b/contracts/src/traits/governance/extensions/governor_settings/mod.rs @@ -22,23 +22,31 @@ use crate::traits::errors::GovernanceError; + +///Extension of {Governor} for settings updatable through governance. #[openbrush::trait_definition] pub trait GovernorSettings { + ///Sets the voting delay #[ink(message)] fn set_voting_delay(&mut self, new_voting_delay: u64) -> Result<(), GovernanceError>; + ///Sets the voting period #[ink(message)] fn set_voting_period(&mut self, new_voting_period: u64) -> Result<(), GovernanceError>; + ///Sets the proposal threshold #[ink(message)] fn set_proposal_threshold(&mut self, new_proposal_threshold: u128) -> Result<(), GovernanceError>; + ///Returns the voting delay #[ink(message)] fn voting_delay(&self) -> u64; + ///Returns the voting period #[ink(message)] fn voting_period(&self) -> u64; + ///Returns the proposal threshold #[ink(message)] fn proposal_threshold(&self) -> u128; } diff --git a/contracts/src/traits/governance/governor/mod.rs b/contracts/src/traits/governance/governor/mod.rs index 02e5ea3e1..831699a47 100644 --- a/contracts/src/traits/governance/governor/mod.rs +++ b/contracts/src/traits/governance/governor/mod.rs @@ -39,8 +39,16 @@ use openbrush::traits::{ Timestamp, }; +///Core of the governance system, designed to be extended though various modules. +/// +///This contract is abstract and requires several functions to be implemented in various modules: +/// +/// - A counting module must implement {quorum}, {_quorumReached}, {_voteSucceeded} and {_countVote} +/// - A voting module must implement {_getVotes} +/// - Additionally, {votingPeriod} must also be implemented #[openbrush::trait_definition] pub trait Governor { + ///Hashing function used to (re)build the proposal id from the proposal details. #[ink(message)] fn hash_proposal( &self, @@ -48,29 +56,38 @@ pub trait Governor { description_hash: HashType, ) -> Result; + ///Current state of a proposal, following Compound's convention #[ink(message)] fn state(&self, proposal_id: ProposalId) -> Result; + ///Returns timestamp at which votes for a proposal starts #[ink(message)] fn proposal_snapshot(&self, proposal_id: ProposalId) -> Result; + ///Returns timestamp at which votes for a proposal ends #[ink(message)] fn proposal_deadline(&self, proposal_id: ProposalId) -> Result; + ///Reeturns the AccountId of the proposer of a proposal #[ink(message)] fn proposal_proposer(&self, proposal_id: ProposalId) -> Result; + ///Returns the number of votes already casted for a proposal by a given account #[ink(message)] fn get_votes_with_params( &mut self, account: AccountId, - time_point: Timestamp, + timestamp: Timestamp, params: Vec, ) -> Result; + ///Makes a proposal for a list of transactions to be executed. + /// Returns the id of the proposal #[ink(message)] fn propose(&mut self, transactions: Vec, description: String) -> Result; + ///Executes a proposal if it is in the `Succeeded` state. + /// Returns the id of the executed proposal #[ink(message)] fn execute( &mut self, @@ -78,6 +95,8 @@ pub trait Governor { description_hash: HashType, ) -> Result; + ///Cancels a proposal if it is in the `Pending` state. + /// Returns the id of the cancelled proposal #[ink(message)] fn cancel( &mut self, @@ -85,9 +104,13 @@ pub trait Governor { description_hash: HashType, ) -> Result; + ///Casts a vote for a proposal from a message sender. + /// Returns the number of votes already casted for the proposal by the sender #[ink(message)] fn cast_vote(&mut self, proposal_id: ProposalId, support: VoteType) -> Result; + ///Casts a vote with reason for a proposal from a message sender. + /// Returns the number of votes already casted for the proposal by the sender #[ink(message)] fn cast_vote_with_reason( &mut self, @@ -96,6 +119,8 @@ pub trait Governor { reason: String, ) -> Result; + ///Casts a vote with reason and parameters for a proposal from a message sender. + /// Returns the number of votes already casted for the proposal by the sender #[ink(message)] fn cast_vote_with_reason_and_params( &mut self, @@ -105,6 +130,7 @@ pub trait Governor { params: Vec, ) -> Result; + ///Casts a vote with signature for a proposal from a message sender. Returns the number of votes already casted for the proposal by the sender #[ink(message)] fn cast_vote_with_signature( &mut self, @@ -114,6 +140,7 @@ pub trait Governor { signature: SignatureType, ) -> Result; + ///Casts a vote with signature and parameters for a proposal from a message sender. Returns the number of votes already casted for the proposal by the sender #[ink(message)] fn cast_vote_with_signature_and_params( &mut self, @@ -124,6 +151,9 @@ pub trait Governor { params: Vec, ) -> Result; + ///Relays a transaction or function call to an arbitrary target. In cases where the governance executor + ///is some contract other than the governor itself, like when using a timelock, this function can be invoked + ///in a governance proposal to recover tokens or Ether that was sent to the governor contract by mistake. #[ink(message)] fn relay(&mut self, target: AccountId, transaction: Transaction) -> Result<(), GovernanceError>; } diff --git a/contracts/src/traits/governance/utils/votes.rs b/contracts/src/traits/governance/utils/votes.rs index f17114a7f..004cd5497 100644 --- a/contracts/src/traits/governance/utils/votes.rs +++ b/contracts/src/traits/governance/utils/votes.rs @@ -30,23 +30,30 @@ use openbrush::traits::{ Timestamp, }; +///Common interface for {PSP22Votes}, and other {Votes}-enabled contracts. #[openbrush::trait_definition] pub trait Votes { + ///The amount of votes owned by `account`. #[ink(message)] fn get_votes(&self, account: AccountId) -> Result; + ///The amount of votes delegated to `account` at the time `timestamp`. #[ink(message)] fn get_past_votes(&self, account: AccountId, timestamp: Timestamp) -> Result; + ///The total amount of votes at the time `timestamp`. #[ink(message)] fn get_past_total_supply(&self, timestamp: Timestamp) -> Result; + ///Returns the address delegated to by `delegator`. #[ink(message)] fn delegates(&mut self, delegator: AccountId) -> Option; + ///Delegate votes from `signer` to `delegatee`. #[ink(message)] fn delegate(&mut self, delegatee: AccountId) -> Result<(), GovernanceError>; + ///Delegate votes from `signer` to `delegatee` using a signature. #[ink(message)] fn delegate_by_signature( &mut self, diff --git a/contracts/src/traits/psp22/extensions/votes.rs b/contracts/src/traits/psp22/extensions/votes.rs index aa14b232f..c239524e4 100644 --- a/contracts/src/traits/psp22/extensions/votes.rs +++ b/contracts/src/traits/psp22/extensions/votes.rs @@ -28,11 +28,22 @@ use crate::{ }, }; use openbrush::traits::AccountId; + +///Extension of ERC20 to support Compound-like voting and delegation. +/// +/// This extension keeps a history (checkpoints) of each account's vote power. Vote power can be delegated either +/// by calling the {delegate} function directly, or by providing a signature to be used with {delegateBySig}. Voting +/// power can be queried through the public accessors {getVotes} and {getPastVotes}. +/// +/// By default, token balance does not account for voting power. This makes transfers cheaper. The downside is that it +/// requires users to delegate to themselves in order to activate checkpoints and have their voting power tracked. #[openbrush::trait_definition] pub trait PSP22Votes { + ///Get number of checkpoints for `account`. #[ink(message)] fn num_checkpoints(&self, account: AccountId) -> Result; + ///Get the `pos`-th checkpoint for `account`. #[ink(message)] fn checkpoints(&self, account: AccountId, pos: u32) -> Result; } diff --git a/contracts/src/traits/utils/nonces.rs b/contracts/src/traits/utils/nonces.rs index aa5b59c23..ba7c5c43f 100644 --- a/contracts/src/traits/utils/nonces.rs +++ b/contracts/src/traits/utils/nonces.rs @@ -1,7 +1,9 @@ use openbrush::traits::AccountId; +///Provides tracking nonces for addresses. Nonces will only increment. #[openbrush::trait_definition] pub trait Nonces { + ///Returns the nonce of `account`. #[ink(message)] fn nonces(&self, account: AccountId) -> u128; }