chore: add comments (#537)

* i_execution_strategy * i_proposal_validation_strategy * i_execution_strategy * i_quorum * i_quorum * i_quorum * i_voting_strategy * proposing_power.cairo * i_proposal_validation_strategy * vanilla proposing strategy * vanilla proposal strategy * choice.cairo * finalization status * indexed strategy * Proposal Status * proposing power * proposal.cairo * strategy * add todo * update settings calldata * user address * user address * update settings * merkle.cairo * utils proposition power * reinitializable * reinitializable * stark_eip712 * add link to off-chain sig SNIP * struct_hash * erc20_votes * eth_balance_of * erc20_votes * vanilla voting strategy * merkle_whitelist * eth balance of address * erc20 votes starknet address * space interface * eth_sig * eth_tx * vanilla auth * stark_sig auth * stark_tx auth * vanilla execution strategy * simple quorum * eth_relayer * emove print in vanilla auth * iethtxauthenticator update * fix eip712 spelling * comments on eth relayer * payload description * newly executed * optional trait * voting power at * the voting delay in seconds * comments for min_voting_duration * max voting duration comment * next voting strategy index comment * propose comments * vote comments * IndexedStrategy comment * proposal comments * active voting strategies comment * Strategy comment
snapshot-labs · Sep 8, 2023 · a4119c3 · a4119c3
1 parent e2c1296
commit a4119c3
Show file tree

Hide file tree

Showing 32 changed files with 493 additions and 11 deletions.
diff --git a/starknet/src/authenticators/eth_sig.cairo b/starknet/src/authenticators/eth_sig.cairo
@@ -3,6 +3,19 @@ use sx::types::{Strategy, IndexedStrategy, Choice};
 
 #[starknet::interface]
 trait IEthSigAuthenticator<TContractState> {
+    /// Authenticates a propose transaction, by checking the signature using EIP712.
+    /// 
+    /// # Arguments
+    ///
+    /// * `r` - The `r` component of the signature.
+    /// * `s` - The `s` component of the signature.
+    /// * `v` - The `v` component of the signature.
+    /// * `space` - The address of the space contract.
+    /// * `author` - The address of the author of the proposal.
+    /// * `metadata_uri` - The URI of the proposal's metadata.
+    /// * `execution_strategy` - The execution strategy of the proposal.
+    /// * `user_proposal_validation_params` - The user proposal validation params.
+    /// * `salt` - The salt, used for replay protection.
     fn authenticate_propose(
         ref self: TContractState,
         r: u256,
@@ -15,6 +28,21 @@ trait IEthSigAuthenticator<TContractState> {
         user_proposal_validation_params: Array<felt252>,
         salt: u256,
     );
+
+    /// Authenticates a vote transaction, by checking the signature using EIP712.
+    /// Salt is not needed here as the space contract prevents double voting.
+    ///
+    /// # Arguments
+    ///
+    /// * `r` - The `r` component of the signature.
+    /// * `s` - The `s` component of the signature.
+    /// * `v` - The `v` component of the signature.
+    /// * `space` - The address of the space contract.
+    /// * `voter` - The address of the voter.
+    /// * `proposal_id` - The ID of the proposal.
+    /// * `choice` - The choice of the voter.
+    /// * `user_voting_strategies` - The user voting strategies.
+    /// * `metadata_uri` - The URI of the proposal's metadata.
     fn authenticate_vote(
         ref self: TContractState,
         r: u256,
@@ -27,6 +55,20 @@ trait IEthSigAuthenticator<TContractState> {
         user_voting_strategies: Array<IndexedStrategy>,
         metadata_uri: Array<felt252>,
     );
+
+    /// Authenticates an update proposal transaction, by checking the signature using EIP712.
+    ///
+    /// # Arguments
+    ///
+    /// * `r` - The `r` component of the signature.
+    /// * `s` - The `s` component of the signature.
+    /// * `v` - The `v` component of the signature.
+    /// * `space` - The address of the space contract.
+    /// * `author` - The address of the author of the proposal.
+    /// * `proposal_id` - The ID of the proposal.
+    /// * `execution_strategy` - The new execution strategy that will replace the old one.
+    /// * `metadata_uri` - The new URI that will replace the old one.
+    /// * `salt` - The salt, used for replay protection.
     fn authenticate_update_proposal(
         ref self: TContractState,
         r: u256,

diff --git a/starknet/src/authenticators/eth_tx.cairo b/starknet/src/authenticators/eth_tx.cairo
@@ -3,6 +3,16 @@ use sx::types::{Strategy, IndexedStrategy, Choice};
 
 #[starknet::interface]
 trait IEthTxAuthenticator<TContractState> {
+    /// Authenticates a propose transaction by checking that `author` has indeed sent a transaction from L1
+    /// to the bridge contract.
+    ///
+    /// # Arguments
+    ///
+    /// * `target` - The address of the contract to which the transaction is sent.
+    /// * `author` - The author of the proposal. Expected to be an ethereum address.
+    /// * `metadata_uri` - The metadata URI of the proposal.
+    /// * `execution_strategy` - The execution strategy of the proposal.
+    /// * `user_proposal_validation_params` - The user proposal validation params of the proposal.
     fn authenticate_propose(
         ref self: TContractState,
         target: ContractAddress,
@@ -11,6 +21,18 @@ trait IEthTxAuthenticator<TContractState> {
         execution_strategy: Strategy,
         user_proposal_validation_params: Array<felt252>,
     );
+
+    /// Authenticates a vote transaction by checking that `voter` has indeed sent a transaction from L1
+    /// to the bridge contract.
+    ///
+    /// # Arguments
+    ///
+    /// * `target` - The address of the contract to which the transaction is sent.
+    /// * `voter` - The voter. Expected to be an ethereum address.
+    /// * `proposal_id` - The id of the proposal.
+    /// * `choice` - The choice of the vote.
+    /// * `user_voting_strategies` - The user voting strategies of the vote.
+    /// * `metadata_uri` - The metadata URI of the vote.
     fn authenticate_vote(
         ref self: TContractState,
         target: ContractAddress,
@@ -20,6 +42,17 @@ trait IEthTxAuthenticator<TContractState> {
         user_voting_strategies: Array<IndexedStrategy>,
         metadata_uri: Array<felt252>
     );
+
+    /// Authenticates an update_proposal transaction by checking that `author` has indeed sent a transaction from L1
+    /// to the bridge contract.
+    ///
+    /// # Arguments
+    ///
+    /// * `target` - The address of the contract to which the transaction is sent.
+    /// * `author` - The author of the proposal. Expected to be an ethereum address.
+    /// * `proposal_id` - The id of the proposal.
+    /// * `execution_strategy` - The execution strategy of the proposal.
+    /// * `metadata_uri` - The metadata URI of the proposal.
     fn authenticate_update_proposal(
         ref self: TContractState,
         target: ContractAddress,

diff --git a/starknet/src/authenticators/stark_sig.cairo b/starknet/src/authenticators/stark_sig.cairo
@@ -1,8 +1,21 @@
 use starknet::ContractAddress;
 use sx::types::{Strategy, IndexedStrategy, Choice};
 
+/// See https://community.starknet.io/t/snip-off-chain-signatures-a-la-eip712/98029
 #[starknet::interface]
 trait IStarkSigAuthenticator<TContractState> {
+    /// Authenticates a propose transaction using the starknet EIP712-equivalent signature scheme.
+    /// 
+    /// # Arguments
+    ///
+    /// * `signature` - The signature of message digest.
+    /// * `target` - The address of the space contract.
+    /// * `author` - The starkent address of the author of the proposal.
+    /// * `metadata_uri` - The URI of the proposal metadata.
+    /// * `execution_strategy` - The execution strategy of the proposal.
+    /// * `user_proposal_validation_params` - The user proposal validation params of the proposal.
+    /// * `salt` - The salt, used for replay protection.
+    /// * `account_type` - The account type of the author ('snake' or 'camel').
     fn authenticate_propose(
         ref self: TContractState,
         signature: Array<felt252>,
@@ -14,6 +27,22 @@ trait IStarkSigAuthenticator<TContractState> {
         salt: felt252,
         account_type: felt252
     );
+
+
+    /// Authenticates a vote transaction using the starknet EIP712-equivalent signature scheme.
+    /// Salt is not needed because double voting is prevented by the space itself.
+    ///
+    /// # Arguments
+    ///
+    /// * `signature` - The signature of message digest.
+    /// * `target` - The address of the space contract.
+    /// * `voter` - The starkent address of the voter.
+    /// * `proposal_id` - The id of the proposal.
+    /// * `choice` - The choice of the voter.
+    /// * `user_voting_strategies` - The user voting strategies of the voter.
+    /// * `metadata_uri` - The URI of the proposal metadata.
+    /// * `account_type` - The account type of the voter ('snake' or 'camel').
+    ///
     fn authenticate_vote(
         ref self: TContractState,
         signature: Array<felt252>,
@@ -25,6 +54,19 @@ trait IStarkSigAuthenticator<TContractState> {
         metadata_uri: Array<felt252>,
         account_type: felt252
     );
+
+    /// Authenticates an update proposal transaction using the starknet EIP712-equivalent signature scheme.
+    ///
+    /// # Arguments
+    ///
+    /// * `signature` - The signature of message digest.
+    /// * `target` - The address of the space contract.
+    /// * `author` - The starkent address of the author of the proposal.
+    /// * `proposal_id` - The id of the proposal.
+    /// * `execution_strategy` - The execution strategy of the proposal.
+    /// * `metadata_uri` - The URI of the proposal metadata.
+    /// * `salt` - The salt, used for replay protection.
+    /// * `account_type` - The account type of the author ('snake' or 'camel').
     fn authenticate_update_proposal(
         ref self: TContractState,
         signature: Array<felt252>,

diff --git a/starknet/src/authenticators/stark_tx.cairo b/starknet/src/authenticators/stark_tx.cairo
@@ -3,6 +3,15 @@ use sx::types::{Strategy, IndexedStrategy, Choice};
 
 #[starknet::interface]
 trait IStarkTxAuthenticator<TContractState> {
+    /// Authenticates a propose transaction by checking that the message sender is indeed `author`.
+    ///
+    /// # Arguments
+    ///
+    /// * `space` - The address of the space contract.
+    /// * `author` - The starknet address of the author.
+    /// * `metadata_uri` - The URI of the metadata.
+    /// * `execution_strategy` - The execution strategy of the proposal.
+    /// * `user_proposal_validation_params` - The user proposal validation params.
     fn authenticate_propose(
         ref self: TContractState,
         space: ContractAddress,
@@ -11,6 +20,17 @@ trait IStarkTxAuthenticator<TContractState> {
         execution_strategy: Strategy,
         user_proposal_validation_params: Array<felt252>,
     );
+
+    /// Authenticates a vote transaction by checking that the message sender is indeed `voter`.
+    ///
+    /// # Arguments
+    ///
+    /// * `space` - The address of the space contract.
+    /// * `voter` - The starknet address of the voter.
+    /// * `proposal_id` - The id of the proposal.
+    /// * `choice` - The choice of the voter.
+    /// * `user_voting_strategies` - The user voting strategies.
+    /// * `metadata_uri` - The URI of the metadata.
     fn authenticate_vote(
         ref self: TContractState,
         space: ContractAddress,
@@ -20,6 +40,16 @@ trait IStarkTxAuthenticator<TContractState> {
         user_voting_strategies: Array<IndexedStrategy>,
         metadata_uri: Array<felt252>
     );
+
+    /// Authenticates an update proposal transaction by checking that the message sender is indeed `author`.
+    ///
+    /// # Arguments
+    ///
+    /// * `space` - The address of the space contract.
+    /// * `author` - The starknet address of the author.
+    /// * `proposal_id` - The id of the proposal.
+    /// * `execution_strategy` - The execution strategy of the proposal.
+    /// * `metadata_uri` - The URI of the metadata.
     fn authenticate_update_proposal(
         ref self: TContractState,
         space: ContractAddress,

diff --git a/starknet/src/authenticators/vanilla.cairo b/starknet/src/authenticators/vanilla.cairo
@@ -2,6 +2,7 @@ use starknet::{ContractAddress, SyscallResult};
 
 #[starknet::interface]
 trait IVanillaAuthenticator<TContractState> {
+    /// Forwards the call to the target contract, no questions asked.
     fn authenticate(
         ref self: TContractState, target: ContractAddress, selector: felt252, data: Array<felt252>
     );

diff --git a/starknet/src/execution_strategies/eth_relayer.cairo b/starknet/src/execution_strategies/eth_relayer.cairo
@@ -11,6 +11,18 @@ mod EthRelayerExecutionStrategy {
     #[storage]
     struct Storage {}
 
+    /// Forwards the proposal data to the L1 execution strategy specified in the payload argument via
+    /// the Starknet<->L1 bridge. Since this contract does not check who is calling it, it is the
+    /// responsibility of the L1 contract to check that the caller is indeed an authorized
+    /// space contract (this information is sent to the bridge).
+    ///
+    /// # Arguments
+    ///
+    /// * proposal - The proposal to execute.
+    /// * votes_for - The number of votes for the proposal.
+    /// * votes_against - The number of votes against the proposal.
+    /// * votes_abstain - The number of votes abstaining from the proposal.
+    /// * payload - An array containing the serialized L1 execution strategy address and the L1 execution hash.
     #[external(v0)]
     impl EthRelayerExecutionStrategy of IExecutionStrategy<ContractState> {
         fn execute(
@@ -54,6 +66,7 @@ mod EthRelayerExecutionStrategy {
             'EthRelayer'
         }
 
+        /// Errors when called. The proposal status is only available on the L1 contract.
         fn get_proposal_status(
             self: @ContractState,
             proposal: Proposal,

diff --git a/starknet/src/execution_strategies/simple_quorum.cairo b/starknet/src/execution_strategies/simple_quorum.cairo
@@ -22,6 +22,14 @@ mod SimpleQuorumExecutionStrategy {
     }
 
     #[internal]
+    /// Returns the status of a proposal.
+    /// To be accepted, a proposal must be supported by a majority of votes, have reached the quorum,
+    /// and have the current timetsamp must be greater or equal to `max_end_timestamp`.
+    /// If the proposal is has a majority of votes and have reached the quorum,
+    /// then it can be early accepted (it will return `VotingPeriodAccepted`) provided the current timestamp is
+    /// between `min_end_timestamp` and `max_end_timestamp`.
+    /// Spaces that don't want to deal with early accepting proposals should set `min_voting_duration` and `max_voting_duration`
+    /// to the same value.
     fn get_proposal_status(
         self: @ContractState,
         proposal: @Proposal,

diff --git a/starknet/src/execution_strategies/vanilla.cairo b/starknet/src/execution_strategies/vanilla.cairo
@@ -19,6 +19,8 @@ mod VanillaExecutionStrategy {
         }
     }
 
+    /// The vanilla execution strategy is a dummy execution strategy that simply increments a `_num_executed` variable for every
+    /// newly executed proposal. It uses the `SimpleQuorum` method to determine whether a proposal is accepted or not.
     #[external(v0)]
     impl VanillaExecutionStrategy of IExecutionStrategy<ContractState> {
         fn execute(

diff --git a/starknet/src/interfaces/i_execution_strategy.cairo b/starknet/src/interfaces/i_execution_strategy.cairo
@@ -1,7 +1,19 @@
 use sx::types::{Proposal, ProposalStatus};
 
+/// The execution strategy interface that all execution strategies must implement.
 #[starknet::interface]
 trait IExecutionStrategy<TContractState> {
+    /// The space contract will call this function when a proposal is `execute`-ed.
+    /// It is up to the `execute` function to perform the necessary
+    /// checks to ensure that the proposal should be executed.
+    ///
+    /// # Arguments
+    ///
+    /// * `proposal` - The proposal to execute.
+    /// * `votes_for` - The number of votes for the proposal.
+    /// * `votes_against` - The number of votes against the proposal.
+    /// * `votes_abstain` - The number of votes abstaining from the proposal.
+    /// * `payload` - The payload of the proposal.
     fn execute(
         ref self: TContractState,
         proposal: Proposal,
@@ -11,6 +23,18 @@ trait IExecutionStrategy<TContractState> {
         payload: Array<felt252>
     );
 
+    /// View function to get the proposal status.
+    ///
+    /// # Arguments
+    ///
+    /// * `proposal` - The proposal to get the status for.
+    /// * `votes_for` - The number of votes for the proposal.
+    /// * `votes_against` - The number of votes against the proposal.
+    /// * `votes_abstain` - The number of votes abstaining from the proposal.
+    ///
+    /// # Returns
+    ///
+    /// * `ProposalStatus` - The status of the proposal.
     fn get_proposal_status(
         self: @TContractState,
         proposal: Proposal,
@@ -19,5 +43,6 @@ trait IExecutionStrategy<TContractState> {
         votes_abstain: u256,
     ) -> ProposalStatus;
 
+    /// Returns a short string describing the strategy type.
     fn get_strategy_type(self: @TContractState) -> felt252;
 }
diff --git a/starknet/src/interfaces/i_proposal_validation_strategy.cairo b/starknet/src/interfaces/i_proposal_validation_strategy.cairo
@@ -3,6 +3,16 @@ use sx::types::UserAddress;
 
 #[starknet::interface]
 trait IProposalValidationStrategy<TContractState> {
+    /// Validates whether `author` has the right to create a new proposal or not.
+    /// # Arguments
+    /// 
+    /// * `author` - The address of the proposal author.
+    /// * `params` - Strategy-supplied parameters, stored in the space contract and defined by the space owner.
+    /// * `user_params` - User-supplied parameters.
+    ///
+    /// # Returns
+    /// 
+    /// * `bool` - `true` if `author` has the right to create a new proposal. `false` otherwise.
     fn validate(
         self: @TContractState,
         author: UserAddress,

diff --git a/starknet/src/interfaces/i_quorum.cairo b/starknet/src/interfaces/i_quorum.cairo
@@ -1,4 +1,6 @@
+/// Optional trait that execution strategies can decide to implement.
 #[starknet::interface]
 trait IQuorum<TContractState> {
+    /// Returns the `quorum` value of an execution strategy.
     fn quorum(self: @TContractState) -> u256;
 }
diff --git a/starknet/src/interfaces/i_voting_strategy.cairo b/starknet/src/interfaces/i_voting_strategy.cairo
@@ -3,6 +3,18 @@ use sx::types::UserAddress;
 
 #[starknet::interface]
 trait IVotingStrategy<TContractState> {
+    /// 
+    ///
+    /// # Arguments
+    ///
+    /// * `timestamp` - The timestamp to use to compute the voting power at.
+    /// * `voter` - The address of the voter.
+    /// * `params` - The strategy-supplied parameters used to compute the voting power.
+    /// * `user_params` - The user-supplied parameters used to compute the voting power.
+    ///
+    /// # Returns
+    ///
+    /// * `u256` - The voting power of the voter.
     fn get_voting_power(
         self: @TContractState,
         timestamp: u32,