What is a proposal?
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.
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.
Lifecycle of a Proposal
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: Creating and Signing Off Proposals
Draft State and Options
A new proposal is initially created in the
Draftstate. 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.
While a proposal is in the
Draftstate, the creator has the ability to add multiple signatories to the proposal using the
AddSignatoryinstruction. 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
Draftstate until all defined signatories have confirmed its readiness.
Moving to Voting State
The proposal transitions to the
Votingstate 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
SigningOffstate until all signatories have signed. Once all signatories have signed, the proposal moves directly to the
Votingstate upon the execution of the
Inserting Transactions and Instructions
While the proposal is in the
Votingstate, additional instructions can be added to the proposal by calling the
InsertTransactioninstruction. 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).
Voting State: Casting Votes and Finalising Voting
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
Voting Process and Options
Votingstate, 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
CastVoteinstruction 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_timecan be set up to prolong the voting period. During the
voting_cool_off_time, voters are only allowed to cast negative votes (
vetoes) or relinquish their votes. The voting period can be completed before its designated duration if
vote tippingis enabled.
Voters have the flexibility to change their votes if they change their minds. To cast a new vote, the voter must first call the
RelinquishVoteinstruction, 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
FinalizeVoteinstruction is called. This instruction considers the number of
denyvotes across all options of the proposal, as well as the type of the proposal (code), and determines whether it has
defeated. The proposal is then moved to the appropriate state accordingly.
Veto Voting Workflow
vetovotes, the workflow differs slightly. If the veto threshold is met, the proposal is moved to the final
Vetoedstate. The veto
thresholdis checked with every
CastVotecall, regardless of whether vote tipping is enabled or not.
Canceling a Proposal
Draftstate or the
Votingstate, the proposal may be
canceled. Only the owner of the proposal, referred to as the token owner record account, is permitted to call the
CancelProposalinstruction. The token owner record account is an account associated with the proposal and was inserted into the proposal account during its creation.
Finalisation State: Executing Instructions
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
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.
Survey type proposals
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.
Need help or have feedback?
We've put together some documentation here, but if you still have questions you'd like answered we’d love to hear from you.