In the realm of SPL Governance, proposals play a pivotal role in the decision-making process within a Decentralised Autonomous Organisation (DAO). They serve as formal submissions that undergo a voting procedure, enabling DAO members to express their support or opposition to the proposed action. This chapter delves into the intricacies of proposals, including their structure, lifecycle, and the power they hold in shaping the governance landscape.
The Nature of Proposals
A proposal is essentially a submission represented by a poll, where voters express their pro or con attitudes. It serves as a means for DAO members to present ideas, suggestions, or changes they believe should be implemented within the organisation. Proposals can encompass a wide range of actions, from simple administrative tasks to substantial governance decisions.
Voting and Success
The fate of a proposal lies in the hands of the DAO's voting members. When a poll successfully passes, meaning it garners enough votes in favour, the proposal is considered successful. If the proposal contains a transaction, it can be executed to finalise the resolution of the voting process. This mechanism ensures that the decisions made by the DAO reflect the will of its community or council.
Thresholds and Configuration
The resolution of voting is influenced by the number of votes gained, but it is also subject to predefined thresholds of success. These thresholds are determined by the creator of the voting and are configurable within the governance framework. These parameters play a crucial role in determining the level of support required for a proposal to be considered successful.
Governance and Proposal Relationship
Every proposal belongs to a specific governance, which acts as the overarching framework for managing and governing the DAO. The governance structure sets the rules and guidelines for proposal creation, voting, and execution. It ensures that proposals align with the DAO's mission, vision, and community values.
Voter Tokens and Power
In SPL Governance, a voter is represented by a wallet that contains tokens. These tokens serve as identifiers of the voting power held by the individual. The number of tokens in a voter's wallet determines their influence and weight in the voting process. This mechanism ensures that voting decisions are reflective of the stake each member holds within the DAO.
Proposal Structure and Hierarchy
Within the account structure hierarchy, the proposal occupies a significant position. It is the final component of this hierarchy, encapsulating all the necessary information related to the proposal. Each proposal (code) is created within a specific governance and is bound to a single mint, known as the governing_token_mint. This mint defines the population, whether it is the council or the community, that has the right to vote on the proposal.
Options and Instructions
A proposal consists of several options, each labeled with a string that represents a distinct choice or course of action. These options provide the voting population with alternatives to choose from during the voting process. Additionally, instructions can be optionally defined for specific options within a proposal. These instructions outline the actions to be executed if a particular option successfully passes the voting stage, allowing for automated and precise execution of decisions made by the DAO.
Lifecycle States
After creation, a proposal goes through a defined lifecycle consisting of several states (code). Each state designates the permitted operations and actions that can be taken regarding the proposal. For example, at a certain state, the proposal can be canceled, voted for, or have its transaction executed. These lifecycle states ensure that the proposal progresses through the necessary stages, providing clarity and control over the decision-making process.
A proposal goes through lifecycle defined by several states: Draft State, Voting State and Execution State. Let's have a look at them in more details.
Draft State and Options
A new proposal is initially created in the Draft state. In this state, the proposal is still being formulated and refined. A proposal consists of a set of options, each identified by a string label and an index in the array where it is stored. These options represent the different choices available for voting.
Adding Signatories
While a proposal is in the Draft state, the creator has the ability to add multiple signatories to the proposal using the AddSignatory instruction. Signatories are individuals who have the authority to endorse and confirm the readiness of the proposal for voting. This feature ensures that the proposal remains in the Draft state until all defined signatories have confirmed its readiness.
Moving to Voting State
The proposal transitions to the Voting state only when all signatories, including the creator, have signed the proposal. This means that all designated individuals must endorse and confirm that the proposal is prepared to be voted on. The proposal remains in the Draft or SigningOff state until all signatories have signed. Once all signatories have signed, the proposal moves directly to the Voting state upon the execution of the SignOffProposal instruction.
Inserting Transactions and Instructions
While the proposal is in the Voting state, additional instructions can be added to the proposal by calling the InsertTransaction instruction. This allows for the binding of specific instructions to an option within the proposal. The option is identified by its index within the array structure. Multiple instructions can be added to the same option, and these instructions can be grouped into an array that will be executed atomically.
Execution of Instructions
The inserted list of instructions added to the proposal are stored in a transaction account (code). When the proposal reaches the execution phase, the ProcessExecuteTransaction (code) takes the transaction account as input and executes the instructions stored within it. The address of the transaction account is calculated using the proposal's public key, the index of the option, and the index of the instruction (code). This process ensures the accurate and secure execution of the instructions associated with the proposal.
Upon creating a proposal, a certain amount of SOL (Solana's native cryptocurrency)(code) is deposited into the custody of the Governance system. The deposited amount is designed to prevent spamming the system with frivolous or unnecessary proposals. The deposit amount increases based on the number of currently active proposals, creating a deterrent for submitting proposals that are unlikely to be voted on. However, this maintenance operation is typically handled automatically by the user interface (UI), ensuring an efficient user experience and can be refunded (code).
Once a proposal has been signed off by all designated signatories and all transactions are in place, it transitions to the Voting state, where it becomes ready to receive votes from the designated voting population, be it the council or the community. This chapter explores the process of voting, the duration of the voting period, the ability to change votes, and the finalisation of the voting results. Additionally, it covers the veto voting workflow and the possibility of canceling a proposal during the Draft or Voting state.
Voting Process and Options
In the Voting state, the proposal is open for voting by the designated voting population. Voters can choose to either cast positive votes in favour of the proposal or negative votes to deny and veto it. The CastVote instruction is used to participate in the voting process.
Voting Duration and Cooling-off Period
The duration of the voting period is defined by the governance attribute voting_base_time. Additionally, a voting_cool_off_time can be set up to prolong the voting period. During the voting_cool_off_time, voters are only allowed to cast negative votes (deny and vetoes) or relinquish their votes. The voting period can be completed before its designated duration if vote tipping is enabled.
Changing Votes
Voters have the flexibility to change their votes if they change their minds. To cast a new vote, the voter must first call the RelinquishVote instruction, which removes voting power from the previous option. Afterward, the voter can cast a new vote.
Finalising Voting Results
When the voting period elapses and the proposal has not been tipped to finish sooner, the FinalizeVote instruction is called. This instruction considers the number of yes votes and deny votes across all options of the proposal, as well as the type of the proposal (code), and determines whether it has succeeded or been defeated. The proposal is then moved to the appropriate state accordingly.
Veto Voting Workflow
For veto votes, the workflow differs slightly. If the veto threshold is met, the proposal is moved to the final Vetoed state. The veto threshold is checked with every CastVote call, regardless of whether vote tipping is enabled or not.
Canceling a Proposal
During the Draft state or the Voting state, the proposal may be canceled. Only the owner of the proposal, referred to as the token owner record account, is permitted to call the CancelProposal instruction. The token owner record account is an account associated with the proposal and was inserted into the proposal account during its creation.
Once a proposal reaches the Succeeded state, the instructions associated with the proposal's options can be executed. It's important to note that each option within the proposal has its own final state. Only options marked as Succeeded are eligible for executing the attached instructions using the ExecuteTransaction instruction.
The governance system allows for the configuration of min_transaction_hold_up_time. This attribute adds a specified duration of time after proposal finalisation before the instruction can begin execution. The purpose of this delay is to ensure that sufficient time has passed for any necessary preparations or validations before the instruction can be safely executed.
Upon successful execution of all instructions, the proposal transitions to the final Completed state, indicating that all the proposed actions have been carried out as intended.
However, there is a possibility that the instructions from the proposal may fail to execute. This can occur due to various reasons, such as incorrectly composed instructions (e.g., providing incorrect accounts or parameters) or changes in the blockchain's state since the proposal's creation, rendering the constraints for instruction execution unmet. In such cases, the proposal can be marked as ExecutingWithErrors by invoking the appropriate instruction, which can only be called by the proposal creator. This state indicates that the execution encountered errors or complications and could not be completed successfully.
Within SPL Governance, there exists a unique category of proposals known as survey-type proposals. These proposals follow a slightly different lifecycle compared to regular proposals. It's important to note that survey-type proposals are not defined as a distinct proposal type but rather possess specific attributes that differentiate them from regular proposals.
A survey-type proposal is created without any instructions attached to it, and it does not allow for the denial vote type (code). Its primary purpose is to gather the opinions and preferences of the community rather than implementing any changes or actions on the blockchain.
Unlike regular proposals that progress through various states, a survey-type proposal bypasses the Succeeded state altogether. Instead, once the voting period for the survey-type proposal ends, it immediately moves to the Completed state. This means that the proposal's outcome does not directly impact the state of the blockchain or trigger any modifications or transactions.
Survey-type proposals serve as a valuable tool for community engagement and decision-making. They enable the governance system to gather feedback, gauge sentiment, and understand the preferences of the community on various matters. By excluding instructions and denying the vote type, survey-type proposals provide a streamlined mechanism to conduct surveys without affecting the state or operation of the blockchain.
Participants within the governance ecosystem can leverage survey-type proposals to solicit community input on important topics, gather consensus on proposed changes, or gauge interest in potential initiatives. The Completed state of these proposals signifies the conclusion of the survey, indicating that the voting period has ended, and the results have been collected.
This article was originally written by Chalda from Marinade (read here). ❤️
We've put together some documentation here, but if you still have questions you'd like answered we’d love to hear from you.
Xentoshi
