Merge remote-tracking branch 'origin/feature/governance' into feature…

…/governance

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>;
 }

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<u128, GovernanceError>;
 
+    ///Updates the quorum numerator
     #[ink(message)]
     fn update_quorum_numerator(&mut self, numerator: u128) -> Result<(), GovernanceError>;
 }

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;
 }

contracts/src/traits/governance/governor/mod.rs

@@ -39,55 +39,78 @@ 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,
         transactions: Vec<Transaction>,
         description_hash: HashType,
     ) -> Result<HashType, GovernanceError>;
 
+    ///Current state of a proposal, following Compound's convention
     #[ink(message)]
     fn state(&self, proposal_id: ProposalId) -> Result<ProposalState, GovernanceError>;
 
+    ///Returns timestamp at which votes for a proposal starts
     #[ink(message)]
     fn proposal_snapshot(&self, proposal_id: ProposalId) -> Result<Timestamp, GovernanceError>;
 
+    ///Returns timestamp at which votes for a proposal ends
     #[ink(message)]
     fn proposal_deadline(&self, proposal_id: ProposalId) -> Result<Timestamp, GovernanceError>;
 
+    ///Reeturns the AccountId of the proposer of a proposal
     #[ink(message)]
     fn proposal_proposer(&self, proposal_id: ProposalId) -> Result<AccountId, GovernanceError>;
 
+    ///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<u8>,
     ) -> Result<u128, GovernanceError>;
 
+    ///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<Transaction>, description: String) -> Result<ProposalId, GovernanceError>;
 
+    ///Executes a proposal if it is in the `Succeeded` state.
+    /// Returns the id of the executed proposal
     #[ink(message)]
     fn execute(
         &mut self,
         transactions: Vec<Transaction>,
         description_hash: HashType,
     ) -> Result<ProposalId, GovernanceError>;
 
+    ///Cancels a proposal if it is in the `Pending` state.
+    /// Returns the id of the cancelled proposal
     #[ink(message)]
     fn cancel(
         &mut self,
         transactions: Vec<Transaction>,
         description_hash: HashType,
     ) -> Result<ProposalId, GovernanceError>;
 
+    ///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<Balance, GovernanceError>;
 
+    ///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<Balance, GovernanceError>;
 
+    ///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<u8>,
     ) -> Result<Balance, GovernanceError>;
 
+    ///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<Balance, GovernanceError>;
 
+    ///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<u8>,
     ) -> Result<Balance, GovernanceError>;
 
+    ///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>;
 }

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<Balance, GovernanceError>;
 
+    ///The amount of votes delegated to `account` at the time `timestamp`.
     #[ink(message)]
     fn get_past_votes(&self, account: AccountId, timestamp: Timestamp) -> Result<Balance, GovernanceError>;
 
+    ///The total amount of votes at the time `timestamp`.
     #[ink(message)]
     fn get_past_total_supply(&self, timestamp: Timestamp) -> Result<Balance, GovernanceError>;
 
+    ///Returns the address delegated to by `delegator`.
     #[ink(message)]
     fn delegates(&mut self, delegator: AccountId) -> Option<AccountId>;
 
+    ///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,

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<u32, GovernanceError>;
 
+    ///Get the `pos`-th checkpoint for `account`.
     #[ink(message)]
     fn checkpoints(&self, account: AccountId, pos: u32) -> Result<Checkpoint, GovernanceError>;
 }

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;
 }