The SPL Governance program, developed as part of the Solana Program Library by Solana Labs, is a blockchain-based tool designed to facilitate the management of Decentralised Autonomous Organisations (DAOs).
One of the fundamental use cases of SPL Governance involves creating a multi-sig control mechanism to govern the distribution of funds within the DAO. This enables a simplistic approach to managing DAO finances, where multiple signatures are required to authorise fund transfers. However, the capabilities of SPL Governance extend far beyond basic fund management. It enables smooth and comprehensive DAO governance by allowing the creation of instructions that can be voted upon by the community and/or council. These instructions encompass a wide range of actions, such as minting tokens, transferring funds from the DAO treasury, upgrading the code of programs affiliated with the DAO, and administering the managed programs.
IMPORTANT: This article refers to SPL Governance in version 3.1 released in December 2022.
The SPL Governance program, an integral part of the Solana Program Library, can be found at the following GitHub repository. While a shared instance of the program is deployed at GovER5Lthms3bLBqWub97yVrMmEogzX7xNjdXpPPCVZw, it is generally recommended for DAOs to deploy their own instance of the program. This involves taking the code from the repository and publishing it to the network, generating a unique address for their deployment. By doing so, the DAO gains the advantage of managing program upgrades on its own terms. However, it is important to note that maintaining the program and its upgrades becomes the responsibility of the DAO.
To facilitate the ease of DAO management, SPL Governance provides a user interface (UI) that simplifies the interaction with the program. The UI can be accessed at https://app.realms.today/realms (for working on the devnet, you can add ?cluster=devnet to the address bar). It offers a user-friendly environment where DAO members can conveniently perform various governance tasks. The source code for the UI is openly available at the GitHub repository.
NOTE: When own deployment of program is done the new address should be configured into UI, into a list of known instances. That mostly means creating a PR with the configuration.
To integrate the SPL Governance into your own application, you can use the Typescript SDK under the Oyster repository.
A good complementary resource to this article could be the official README of the governance program at GitHub. A tutorial to UI is available at here.
Then a nice technical description of the SPL Governance system can be found at sec3 article Solana DAO Governance (Part 1): understanding SPL Governance Workflow. A nice governance UI tutorial is available at PsyFi documentation page.
The terms used within the SPL Governance system are a bit ambiguous at some places, so let's pin some of them to clarify their meaning and not missed you in the rest of the text.
The term realm plays a significant role within the texts and documentation of the SPL Governance system. It can be understood as being equivalent to a Decentralised Autonomous Organization (DAO) in certain contexts, where a DAO may consist of multiple realms. To delve deeper into this concept, let's explore its various aspects.
From a technical perspective, a realm serves as the top-level wrapper for configuring a DAO. It represents the highest-level data structure within the program, to which all other data structures refer. Essentially, the realm encapsulates the configuration setup for the DAO, providing a framework for its governance operations.
In some cases, a DAO may require specific configurations for its voting processes. In such scenarios, a decentralised organisation has the flexibility to create multiple realms, all falling under the umbrella of a single DAO. However, it's important to note that this configuration is relatively uncommon. Typically, a DAO is managed within a single realm, and as such, it is customary to consider the terms "DAO" and "realm" as equivalent in the context of the SPL Governance system. This equivalence is why the governance-ui employs both terms interchangeably.
The term "governance" holds significant prominence within the SPL Governance system. It is not only reflected in the name of the library but also encompasses the fundamental purpose of the program, which is to govern the DAO. As developers delve into the repository, they will naturally encounter the term governance (code) promptly. From a code perspective, governance represents a data structure that defines the contents of a Solana account. Importantly, it is tightly associated with a specific realm (as discussed earlier).
The governance component consists of a set of configuration parameters that govern the voting process for proposals within the DAO. It establishes the rules and guidelines for decision-making within the organisation. Additionally, the governance component determines the existence of a unique DAO wallet, which holds native SOL tokens (code). This DAO wallet is an essential Solana account that holds native SOL tokens owned by the System program. It is created as a Program Derived Address (PDA) seeded by the governance account address.
In the SPL Governance program, the DAO wallet is specifically referred to as the native treasury. This term highlights its role as the central repository for the native SOL tokens owned by the DAO. Transactions executed on behalf of a particular realm are associated with a governance, which may utilize the DAO wallet as the fee payer for those transactions.
While the user interface (UI) in the SPL Governance system distinguishes between the governance and the DAO wallet, it is crucial to understand that these terms are intrinsically linked. The governance component defines the parameters and guidelines for decision-making, while the DAO wallet serves as the repository for the native SOL tokens owned by the DAO.
NOTE: It is highly recommended to utilize the address of the DAO wallet (i.e., governance native treasury address) as the authority for managing any assets under the Realm. This includes matters such as a mint authority, a token owner authority, or a contract custom admin authority with permission to make configuration changes. While using the governance address for these purposes is possible, it is not considered a best practice.
Voting is a crucial aspect of the SPL Governance system, enabling DAO members to express their opinions and make collective decisions. A voting process begins with a proposal, which serves as a submission presented to the voters. Within this submission, voters have the opportunity to express their support or opposition by placing their pro or con attitudes towards the proposal.
For a proposal to be considered successful, it must pass the voting process. This means that it must receive a sufficient number of votes in favor of the proposal. If the proposal includes a transaction, its execution can be triggered to finalize the outcome of the voting process and implement the proposed changes or actions.
The resolution of a voting process depends on the number of votes garnered by the proposal. The specific threshold for success is defined by the creator of the voting process and is configured within the governance settings. Each proposal is associated with a particular governance, and the parameters for success are determined within that governance framework.
A voter in the SPL Governance system is represented by a wallet that contains tokens, which serve as identifiers for their voting power. The number of tokens held by a voter determines their influence or weight in the voting process. Generally, the more tokens a voter possesses, the greater voting power and impact on the outcome of the proposals.
If you want to learn more about proposals, read here.
The Governance account structure is documented in the repository. But let's have a look at the account hierarchy in more detail. We will start with the picture of all available accounts and then have a description of them.
The SPL Governance system operates with several key entities, and understanding their roles and relationships is essential for effective utilisation. At the top level, we have the Realm account, representing the DAO (code). The Realm account is identified by a unique PDA address, and its name serves as an identifier that cannot be changed (code). However, a display name can be modified for user interface purposes, such as in the Governance UI.
Within a Realm, there are two distinct voting populations: the council and the community. Each population can configure its own mint, with the community mint being set only at the time of creation and not alterable afterwards. It is worth noting that different community mints can be utilised by creating a new Realm or applying plugin functionality like the Voter Stake Registry (VSR) (code). Members of these populations can create proposals, either with or without execution instructions, and the creator of a proposal determines which voting population is eligible to vote on it. For instance, if a proposal is intended for the council, only council members can vote on it, although community members retain the power to veto such proposals.
Furthermore, the Realm encompasses various configuration parameters, including rules for creating new governance instances. A new governance instance can be initiated when the instruction is signed by the Realm authority address, a council member possessing at least one token, or a community member with sufficient voting power specified in the Realm account.
The configuration details of the Realm are stored in a separate Solana account called the RealmConfigAccount. Within the Realm structure, there is a field known as realm_config, which holds the public key of the corresponding RealmConfigAccount. This separation of accounts stems from historical limitations in Solana that prevented account size changes. The RealmConfigAccount specifies the token type (liquid, membership, dormant/disabled) used for specific voter groups or plugin usage, such as the VSR plugin for voter weight calculation.
Lastly, the Realm can encompass multiple Governance accounts. Governance serves as a fundamental configuration unit, defining parameters such as proposal creation limits, voting durations, voting thresholds, the possibility of early voting completion (known as vote tipping), and the authorisation to sign transactions for execution using governance and native treasury (DAO Wallet) keys.
NOTE: The governance account is another type of account that is created using a program-derived address (PDA). Similar to other accounts mentioned in the listing, the governance account is seeded with the realm account address and a governance_seed.
Previously, the governance_seed used to be a public key associated with the governed program. However, this concept is now considered obsolete. Instead, the governance_seed should be understood as an arbitrary public key used solely to generate the address for the governance account. It is important to note that the Governance account is not limited to governing a single program address. It has the capability to manage various assets, such as tokens, programs, and more.
The Proposal is the final component in the account structure hierarchy of the SPL Governance system. It is associated with a specific governance account and is tied to a single governing token mint, which determines the voting population (either the council or the community) eligible to vote on the proposal. A proposal consists of multiple options, each identified by a unique string label, from which the voting population can choose. Additionally, instructions can be defined for specific options, which are executed if the corresponding option successfully passes the voting process. Once created, the proposal progresses through a lifecycle that encompasses different states (code). Each state within the lifecycle specifies the operations permitted on the proposal. For example, only at certain states can the proposal be canceled, voted on, or have its transaction executed.
For a deep dive on the lifecycle of a proposal and stages, read here.
In version 3.1 of the SPL Governance program, there are three types of governances that can be created: mint governance, program governance, and token governance account types (code). It's important to note that all of these types are considered deprecated, meaning they are no longer actively supported or recommended for use. However, due to certain technical limitations, they are still heavily utilised within the Governance UI.
Lifecycle of a Proposal: Understanding Proposals in SPL Governance
Voting in Realms: Locking Tokens and Plugin System
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
