From c87cb0fb491673ab755ee0bba13fb0f031c2a763 Mon Sep 17 00:00:00 2001 From: Giorgi Lagidze Date: Sun, 17 Nov 2024 18:43:27 +0400 Subject: [PATCH] new --- packages/contracts/docs/IMajorityVoting.md | 266 ----- packages/contracts/docs/MajorityVotingBase.md | 953 ------------------ packages/contracts/docs/TokenVoting.md | 253 ----- packages/contracts/docs/TokenVotingSetup.md | 155 --- .../contracts/docs/VotingPowerCondition.md | 46 - packages/contracts/docs/templates/helpers.js | 8 - .../contracts/docs/templates/properties.js | 14 - packages/contracts/scripts/prepare-docs.sh | 10 - 8 files changed, 1705 deletions(-) delete mode 100644 packages/contracts/docs/IMajorityVoting.md delete mode 100644 packages/contracts/docs/MajorityVotingBase.md delete mode 100644 packages/contracts/docs/TokenVoting.md delete mode 100644 packages/contracts/docs/TokenVotingSetup.md delete mode 100644 packages/contracts/docs/VotingPowerCondition.md diff --git a/packages/contracts/docs/IMajorityVoting.md b/packages/contracts/docs/IMajorityVoting.md deleted file mode 100644 index c76ef8c1..00000000 --- a/packages/contracts/docs/IMajorityVoting.md +++ /dev/null @@ -1,266 +0,0 @@ -# Solidity API - -## IMajorityVoting - -The interface of majority voting plugin. - -### VoteOption - -```solidity -enum VoteOption { - None, - Abstain, - Yes, - No -} -``` - -### VoteCast - -```solidity -event VoteCast(uint256 proposalId, address voter, enum IMajorityVoting.VoteOption voteOption, uint256 votingPower) -``` - -Emitted when a vote is cast by a voter. - -#### Parameters - -| Name | Type | Description | -| ----------- | ------------------------------- | ---------------------------------- | -| proposalId | uint256 | The ID of the proposal. | -| voter | address | The voter casting the vote. | -| voteOption | enum IMajorityVoting.VoteOption | The casted vote option. | -| votingPower | uint256 | The voting power behind this vote. | - -### supportThreshold - -```solidity -function supportThreshold() external view returns (uint32) -``` - -Returns the support threshold parameter stored in the voting settings. - -#### Return Values - -| Name | Type | Description | -| ---- | ------ | -------------------------------- | -| [0] | uint32 | The support threshold parameter. | - -### minApproval - -```solidity -function minApproval() external view returns (uint256) -``` - -Returns the configured minimum approval value. - -#### Return Values - -| Name | Type | Description | -| ---- | ------- | --------------------------- | -| [0] | uint256 | The minimal approval value. | - -### minParticipation - -```solidity -function minParticipation() external view returns (uint32) -``` - -Returns the minimum participation parameter stored in the voting settings. - -#### Return Values - -| Name | Type | Description | -| ---- | ------ | ------------------------------------ | -| [0] | uint32 | The minimum participation parameter. | - -### isSupportThresholdReached - -```solidity -function isSupportThresholdReached(uint256 _proposalId) external view returns (bool) -``` - -Checks if the support value defined as: -$$\texttt{support} = \frac{N_\text{yes}}{N_\text{yes}+N_\text{no}}$$ -for a proposal is greater than the support threshold. - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | ----------------------- | -| \_proposalId | uint256 | The ID of the proposal. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ------------------------------------------------------------------------------------------ | -| [0] | bool | Returns `true` if the support is greater than the support threshold and `false` otherwise. | - -### isSupportThresholdReachedEarly - -```solidity -function isSupportThresholdReachedEarly(uint256 _proposalId) external view returns (bool) -``` - -Checks if the worst-case support value defined as: -$$\texttt{worstCaseSupport} = \frac{N_\text{yes}}{ N_\text{total}-N_\text{abstain}}$$ -for a proposal is greater than the support threshold. - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | ----------------------- | -| \_proposalId | uint256 | The ID of the proposal. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------------------------------------------------------------------------------------------------- | -| [0] | bool | Returns `true` if the worst-case support is greater than the support threshold and `false` otherwise. | - -### isMinParticipationReached - -```solidity -function isMinParticipationReached(uint256 _proposalId) external view returns (bool) -``` - -Checks if the participation value defined as: -$$\texttt{participation} = \frac{N_\text{yes}+N_\text{no}+N_\text{abstain}}{N_\text{total}}$$ -for a proposal is greater or equal than the minimum participation value. - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | ----------------------- | -| \_proposalId | uint256 | The ID of the proposal. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | -------------------------------------------------------------------------------------------------------------- | -| [0] | bool | Returns `true` if the participation is greater or equal than the minimum participation, and `false` otherwise. | - -### isMinApprovalReached - -```solidity -function isMinApprovalReached(uint256 _proposalId) external view returns (bool) -``` - -Checks if the min approval value defined as: -$$\texttt{minApproval} = \frac{N_\text{yes}}{N_\text{total}}$$ -for a proposal is greater or equal than the minimum approval value. - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | ----------------------- | -| \_proposalId | uint256 | The ID of the proposal. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ---------------------------------------------------------------------------------------------------- | -| [0] | bool | Returns `true` if the approvals is greater or equal than the minimum approval and `false` otherwise. | - -### canVote - -```solidity -function canVote(uint256 _proposalId, address _account, enum IMajorityVoting.VoteOption _voteOption) external view returns (bool) -``` - -Checks if an account can participate on a proposal. This can be because the vote - -- has not started, -- has ended, -- was executed, or -- the voter doesn't have voting powers. - -#### Parameters - -| Name | Type | Description | -| ------------ | ------------------------------- | ------------------------------------------------------------- | -| \_proposalId | uint256 | The proposal Id. | -| \_account | address | The account address to be checked. | -| \_voteOption | enum IMajorityVoting.VoteOption | Whether the voter abstains, supports or opposes the proposal. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------------------------------------------- | -| [0] | bool | Returns true if the account is allowed to vote. | - -### canExecute - -```solidity -function canExecute(uint256 _proposalId) external view returns (bool) -``` - -Checks if a proposal can be executed. - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | ------------------------------------- | -| \_proposalId | uint256 | The ID of the proposal to be checked. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ------------------------------------------------------ | -| [0] | bool | True if the proposal can be executed, false otherwise. | - -### vote - -```solidity -function vote(uint256 _proposalId, enum IMajorityVoting.VoteOption _voteOption, bool _tryEarlyExecution) external -``` - -Votes on a proposal and, optionally, executes the proposal. - -_`_voteOption`, 1 -> abstain, 2 -> yes, 3 -> no_ - -#### Parameters - -| Name | Type | Description | -| ------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| \_proposalId | uint256 | The ID of the proposal. | -| \_voteOption | enum IMajorityVoting.VoteOption | The chosen vote option. | -| \_tryEarlyExecution | bool | If `true`, early execution is tried after the vote cast. The call does not revert if early execution is not possible. | - -### execute - -```solidity -function execute(uint256 _proposalId) external -``` - -Executes a proposal. - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | -------------------------------------- | -| \_proposalId | uint256 | The ID of the proposal to be executed. | - -### getVoteOption - -```solidity -function getVoteOption(uint256 _proposalId, address _account) external view returns (enum IMajorityVoting.VoteOption) -``` - -Returns whether the account has voted for the proposal. - -_May return `none` if the `_proposalId` does not exist, -or the `_account` does not have voting power._ - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | ---------------------------------- | -| \_proposalId | uint256 | The ID of the proposal. | -| \_account | address | The account address to be checked. | - -#### Return Values - -| Name | Type | Description | -| ---- | ------------------------------- | ------------------------------------------------------- | -| [0] | enum IMajorityVoting.VoteOption | The vote option cast by a voter for a certain proposal. | diff --git a/packages/contracts/docs/MajorityVotingBase.md b/packages/contracts/docs/MajorityVotingBase.md deleted file mode 100644 index 7187b05e..00000000 --- a/packages/contracts/docs/MajorityVotingBase.md +++ /dev/null @@ -1,953 +0,0 @@ -# Solidity API - -## MajorityVotingBase - -The abstract implementation of majority voting plugins. - -### Parameterization - -We define two parameters -$$\texttt{support} = \frac{N_\text{yes}}{N_\text{yes} + N_\text{no}} \in [0,1]$$ -and -$$\texttt{participation} = \frac{N_\text{yes} + N_\text{no} + N_\text{abstain}}{N_\text{total}} \in [0,1],$$ -where $N_\text{yes}$, $N_\text{no}$, and $N_\text{abstain}$ are the yes, no, and abstain votes that have been -cast and $N_\text{total}$ is the total voting power available at proposal creation time. - -#### Limit Values: Support Threshold & Minimum Participation - -Two limit values are associated with these parameters and decide if a proposal execution should be possible: -$\texttt{supportThreshold} \in [0,1)$ and $\texttt{minParticipation} \in [0,1]$. - -For threshold values, $>$ comparison is used. This **does not** include the threshold value. -E.g., for $\texttt{supportThreshold} = 50\%$, -the criterion is fulfilled if there is at least one more yes than no votes ($N_\text{yes} = N_\text{no} + 1$). -For minimum values, $\ge{}$ comparison is used. This **does** include the minimum participation value. -E.g., for $\texttt{minParticipation} = 40\%$ and $N_\text{total} = 10$, -the criterion is fulfilled if 4 out of 10 votes were casted. - -Majority voting implies that the support threshold is set with -$$\texttt{supportThreshold} \ge 50\% .$$ -However, this is not enforced by the contract code and developers can make unsafe parameters and -only the frontend will warn about bad parameter settings. - -### Execution Criteria - -After the vote is closed, two criteria decide if the proposal passes. - -#### The Support Criterion - -For a proposal to pass, the required ratio of yes and no votes must be met: -$$(1- \texttt{supportThreshold}) \cdot N_\text{yes} > \texttt{supportThreshold} \cdot N_\text{no}.$$ -Note, that the inequality yields the simple majority voting condition for $\texttt{supportThreshold}=\frac{1}{2}$. - -#### The Participation Criterion - -For a proposal to pass, the minimum voting power must have been cast: -$$N_\text{yes} + N_\text{no} + N_\text{abstain} \ge \texttt{minVotingPower},$$ -where $\texttt{minVotingPower} = \texttt{minParticipation} \cdot N_\text{total}$. - -### Vote Replacement - -The contract allows votes to be replaced. Voters can vote multiple times -and only the latest voteOption is tallied. - -### Early Execution - -This contract allows a proposal to be executed early, -iff the vote outcome cannot change anymore by more people voting. -Accordingly, vote replacement and early execution are mutually exclusive options. -The outcome cannot change anymore -iff the support threshold is met even if all remaining votes are no votes. -We call this number the worst-case number of no votes and define it as - -$$N_\text{no, worst-case} = N_\text{no} + \texttt{remainingVotes}$$ - -where - -$$ -\texttt{remainingVotes} = -N_\text{total}-\underbrace{(N_\text{yes}+N_\text{no}+N_\text{abstain})}_{\text{turnout}}. -$$ - -We can use this quantity to calculate the worst-case support that would be obtained -if all remaining votes are casted with no: - -$$ -\begin{align*} - \texttt{worstCaseSupport} - &= \frac{N_\text{yes}}{N_\text{yes} + (N_\text{no, worst-case})} \\[3mm] - &= \frac{N_\text{yes}}{N_\text{yes} + (N_\text{no} + \texttt{remainingVotes})} \\[3mm] - &= \frac{N_\text{yes}}{N_\text{yes} + N_\text{no} + N_\text{total} - - (N_\text{yes} + N_\text{no} + N_\text{abstain})} \\[3mm] - &= \frac{N_\text{yes}}{N_\text{total} - N_\text{abstain}} -\end{align*} -$$ - -In analogy, we can modify [the support criterion](#the-support-criterion) -from above to allow for early execution: - -$$ -\begin{align*} - (1 - \texttt{supportThreshold}) \cdot N_\text{yes} - &> \texttt{supportThreshold} \cdot N_\text{no, worst-case} \\[3mm] - &> \texttt{supportThreshold} \cdot (N_\text{no} + \texttt{remainingVotes}) \\[3mm] - &> \texttt{supportThreshold} \cdot (N_\text{no} - + N_\text{total}-(N_\text{yes}+N_\text{no}+N_\text{abstain})) \\[3mm] - &> \texttt{supportThreshold} \cdot (N_\text{total} - N_\text{yes} - N_\text{abstain}) -\end{align*} -$$ - -Accordingly, early execution is possible when the vote is open, -the modified support criterion, and the particicpation criterion are met. - -_This contract implements the `IMajorityVoting` interface._ - -### VotingMode - -```solidity -enum VotingMode { - Standard, - EarlyExecution, - VoteReplacement -} -``` - -### VotingSettings - -```solidity -struct VotingSettings { - enum MajorityVotingBase.VotingMode votingMode; - uint32 supportThreshold; - uint32 minParticipation; - uint64 minDuration; - uint256 minProposerVotingPower; -} -``` - -### Proposal - -```solidity -struct Proposal { - bool executed; - struct MajorityVotingBase.ProposalParameters parameters; - struct MajorityVotingBase.Tally tally; - mapping(address => enum IMajorityVoting.VoteOption) voters; - struct Action[] actions; - uint256 allowFailureMap; - uint256 minApprovalPower; - struct IPlugin.TargetConfig targetConfig; -} -``` - -### ProposalParameters - -```solidity -struct ProposalParameters { - enum MajorityVotingBase.VotingMode votingMode; - uint32 supportThreshold; - uint64 startDate; - uint64 endDate; - uint64 snapshotBlock; - uint256 minVotingPower; -} -``` - -### Tally - -```solidity -struct Tally { - uint256 abstain; - uint256 yes; - uint256 no; -} -``` - -### MAJORITY_VOTING_BASE_INTERFACE_ID - -```solidity -bytes4 MAJORITY_VOTING_BASE_INTERFACE_ID -``` - -The [ERC-165](https://eips.ethereum.org/EIPS/eip-165) interface ID of the contract. - -### UPDATE_VOTING_SETTINGS_PERMISSION_ID - -```solidity -bytes32 UPDATE_VOTING_SETTINGS_PERMISSION_ID -``` - -The ID of the permission required to call the `updateVotingSettings` function. - -### CREATE_PROPOSAL_PERMISSION_ID - -```solidity -bytes32 CREATE_PROPOSAL_PERMISSION_ID -``` - -The ID of the permission required to call the `createProposal` functions. - -### EXECUTE_PROPOSAL_PERMISSION_ID - -```solidity -bytes32 EXECUTE_PROPOSAL_PERMISSION_ID -``` - -The ID of the permission required to call the `execute` function. - -### proposals - -```solidity -mapping(uint256 => struct MajorityVotingBase.Proposal) proposals -``` - -A mapping between proposal IDs and proposal information. - -### DateOutOfBounds - -```solidity -error DateOutOfBounds(uint64 limit, uint64 actual) -``` - -Thrown if a date is out of bounds. - -#### Parameters - -| Name | Type | Description | -| ------ | ------ | ----------------- | -| limit | uint64 | The limit value. | -| actual | uint64 | The actual value. | - -### MinDurationOutOfBounds - -```solidity -error MinDurationOutOfBounds(uint64 limit, uint64 actual) -``` - -Thrown if the minimal duration value is out of bounds (less than one hour or greater than 1 year). - -#### Parameters - -| Name | Type | Description | -| ------ | ------ | ----------------- | -| limit | uint64 | The limit value. | -| actual | uint64 | The actual value. | - -### ProposalCreationForbidden - -```solidity -error ProposalCreationForbidden(address sender) -``` - -Thrown when a sender is not allowed to create a proposal. - -#### Parameters - -| Name | Type | Description | -| ------ | ------- | ------------------- | -| sender | address | The sender address. | - -### NonexistentProposal - -```solidity -error NonexistentProposal(uint256 proposalId) -``` - -Thrown when a proposal doesn't exist. - -#### Parameters - -| Name | Type | Description | -| ---------- | ------- | ------------------------------------------- | -| proposalId | uint256 | The ID of the proposal which doesn't exist. | - -### VoteCastForbidden - -```solidity -error VoteCastForbidden(uint256 proposalId, address account, enum IMajorityVoting.VoteOption voteOption) -``` - -Thrown if an account is not allowed to cast a vote. This can be because the vote - -- has not started, -- has ended, -- was executed, or -- the account doesn't have voting powers. - -#### Parameters - -| Name | Type | Description | -| ---------- | ------------------------------- | ----------------------------- | -| proposalId | uint256 | The ID of the proposal. | -| account | address | The address of the \_account. | -| voteOption | enum IMajorityVoting.VoteOption | The chosen vote option. | - -### ProposalExecutionForbidden - -```solidity -error ProposalExecutionForbidden(uint256 proposalId) -``` - -Thrown if the proposal execution is forbidden. - -#### Parameters - -| Name | Type | Description | -| ---------- | ------- | ----------------------- | -| proposalId | uint256 | The ID of the proposal. | - -### ProposalAlreadyExists - -```solidity -error ProposalAlreadyExists(uint256 proposalId) -``` - -Thrown if the proposal with same actions and metadata already exists. - -#### Parameters - -| Name | Type | Description | -| ---------- | ------- | ----------------------- | -| proposalId | uint256 | The id of the proposal. | - -### VotingSettingsUpdated - -```solidity -event VotingSettingsUpdated(enum MajorityVotingBase.VotingMode votingMode, uint32 supportThreshold, uint32 minParticipation, uint64 minDuration, uint256 minProposerVotingPower) -``` - -Emitted when the voting settings are updated. - -#### Parameters - -| Name | Type | Description | -| ---------------------- | ---------------------------------- | ------------------------------------------------------- | -| votingMode | enum MajorityVotingBase.VotingMode | A parameter to select the vote mode. | -| supportThreshold | uint32 | The support threshold value. | -| minParticipation | uint32 | The minimum participation value. | -| minDuration | uint64 | The minimum duration of the proposal vote in seconds. | -| minProposerVotingPower | uint256 | The minimum voting power required to create a proposal. | - -### VotingMinApprovalUpdated - -```solidity -event VotingMinApprovalUpdated(uint256 minApprovals) -``` - -Emitted when the min approval value is updated. - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | -------------------------------------------------------------- | -| minApprovals | uint256 | The minimum amount of yes votes needed for a proposal succeed. | - -### \_\_MajorityVotingBase_init - -```solidity -function __MajorityVotingBase_init(contract IDAO _dao, struct MajorityVotingBase.VotingSettings _votingSettings, struct IPlugin.TargetConfig _targetConfig, uint256 _minApprovals, bytes _pluginMetadata) internal -``` - -Initializes the component to be used by inheriting contracts. - -_This method is required to support [ERC-1822](https://eips.ethereum.org/EIPS/eip-1822)._ - -#### Parameters - -| Name | Type | Description | -| ---------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| \_dao | contract IDAO | The IDAO interface of the associated DAO. | -| \_votingSettings | struct MajorityVotingBase.VotingSettings | The voting settings. | -| \_targetConfig | struct IPlugin.TargetConfig | Configuration for the execution target, specifying the target address and operation type (either `Call` or `DelegateCall`). Defined by `TargetConfig` in the `IPlugin` interface, part of the `osx-commons-contracts` package, added in build 3. | -| \_minApprovals | uint256 | The minimal amount of approvals the proposal needs to succeed. | -| \_pluginMetadata | bytes | The plugin specific information encoded in bytes. This can also be an ipfs cid encoded in bytes. | - -### supportsInterface - -```solidity -function supportsInterface(bytes4 _interfaceId) public view virtual returns (bool) -``` - -Checks if this or the parent contract supports an interface by its ID. - -#### Parameters - -| Name | Type | Description | -| ------------- | ------ | ------------------------ | -| \_interfaceId | bytes4 | The ID of the interface. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | --------------------------------------------- | -| [0] | bool | Returns `true` if the interface is supported. | - -### vote - -```solidity -function vote(uint256 _proposalId, enum IMajorityVoting.VoteOption _voteOption, bool _tryEarlyExecution) public virtual -``` - -Votes on a proposal and, optionally, executes the proposal. - -_`_voteOption`, 1 -> abstain, 2 -> yes, 3 -> no_ - -#### Parameters - -| Name | Type | Description | -| ------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| \_proposalId | uint256 | The ID of the proposal. | -| \_voteOption | enum IMajorityVoting.VoteOption | The chosen vote option. | -| \_tryEarlyExecution | bool | If `true`, early execution is tried after the vote cast. The call does not revert if early execution is not possible. | - -### execute - -```solidity -function execute(uint256 _proposalId) public virtual -``` - -Executes a proposal. - -_Requires the `EXECUTE_PROPOSAL_PERMISSION_ID` permission._ - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | -------------------------------------- | -| \_proposalId | uint256 | The ID of the proposal to be executed. | - -### getVoteOption - -```solidity -function getVoteOption(uint256 _proposalId, address _voter) public view virtual returns (enum IMajorityVoting.VoteOption) -``` - -Returns whether the account has voted for the proposal. - -_May return `none` if the `_proposalId` does not exist, -or the `_account` does not have voting power._ - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | ----------------------- | -| \_proposalId | uint256 | The ID of the proposal. | -| \_voter | address | | - -#### Return Values - -| Name | Type | Description | -| ---- | ------------------------------- | ------------------------------------------------------- | -| [0] | enum IMajorityVoting.VoteOption | The vote option cast by a voter for a certain proposal. | - -### canVote - -```solidity -function canVote(uint256 _proposalId, address _account, enum IMajorityVoting.VoteOption _voteOption) public view virtual returns (bool) -``` - -Checks if an account can participate on a proposal. This can be because the vote - -- has not started, -- has ended, -- was executed, or -- the voter doesn't have voting powers. - -_Reverts if the proposal with the given `_proposalId` does not exist._ - -#### Parameters - -| Name | Type | Description | -| ------------ | ------------------------------- | ------------------------------------------------------------- | -| \_proposalId | uint256 | The proposal Id. | -| \_account | address | The account address to be checked. | -| \_voteOption | enum IMajorityVoting.VoteOption | Whether the voter abstains, supports or opposes the proposal. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------------------------------------------- | -| [0] | bool | Returns true if the account is allowed to vote. | - -### canExecute - -```solidity -function canExecute(uint256 _proposalId) public view virtual returns (bool) -``` - -Checks if a proposal can be executed. - -_Reverts if the proposal with the given `_proposalId` does not exist._ - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | ------------------------------------- | -| \_proposalId | uint256 | The ID of the proposal to be checked. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ------------------------------------------------------ | -| [0] | bool | True if the proposal can be executed, false otherwise. | - -### hasSucceeded - -```solidity -function hasSucceeded(uint256 _proposalId) public view virtual returns (bool) -``` - -Whether proposal succeeded or not. - -_Reverts if the proposal with the given `_proposalId` does not exist._ - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | ----------------------- | -| \_proposalId | uint256 | The id of the proposal. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------------------------------------------------------------------------------- | -| [0] | bool | Returns if proposal has been succeeded or not without including time window checks. | - -### isSupportThresholdReached - -```solidity -function isSupportThresholdReached(uint256 _proposalId) public view virtual returns (bool) -``` - -Checks if the support value defined as: -$$\texttt{support} = \frac{N_\text{yes}}{N_\text{yes}+N_\text{no}}$$ -for a proposal is greater than the support threshold. - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | ----------------------- | -| \_proposalId | uint256 | The ID of the proposal. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ------------------------------------------------------------------------------------------ | -| [0] | bool | Returns `true` if the support is greater than the support threshold and `false` otherwise. | - -### isSupportThresholdReachedEarly - -```solidity -function isSupportThresholdReachedEarly(uint256 _proposalId) public view virtual returns (bool) -``` - -Checks if the worst-case support value defined as: -$$\texttt{worstCaseSupport} = \frac{N_\text{yes}}{ N_\text{total}-N_\text{abstain}}$$ -for a proposal is greater than the support threshold. - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | ----------------------- | -| \_proposalId | uint256 | The ID of the proposal. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------------------------------------------------------------------------------------------------- | -| [0] | bool | Returns `true` if the worst-case support is greater than the support threshold and `false` otherwise. | - -### isMinParticipationReached - -```solidity -function isMinParticipationReached(uint256 _proposalId) public view virtual returns (bool) -``` - -Checks if the participation value defined as: -$$\texttt{participation} = \frac{N_\text{yes}+N_\text{no}+N_\text{abstain}}{N_\text{total}}$$ -for a proposal is greater or equal than the minimum participation value. - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | ----------------------- | -| \_proposalId | uint256 | The ID of the proposal. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | -------------------------------------------------------------------------------------------------------------- | -| [0] | bool | Returns `true` if the participation is greater or equal than the minimum participation, and `false` otherwise. | - -### isMinApprovalReached - -```solidity -function isMinApprovalReached(uint256 _proposalId) public view virtual returns (bool) -``` - -Checks if the min approval value defined as: -$$\texttt{minApproval} = \frac{N_\text{yes}}{N_\text{total}}$$ -for a proposal is greater or equal than the minimum approval value. - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | ----------------------- | -| \_proposalId | uint256 | The ID of the proposal. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ---------------------------------------------------------------------------------------------------- | -| [0] | bool | Returns `true` if the approvals is greater or equal than the minimum approval and `false` otherwise. | - -### minApproval - -```solidity -function minApproval() public view virtual returns (uint256) -``` - -Returns the configured minimum approval value. - -#### Return Values - -| Name | Type | Description | -| ---- | ------- | --------------------------- | -| [0] | uint256 | The minimal approval value. | - -### supportThreshold - -```solidity -function supportThreshold() public view virtual returns (uint32) -``` - -Returns the support threshold parameter stored in the voting settings. - -#### Return Values - -| Name | Type | Description | -| ---- | ------ | -------------------------------- | -| [0] | uint32 | The support threshold parameter. | - -### minParticipation - -```solidity -function minParticipation() public view virtual returns (uint32) -``` - -Returns the minimum participation parameter stored in the voting settings. - -#### Return Values - -| Name | Type | Description | -| ---- | ------ | ------------------------------------ | -| [0] | uint32 | The minimum participation parameter. | - -### minDuration - -```solidity -function minDuration() public view virtual returns (uint64) -``` - -Returns the minimum duration parameter stored in the voting settings. - -#### Return Values - -| Name | Type | Description | -| ---- | ------ | ------------------------------- | -| [0] | uint64 | The minimum duration parameter. | - -### minProposerVotingPower - -```solidity -function minProposerVotingPower() public view virtual returns (uint256) -``` - -Returns the minimum voting power required to create a proposal stored in the voting settings. - -#### Return Values - -| Name | Type | Description | -| ---- | ------- | ------------------------------------------------------- | -| [0] | uint256 | The minimum voting power required to create a proposal. | - -### votingMode - -```solidity -function votingMode() public view virtual returns (enum MajorityVotingBase.VotingMode) -``` - -Returns the vote mode stored in the voting settings. - -#### Return Values - -| Name | Type | Description | -| ---- | ---------------------------------- | ------------------------ | -| [0] | enum MajorityVotingBase.VotingMode | The vote mode parameter. | - -### totalVotingPower - -```solidity -function totalVotingPower(uint256 _blockNumber) public view virtual returns (uint256) -``` - -Returns the total voting power checkpointed for a specific block number. - -#### Parameters - -| Name | Type | Description | -| ------------- | ------- | ----------------- | -| \_blockNumber | uint256 | The block number. | - -#### Return Values - -| Name | Type | Description | -| ---- | ------- | ----------------------- | -| [0] | uint256 | The total voting power. | - -### getProposal - -```solidity -function getProposal(uint256 _proposalId) public view virtual returns (bool open, bool executed, struct MajorityVotingBase.ProposalParameters parameters, struct MajorityVotingBase.Tally tally, struct Action[] actions, uint256 allowFailureMap) -``` - -Returns all information for a proposal by its ID. - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | ----------------------- | -| \_proposalId | uint256 | The ID of the proposal. | - -#### Return Values - -| Name | Type | Description | -| --------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------- | -| open | bool | Whether the proposal is open or not. | -| executed | bool | Whether the proposal is executed or not. | -| parameters | struct MajorityVotingBase.ProposalParameters | The parameters of the proposal. | -| tally | struct MajorityVotingBase.Tally | The current tally of the proposal. | -| actions | struct Action[] | The actions to be executed in the associated DAO after the proposal has passed. | -| allowFailureMap | uint256 | The bit map representations of which actions are allowed to revert so tx still succeeds. | - -### updateVotingSettings - -```solidity -function updateVotingSettings(struct MajorityVotingBase.VotingSettings _votingSettings) external virtual -``` - -Updates the voting settings. - -_Requires the `UPDATE_VOTING_SETTINGS_PERMISSION_ID` permission._ - -#### Parameters - -| Name | Type | Description | -| ---------------- | ---------------------------------------- | ------------------------ | -| \_votingSettings | struct MajorityVotingBase.VotingSettings | The new voting settings. | - -### updateMinApprovals - -```solidity -function updateMinApprovals(uint256 _minApprovals) external virtual -``` - -Updates the minimal approval value. - -_Requires the `UPDATE_VOTING_SETTINGS_PERMISSION_ID` permission._ - -#### Parameters - -| Name | Type | Description | -| -------------- | ------- | ------------------------------- | -| \_minApprovals | uint256 | The new minimal approval value. | - -### createProposal - -```solidity -function createProposal(bytes _metadata, struct Action[] _actions, uint256 _allowFailureMap, uint64 _startDate, uint64 _endDate, enum IMajorityVoting.VoteOption _voteOption, bool _tryEarlyExecution) external virtual returns (uint256 proposalId) -``` - -Creates a new majority voting proposal. - -#### Parameters - -| Name | Type | Description | -| ------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| \_metadata | bytes | The metadata of the proposal. | -| \_actions | struct Action[] | The actions that will be executed after the proposal passes. | -| \_allowFailureMap | uint256 | Allows proposal to succeed even if an action reverts. Uses bitmap representation. If the bit at index `x` is 1, the tx succeeds even if the action at `x` failed. Passing 0 will be treated as atomic execution. | -| \_startDate | uint64 | The start date of the proposal vote. If 0, the current timestamp is used and the vote starts immediately. | -| \_endDate | uint64 | The end date of the proposal vote. If 0, `_startDate + minDuration` is used. | -| \_voteOption | enum IMajorityVoting.VoteOption | The chosen vote option to be casted on proposal creation. | -| \_tryEarlyExecution | bool | If `true`, early execution is tried after the vote cast. The call does not revert if early execution is not possible. | - -#### Return Values - -| Name | Type | Description | -| ---------- | ------- | ----------------------- | -| proposalId | uint256 | The ID of the proposal. | - -### \_vote - -```solidity -function _vote(uint256 _proposalId, enum IMajorityVoting.VoteOption _voteOption, address _voter, bool _tryEarlyExecution) internal virtual -``` - -Internal function to cast a vote. It assumes the queried proposal exists. - -#### Parameters - -| Name | Type | Description | -| ------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| \_proposalId | uint256 | The ID of the proposal. | -| \_voteOption | enum IMajorityVoting.VoteOption | The chosen vote option to be casted on the proposal vote. | -| \_voter | address | The address of the account that is voting on the `_proposalId`. | -| \_tryEarlyExecution | bool | If `true`, early execution is tried after the vote cast. The call does not revert if early execution is not possible. | - -### \_execute - -```solidity -function _execute(uint256 _proposalId) internal virtual -``` - -Internal function to execute a proposal. It assumes the queried proposal exists. - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | ----------------------- | -| \_proposalId | uint256 | The ID of the proposal. | - -### \_canVote - -```solidity -function _canVote(uint256 _proposalId, address _account, enum IMajorityVoting.VoteOption _voteOption) internal view virtual returns (bool) -``` - -Internal function to check if a voter can vote. It assumes the queried proposal exists. - -#### Parameters - -| Name | Type | Description | -| ------------ | ------------------------------- | ------------------------------------------------------------- | -| \_proposalId | uint256 | The ID of the proposal. | -| \_account | address | The address of the voter to check. | -| \_voteOption | enum IMajorityVoting.VoteOption | Whether the voter abstains, supports or opposes the proposal. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | --------------------------------------------------------------------------------------- | -| [0] | bool | Returns `true` if the given voter can vote on a certain proposal and `false` otherwise. | - -### \_hasSucceeded - -```solidity -function _hasSucceeded(uint256 _proposalId) internal view virtual returns (bool) -``` - -An internal function that checks if the proposal succeeded or not. - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | ----------------------- | -| \_proposalId | uint256 | The ID of the proposal. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | -------------------------------------------------------------------------------------- | -| [0] | bool | Returns `true` if the proposal succeeded depending on the thresholds and voting modes. | - -### \_canExecute - -```solidity -function _canExecute(uint256 _proposalId) internal view virtual returns (bool) -``` - -Internal function to check if a proposal can be executed. It assumes the queried proposal exists. - -_Threshold and minimal values are compared with `>` and `>=` comparators, respectively._ - -#### Parameters - -| Name | Type | Description | -| ------------ | ------- | ----------------------- | -| \_proposalId | uint256 | The ID of the proposal. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ------------------------------------------------------ | -| [0] | bool | True if the proposal can be executed, false otherwise. | - -### \_isProposalOpen - -```solidity -function _isProposalOpen(struct MajorityVotingBase.Proposal proposal_) internal view virtual returns (bool) -``` - -Internal function to check if a proposal is still open. - -#### Parameters - -| Name | Type | Description | -| ---------- | ---------------------------------- | -------------------- | -| proposal\_ | struct MajorityVotingBase.Proposal | The proposal struct. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ---------------------------------------------- | -| [0] | bool | True if the proposal is open, false otherwise. | - -### \_updateVotingSettings - -```solidity -function _updateVotingSettings(struct MajorityVotingBase.VotingSettings _votingSettings) internal virtual -``` - -Internal function to update the plugin-wide proposal settings. - -#### Parameters - -| Name | Type | Description | -| ---------------- | ---------------------------------------- | ------------------------------------------------ | -| \_votingSettings | struct MajorityVotingBase.VotingSettings | The voting settings to be validated and updated. | - -### \_updateMinApprovals - -```solidity -function _updateMinApprovals(uint256 _minApprovals) internal virtual -``` - -Internal function to update minimal approval value. - -#### Parameters - -| Name | Type | Description | -| -------------- | ------- | ------------------------------- | -| \_minApprovals | uint256 | The new minimal approval value. | - -### \_validateProposalDates - -```solidity -function _validateProposalDates(uint64 _start, uint64 _end) internal view virtual returns (uint64 startDate, uint64 endDate) -``` - -Validates and returns the proposal dates. - -#### Parameters - -| Name | Type | Description | -| ------- | ------ | ---------------------------------------------------------------------------------------------------- | -| \_start | uint64 | The start date of the proposal. If 0, the current timestamp is used and the vote starts immediately. | -| \_end | uint64 | The end date of the proposal. If 0, `_start + minDuration` is used. | - -#### Return Values - -| Name | Type | Description | -| --------- | ------ | ----------------------------------------- | -| startDate | uint64 | The validated start date of the proposal. | -| endDate | uint64 | The validated end date of the proposal. | diff --git a/packages/contracts/docs/TokenVoting.md b/packages/contracts/docs/TokenVoting.md deleted file mode 100644 index 9279ff49..00000000 --- a/packages/contracts/docs/TokenVoting.md +++ /dev/null @@ -1,253 +0,0 @@ -# Solidity API - -## TokenVoting - -The majority voting implementation using an -[OpenZeppelin `Votes`](https://docs.openzeppelin.com/contracts/4.x/api/governance#Votes) -compatible governance token. - -_v1.3 (Release 1, Build 3). For each upgrade, if the reinitialization step is required, -increment the version numbers in the modifier for both the initialize and initializeFrom functions._ - -### TOKEN_VOTING_INTERFACE_ID - -```solidity -bytes4 TOKEN_VOTING_INTERFACE_ID -``` - -The [ERC-165](https://eips.ethereum.org/EIPS/eip-165) interface ID of the contract. - -### NoVotingPower - -```solidity -error NoVotingPower() -``` - -Thrown if the voting power is zero - -### initialize - -```solidity -function initialize(contract IDAO _dao, struct MajorityVotingBase.VotingSettings _votingSettings, contract IVotesUpgradeable _token, struct IPlugin.TargetConfig _targetConfig, uint256 _minApprovals, bytes _pluginMetadata) external -``` - -Initializes the component. - -_This method is required to support [ERC-1822](https://eips.ethereum.org/EIPS/eip-1822)._ - -#### Parameters - -| Name | Type | Description | -| ---------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| \_dao | contract IDAO | The IDAO interface of the associated DAO. | -| \_votingSettings | struct MajorityVotingBase.VotingSettings | The voting settings. | -| \_token | contract IVotesUpgradeable | The [ERC-20](https://eips.ethereum.org/EIPS/eip-20) token used for voting. | -| \_targetConfig | struct IPlugin.TargetConfig | Configuration for the execution target, specifying the target address and operation type (either `Call` or `DelegateCall`). Defined by `TargetConfig` in the `IPlugin` interface, part of the `osx-commons-contracts` package, added in build 3. | -| \_minApprovals | uint256 | The minimal amount of approvals the proposal needs to succeed. | -| \_pluginMetadata | bytes | The plugin specific information encoded in bytes. This can also be an ipfs cid encoded in bytes. | - -### initializeFrom - -```solidity -function initializeFrom(uint16 _fromBuild, bytes _initData) external -``` - -Reinitializes the TokenVoting after an upgrade from a previous build version. For each -reinitialization step, use the `_fromBuild` version to decide which internal functions to -call for reinitialization. - -_WARNING: The contract should only be upgradeable through PSP to ensure that \_fromBuild is not -incorrectly passed, and that the appropriate permissions for the upgrade are properly configured._ - -#### Parameters - -| Name | Type | Description | -| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| \_fromBuild | uint16 | Build version number of previous implementation contract this upgrade is transitioning from. | -| \_initData | bytes | The initialization data to be passed to via `upgradeToAndCall` (see [ERC-1967](https://docs.openzeppelin.com/contracts/4.x/api/proxy#ERC1967Upgrade)). | - -### supportsInterface - -```solidity -function supportsInterface(bytes4 _interfaceId) public view virtual returns (bool) -``` - -Checks if this or the parent contract supports an interface by its ID. - -#### Parameters - -| Name | Type | Description | -| ------------- | ------ | ------------------------ | -| \_interfaceId | bytes4 | The ID of the interface. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | --------------------------------------------- | -| [0] | bool | Returns `true` if the interface is supported. | - -### getVotingToken - -```solidity -function getVotingToken() public view returns (contract IVotesUpgradeable) -``` - -getter function for the voting token. - -_public function also useful for registering interfaceId -and for distinguishing from majority voting interface._ - -#### Return Values - -| Name | Type | Description | -| ---- | -------------------------- | -------------------------- | -| [0] | contract IVotesUpgradeable | The token used for voting. | - -### totalVotingPower - -```solidity -function totalVotingPower(uint256 _blockNumber) public view returns (uint256) -``` - -Returns the total voting power checkpointed for a specific block number. - -#### Parameters - -| Name | Type | Description | -| ------------- | ------- | ----------------- | -| \_blockNumber | uint256 | The block number. | - -#### Return Values - -| Name | Type | Description | -| ---- | ------- | ----------------------- | -| [0] | uint256 | The total voting power. | - -### createProposal - -```solidity -function createProposal(bytes _metadata, struct Action[] _actions, uint256 _allowFailureMap, uint64 _startDate, uint64 _endDate, enum IMajorityVoting.VoteOption _voteOption, bool _tryEarlyExecution) public returns (uint256 proposalId) -``` - -Creates a new majority voting proposal. - -_Requires the `CREATE_PROPOSAL_PERMISSION_ID` permission._ - -#### Parameters - -| Name | Type | Description | -| ------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| \_metadata | bytes | The metadata of the proposal. | -| \_actions | struct Action[] | The actions that will be executed after the proposal passes. | -| \_allowFailureMap | uint256 | Allows proposal to succeed even if an action reverts. Uses bitmap representation. If the bit at index `x` is 1, the tx succeeds even if the action at `x` failed. Passing 0 will be treated as atomic execution. | -| \_startDate | uint64 | The start date of the proposal vote. If 0, the current timestamp is used and the vote starts immediately. | -| \_endDate | uint64 | The end date of the proposal vote. If 0, `_startDate + minDuration` is used. | -| \_voteOption | enum IMajorityVoting.VoteOption | The chosen vote option to be casted on proposal creation. | -| \_tryEarlyExecution | bool | If `true`, early execution is tried after the vote cast. The call does not revert if early execution is not possible. | - -#### Return Values - -| Name | Type | Description | -| ---------- | ------- | ----------------------- | -| proposalId | uint256 | The ID of the proposal. | - -### createProposal - -```solidity -function createProposal(bytes _metadata, struct Action[] _actions, uint64 _startDate, uint64 _endDate, bytes _data) external returns (uint256 proposalId) -``` - -Creates a new proposal. - -#### Parameters - -| Name | Type | Description | -| ----------- | --------------- | ----------------------------------------------------------------- | -| \_metadata | bytes | The metadata of the proposal. | -| \_actions | struct Action[] | The actions that will be executed after the proposal passes. | -| \_startDate | uint64 | The start date of the proposal. | -| \_endDate | uint64 | The end date of the proposal. | -| \_data | bytes | The additional abi-encoded data to include more necessary fields. | - -#### Return Values - -| Name | Type | Description | -| ---------- | ------- | ----------------------- | -| proposalId | uint256 | The id of the proposal. | - -### customProposalParamsABI - -```solidity -function customProposalParamsABI() external pure returns (string) -``` - -The human-readable abi format for extra params included in `data` of `createProposal`. - -_Used for UI to easily detect what extra params the contract expects._ - -#### Return Values - -| Name | Type | Description | -| ---- | ------ | -------------------------------------------- | -| [0] | string | ABI of params in `data` of `createProposal`. | - -### isMember - -```solidity -function isMember(address _account) external view returns (bool) -``` - -Checks if an account is a member of the DAO. - -_This function must be implemented in the plugin contract that introduces the members to the DAO._ - -#### Parameters - -| Name | Type | Description | -| --------- | ------- | ----------------------------------------- | -| \_account | address | The address of the account to be checked. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | --------------------------------------- | -| [0] | bool | Whether the account is a member or not. | - -### \_vote - -```solidity -function _vote(uint256 _proposalId, enum IMajorityVoting.VoteOption _voteOption, address _voter, bool _tryEarlyExecution) internal -``` - -Internal function to cast a vote. It assumes the queried proposal exists. - -#### Parameters - -| Name | Type | Description | -| ------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| \_proposalId | uint256 | The ID of the proposal. | -| \_voteOption | enum IMajorityVoting.VoteOption | The chosen vote option to be casted on the proposal vote. | -| \_voter | address | The address of the account that is voting on the `_proposalId`. | -| \_tryEarlyExecution | bool | If `true`, early execution is tried after the vote cast. The call does not revert if early execution is not possible. | - -### \_canVote - -```solidity -function _canVote(uint256 _proposalId, address _account, enum IMajorityVoting.VoteOption _voteOption) internal view returns (bool) -``` - -Internal function to check if a voter can vote. It assumes the queried proposal exists. - -#### Parameters - -| Name | Type | Description | -| ------------ | ------------------------------- | ------------------------------------------------------------- | -| \_proposalId | uint256 | The ID of the proposal. | -| \_account | address | The address of the voter to check. | -| \_voteOption | enum IMajorityVoting.VoteOption | Whether the voter abstains, supports or opposes the proposal. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | --------------------------------------------------------------------------------------- | -| [0] | bool | Returns `true` if the given voter can vote on a certain proposal and `false` otherwise. | diff --git a/packages/contracts/docs/TokenVotingSetup.md b/packages/contracts/docs/TokenVotingSetup.md deleted file mode 100644 index da40b5b9..00000000 --- a/packages/contracts/docs/TokenVotingSetup.md +++ /dev/null @@ -1,155 +0,0 @@ -# Solidity API - -## TokenVotingSetup - -The setup contract of the `TokenVoting` plugin. - -_v1.3 (Release 1, Build 3)_ - -### governanceERC20Base - -```solidity -address governanceERC20Base -``` - -The address of the `GovernanceERC20` base contract. - -### governanceWrappedERC20Base - -```solidity -address governanceWrappedERC20Base -``` - -The address of the `GovernanceWrappedERC20` base contract. - -### TokenSettings - -```solidity -struct TokenSettings { - address addr; - string name; - string symbol; -} -``` - -### TokenNotContract - -```solidity -error TokenNotContract(address token) -``` - -Thrown if the passed token address is not a token contract. - -#### Parameters - -| Name | Type | Description | -| ----- | ------- | ----------------- | -| token | address | The token address | - -### TokenNotERC20 - -```solidity -error TokenNotERC20(address token) -``` - -Thrown if token address is not ERC20. - -#### Parameters - -| Name | Type | Description | -| ----- | ------- | ----------------- | -| token | address | The token address | - -### constructor - -```solidity -constructor(contract GovernanceERC20 _governanceERC20Base, contract GovernanceWrappedERC20 _governanceWrappedERC20Base) public -``` - -The contract constructor deploying the plugin implementation contract -and receiving the governance token base contracts to clone from. - -#### Parameters - -| Name | Type | Description | -| ---------------------------- | ------------------------------- | ----------------------------------------------------------------- | -| \_governanceERC20Base | contract GovernanceERC20 | The base `GovernanceERC20` contract to create clones from. | -| \_governanceWrappedERC20Base | contract GovernanceWrappedERC20 | The base `GovernanceWrappedERC20` contract to create clones from. | - -### prepareInstallation - -```solidity -function prepareInstallation(address _dao, bytes _data) external returns (address plugin, struct IPluginSetup.PreparedSetupData preparedSetupData) -``` - -Prepares the installation of a plugin. - -#### Parameters - -| Name | Type | Description | -| ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| \_dao | address | The address of the installing DAO. | -| \_data | bytes | The bytes-encoded data containing the input parameters for the installation as specified in the plugin's build metadata JSON file. | - -#### Return Values - -| Name | Type | Description | -| ----------------- | ------------------------------------- | ------------------------------------------------------------------------------ | -| plugin | address | The address of the `Plugin` contract being prepared for installation. | -| preparedSetupData | struct IPluginSetup.PreparedSetupData | The deployed plugin's relevant data which consists of helpers and permissions. | - -### prepareUpdate - -```solidity -function prepareUpdate(address _dao, uint16 _fromBuild, struct IPluginSetup.SetupPayload _payload) external returns (bytes initData, struct IPluginSetup.PreparedSetupData preparedSetupData) -``` - -Prepares the update of a plugin. - -_Revoke the upgrade plugin permission to the DAO for all builds prior the current one (3)._ - -#### Parameters - -| Name | Type | Description | -| ----------- | -------------------------------- | --------------------------------------------------------------- | -| \_dao | address | The address of the updating DAO. | -| \_fromBuild | uint16 | The build number of the plugin to update from. | -| \_payload | struct IPluginSetup.SetupPayload | The relevant data necessary for the `prepareUpdate`. See above. | - -#### Return Values - -| Name | Type | Description | -| ----------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -| initData | bytes | The initialization data to be passed to upgradeable contracts when the update is applied in the `PluginSetupProcessor`. | -| preparedSetupData | struct IPluginSetup.PreparedSetupData | The deployed plugin's relevant data which consists of helpers and permissions. | - -### prepareUninstallation - -```solidity -function prepareUninstallation(address _dao, struct IPluginSetup.SetupPayload _payload) external view returns (struct PermissionLib.MultiTargetPermission[] permissions) -``` - -Prepares the uninstallation of a plugin. - -#### Parameters - -| Name | Type | Description | -| --------- | -------------------------------- | ----------------------------------------------------------------------- | -| \_dao | address | The address of the uninstalling DAO. | -| \_payload | struct IPluginSetup.SetupPayload | The relevant data necessary for the `prepareUninstallation`. See above. | - -#### Return Values - -| Name | Type | Description | -| ----------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -| permissions | struct PermissionLib.MultiTargetPermission[] | The array of multi-targeted permission operations to be applied by the `PluginSetupProcessor` to the uninstalling DAO. | - -### supportsIVotesInterface - -```solidity -function supportsIVotesInterface(address token) public view returns (bool) -``` - -Unsatisfiably determines if the token is an IVotes interface. - -_Many tokens don't use ERC165 even though they still support IVotes._ diff --git a/packages/contracts/docs/VotingPowerCondition.md b/packages/contracts/docs/VotingPowerCondition.md deleted file mode 100644 index 679d863b..00000000 --- a/packages/contracts/docs/VotingPowerCondition.md +++ /dev/null @@ -1,46 +0,0 @@ -# Solidity API - -## VotingPowerCondition - -Checks if an account's voting power or token balance meets the threshold set -in an associated TokenVoting plugin. - -### constructor - -```solidity -constructor(address _tokenVoting) public -``` - -Initializes the contract with the `TokenVoting` plugin address and fetches the associated token. - -#### Parameters - -| Name | Type | Description | -| ------------- | ------- | ---------------------------------------- | -| \_tokenVoting | address | The address of the `TokenVoting` plugin. | - -### isGranted - -```solidity -function isGranted(address _where, address _who, bytes32 _permissionId, bytes _data) public view returns (bool) -``` - -Checks if a call is permitted. - -_The function checks both the voting power and token balance to ensure `_who` meets the minimum voting -threshold defined in the `TokenVoting` plugin. Returns `false` if the minimum requirement is unmet._ - -#### Parameters - -| Name | Type | Description | -| -------------- | ------- | -------------------------------------------------------------------- | -| \_where | address | The address of the target contract. | -| \_who | address | The address (EOA or contract) for which the permissions are checked. | -| \_permissionId | bytes32 | The permission identifier. | -| \_data | bytes | Optional data passed to the `PermissionCondition` implementation. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bool | | diff --git a/packages/contracts/docs/templates/helpers.js b/packages/contracts/docs/templates/helpers.js index 973c5762..f4969300 100644 --- a/packages/contracts/docs/templates/helpers.js +++ b/packages/contracts/docs/templates/helpers.js @@ -29,14 +29,6 @@ module.exports['getExternalLink'] = absolutePath => { return 'github.com'; }; -// module.exports['isAragonInherittedContract1'] = contract => { -// console.log(contract, 'oe'); -// }; - -// module.exports['getExternalLink1'] = item => { -// // console.log(item, 'oe'); -// }; - module.exports.names = params => params?.map(p => p.name).join(', '); module.exports['typed-params'] = params => { diff --git a/packages/contracts/docs/templates/properties.js b/packages/contracts/docs/templates/properties.js index 4d0d770f..a086d26f 100644 --- a/packages/contracts/docs/templates/properties.js +++ b/packages/contracts/docs/templates/properties.js @@ -24,12 +24,6 @@ module.exports.inheritance = function ({item, build}) { throw new Error('used inherited-items on non-contract'); } - // console.log( - // item.linearizedBaseContracts - // .map(id => build.deref('ContractDefinition', id)) - // .filter((c, i) => c.name !== 'Context' || i === 0), - // ' awesome' - // ); return item.linearizedBaseContracts .map(id => build.deref('ContractDefinition', id)) .filter((c, i) => c.name !== 'Context' || i === 0); @@ -87,13 +81,5 @@ module.exports['inherited-functions'] = function ({item}) { ), })); - // d.map(item => { - // // console.log(item.contract.name); - // // console.log('starts'); - // item.functions.map(item2 => { - // console.log(item2); - // }); - // console.log('ends'); - // }); return d; }; diff --git a/packages/contracts/scripts/prepare-docs.sh b/packages/contracts/scripts/prepare-docs.sh index b5e55bd4..ada79608 100755 --- a/packages/contracts/scripts/prepare-docs.sh +++ b/packages/contracts/scripts/prepare-docs.sh @@ -13,16 +13,6 @@ rm -rf "$OUTDIR" hardhat docgen -# copy examples and adjust imports -# examples_source_dir="contracts/mocks/docs" -# examples_target_dir="docs/modules/api/examples" - -# for f in "$examples_source_dir"/**/*.sol; do -# name="${f/#"$examples_source_dir/"/}" -# mkdir -p "$examples_target_dir/$(dirname "$name")" -# sed -Ee '/^import/s|"(\.\./)+|"@openzeppelin/contracts/|' "$f" > "$examples_target_dir/$name" -# done - echo $OUTDIR node scripts/gen-nav.js "$OUTDIR" > "$OUTDIR/../nav.adoc" \ No newline at end of file