This article introduces Mango Market Governance within Realms, an infrastructure for governance on Solana. We will detail how users can create proposals and add instructions. These instructions will then execute upon the proposal's passing.

Table of Contents

What are instructions?

• Creating a Proposal

• Add Instruction to the Proposal

List of all the Instructions in Mango DAO

• Create Perp

• Create Stub Oracle

• Edit Group

• Edit Openbook Market

• Edit Perp

• Edit Token

• Enable/Disable individual instructions in Group

• Extend Address Lookup Table

• Idl Set Buffer

• Register Openbook Market

• Register Token

• Register Trustless Token

• Set Address Lookup Table for Group

• Set Stub Oracle Value

• Withdraw Perp Fees

• Withdraw Token Fees

What are instructions?

First of all, what are instructions? The most important functionality in a DAO is the creation of proposals containing blockchain instructions that DAO members may vote upon. Upon successful voting, the instructions may be executed. Instructions are specified rules that can trigger action on the blockchain upon successful voting. Proposals can be created with or without instructions. Different projects design instructions based on their needs and use-cases. Read here on how to participate in the MangoDAO governance voting.

Main takeaways to remember are:

1. Every decision in DAOs is made with proposals.

2. Proposals can carry instructions which get executed when proposal pass.

Let's go through an example of creating a proposal to add additional bank to an existing token:

1. Creating a Proposal

Connect your wallet possessing governance power onto Realms & scroll to the home page of your DAO. Press “New Proposal” & draft a title & description. Please be as detailed, in the interest of transparency.

2. Add Instruction to the Proposal

Scroll down and you choose the Mango Market v4 instruction set either by clicking on the icon (3rd from left) or using the drop-down menu. Let's do one proposal with instruction ‘Add additional Bank to an existing Token' as an example. This instruction allows the protocol to expand liquidity and trading options by adding another bank that holds reserves of an existing token.

There are two parameters that are needed for every instruction, and those are:

• Governance - Governance address to which the instruction should be applied.

• Instruction hold up time (days) - Refers to the period after a vote ends, during which the execution of the instruction is delayed. For instance, if there's an 8-hour hold-up time after the vote concludes, the instruction can't be executed for those 8 hours. This delay allows for preparations in the interim. Importantly, during the hold-up time, the instruction's execution is only postponed – it cannot be voted down or prevented.

• Tokens - This list includes assets like KIN, HNT, SOL, wBTC (Portal), MNGO, bSOL, MSOL, DAI, ORCA, LDO, RAY, stSOL, BONK, ETH (Portal), DUAL, JitoSOL, USDT, and USDC that you may use for payments within the Mango Markets DAO.

Once done, preview the transaction and press ‘Add Proposal’. If there is quorum and enough yes votes, proposal will pass and instruction from the proposal will be executed.

All the proposal instructions in Mango DAO follow a similar workflow, although the number of parameters required may vary among them.

List of all the instructions in Mango DAO

Let's take a look at all the instructions Mango created:

Create Perp

Perpetual contracts track the price movement of underlying assets and enable leveraged trading. By creating a new Perp, users can speculate on the price of an asset without holding it directly.

• Perp Name - Name of the new Perpetual Market.

• Perp Market Index - This is an identifier or index number for the perpetual market.

• Oracle Public Key - An oracle is a system that feeds external price information into a blockchain. The PublicKey is a unique identifier for the specific oracle being used to supply price information for this market.

• Oracle Confidence Filter - This is a value between 0 and 1 that sets a confidence level for the oracle price feed. It helps filter out potentially incorrect price data.

• Max Staleness Slots - Defines how long a price from the oracle is considered valid, measured in slots (Solana's time units).

• Base Decimals - This refers to the number of decimal places used in the base currency of the perpetual market. It helps in representing fractional values of the asset.

• Quote Lot Size - This is a complex parameter related to the pricing structure of the market. The quote lot size must be a power of 10 and is primarily useful for increasing the tick size (minimum price movement) on the market. The formula given explains how the lot price translates into the native and user interface (UI) prices by considering the quote lot size, base lot size, base decimals, and quote decimals.

• Base Lot Size - The base lot size defines the minimum quantity of the base asset that can be traded. It must be a power of 10, and it helps determine the minimum tradable unit. The calculation provided illustrates how the base lot size works with base decimals to translate into native and user interface positions.

• Maintenance Base Asset Weight - This weight applies to the base asset in a trading position and helps determine whether the position is healthy or needs to be closed.

• Init Base Asset Weight - This is the initial weight applied to the base asset when a trading position is first opened. It sets the starting rules for a trade.

• Maintenance Base Liab Weight - This weight is used to calculate the health of the liabilities in a trader's position and ensures that the position is maintained properly.

• Init Base Liab Weight - This weight sets the initial rules for the liabilities when a trader opens a new position.

• Maint Overall Asset Weight - This weight is used to mantain the health of the whole perpetual market. It's like a safety check for the entire trading game.

• Init Overall Asset Weight - This is the starting weight for the entire market, setting the initial balance for the trading system.

• Base Liquidation Fee - This fee is charged when a trading position is closed because it's not healthy. It's like a penalty for not following the rules.

• Maker Fee - This fee or reward is for traders who make offers in the market.

• Taker Fee - This fee is charged to traders who take offers from the market. It can't be negative and ensures that the market stays balanced.

• Fee Penalty - This is a specific fee charged for IOC (Immediate or Cancel) orders, which must be executed immediately or canceled if not filled. It's a penalty to discourage specific trading behaviors.

• Group Insurance Fund - This refers to a shared fund that may cover the market, acting like an insurance policy to protect against unexpected losses.

• Settle Fee Flat - This is a fixed fee, given in the native units of a settlement token, that's charged when settling a trade above a certain threshold.

• Settle Fee Amount Threshold - This is the minimum amount that must be settled for the flat settle fee to apply.

• Settle Fee Fraction Low Health - This fee applies when an account with positive profits has low health. It's a fraction of the profits paid out as a fee.

• Settle Token Index and Settle Pnl Limit Window Size - This identifies the token used for settlements. Currently, it's set to USDC, but other tokens might be allowed in the future.

• Settle Pnl Limit Factor - These control how profits and losses (PnL) are settled, with limits and rules to make sure everything is fair. The window size refer to a time window for these rules.

• Min Funding and Max Funding - These set the lowest and highest funding rates allowed per day. They ensure that the funding stays within certain bounds.

• Impact Quantity - For calculating funding, this determines how deep into the order book the impact price is calculated. It's a measure of how big trades affect the market price.

• Positive Pnl Liquidation Fee - This is a fee charged when a position with positive profits is forcibly closed or liquidated. It might be used to cover costs or as a penalty.

Create Stub Oracle

Creating a stub oracle involves setting up a temporary or placeholder data feed for pricing. This can be used in testing or in scenarios where the full oracle service isn't yet available. It's a part of governance processes to manage the system's data inputs.

• Price - The price parameter represent the current value or cost of a particular asset or commodity within the system. It is tied to the data from an oracle or another price source.

• Mint - Minting refers to the process of creating new digital tokens or assets.

Edit Group

The "Edit Group" instruction allow authorized users (such as administrators or governance bodies) to modify key operational settings, control parameters, and functionalities.

• Admin - This parameter identifies the administrative account or entity with special permissions to manage certain aspects of the proposal.

• Fast Listing Admin - A designated address responsible for approving or speeding up the listing of new assets on the platform.

• Security Admin - The address or entity responsible for managing security-related matters, such as authentication and authorization.

• Testing - A binary parameter (0 or 1) indicating whether the proposal is in a testing phase.

• Version - This denotes the current version of the protocol or the feature being controlled, helping in managing updates or upgrades.

• Deposit limit quote - This sets the maximum amount of quote currency that can be deposited into the market. A value of 0 indicates no limit.

• Fee Pay with MNGO - Allows users to pay fees using Mango's native token (MNGO).

• Fees MNGO Bonus Rate - If set, this could provide bonuses or discounts on fees when paid with MNGO tokens.

• Fees Swap Mango Account - An address likely used to handle fee-related swaps within the platform.

• Fees MNGO Token Index - An index pointing to the specific MNGO token contract or type, for accurate fee management.

• Fees Expiry Interval - Specifies the time after which the fees may expire, and a new fee structure may be applied.

• Token Conditional Swap Taker Fee Fraction & Token Conditional Swap Maker Fee Fraction - These represent the fees for takers and makers in token-based conditional swaps on the platform. The "taker" is the one who accepts the offer, and the "maker" is the one who creates the offer.

• Force Values - These values give specific permissions to the administrators to override or enforce certain values or settings within the system.

Edit Openbook Market

This instruction allows adjustments to specific settings of Openbook markets, which are spot trading markets on Mango Markets. Traders can modify order types, and market-making incentives to create optimal trading environments.

• Market - Trading pairs. A proposal can target any one of these pairs, for example MNGO/USDC.

• Name - Name of the new Openbook Market.

• Reduce Only - Risk management feature that restricts certain trading operations. When enabled, it may only allow orders that would reduce an existing position rather than create or increase one.

• Force Close - An option to forcibly close specific positions or even an entire market. It may be used in emergency situations, such as when there's a critical vulnerability or significant market manipulation.

Edit Perp

The Edit Perp instruction enables adjustments to existing perpetual contracts. Traders can modify parameters such as leverage, margin requirements, and funding rates to optimize their trading strategies and risk management.

• Perp - Perpetual contracts available for trading on the platform, each tied to specific assets. For example: MNGO-PERP-OLD, ETH-PERP, RNDR-PERP, SOL-PERP, BTC-PERP.

• Name - This is the name assigned to the particular perpetual contract.

• Oracle - A data source that provides the current market price for the underlying asset of a perpetual contract, helping maintain accurate pricing.

• Oracle Confidence Filter - A threshold that filters out any price updates from the oracle that deviate too significantly from current expectations.

• Max Staleness Slots - Defines how long a price from the oracle is considered valid, measured in slots (Solana's time units).

• Base Decimals -The number of decimal places for the underlying asset in the perpetual contract.

• Stable Price Delay Growth Limit and Stable Price Growth Limit - Parameters that constrain how the stable price of the asset can change to prevent drastic fluctuations.

• Maintenance and Init Base Asset/Liab Weight - These weights determine the amount of collateral required and assist in managing leverage and risk.

• Maint Overall Asset Weight - This weight is used to mantain the health of the whole perpetual market. It's like a safety check for the entire trading game.

• Init Overall Asset Weight - This is the starting weight for the entire market, setting the initial balance for the trading system.

• Base Liquidation Fee - A fee charged when a base position is liquidated.

• Maker Fee - A fee or reward for matching maker orders in the trading system.

• Taker Fee - A fee for taking an existing order from the order book.

• Fee Penalty - A specific fee charged for Immediate-or-Cancel (IOC) orders.

• Settle Fee Flat, Settle Fee Amount Threshold, Settle Fee Fraction Low Health - Various fees tied to the settlement of positions, linked to conditions like the health of an account.

• Stable Price Delay Interval Seconds - The time delay for updating the stable price of an asset.

• Settle Pnl Limit Factor, Settle Pnl Limit Window Size - Controls for setting limits on profit and loss (PnL) settlement.

• Min Funding, Max Funding - Minimum and maximum boundaries for the daily funding rate of a contract.

• Impact Quantity - The depth into the order book used to calculate the impact price for funding purposes.

• Positive Pnl Liquidation Fee - A fee charged on liquidation if the position has positive profit and loss (PnL).

• Group Insurance Fund - Indicates whether this market is backed by a collective insurance fund to mitigate potential losses.

• Reduce Only - If enabled, restricts users to actions that reduce their position in the market, disallowing them from increasing their exposure.

• Reset Stable Price, Force Close - Administrative controls to reset stable prices or forcibly close positions.

Edit Token

This instruction enables the editing of an existing token within the Mango Markets.

• Token Selection - Choose a token from drop-down menu.

• Mint & Oracle - These fields are for managing the creation of new tokens (minting) and determining price feeds from an oracle.

• Oracle Confidence Filter - A threshold that filters out any price updates from the oracle that deviate too significantly from current expectations.

• Max Staleness Slots - Defines how long a price from the oracle is considered valid, measured in slots (Solana's time units).

• Interest Rate Adjustment Factors - Various parameters here allow for the fine-tuning of interest rates based on utilization levels. This enables a flexible adjustment in borrowing costs according to the market's demand.

• Loan Fee Rate & Loan Origination Fee Rate - The fees associated with taking out a loan. These could include a continuous charge (interest) and a one-time fee when the loan is created.

• Maintenance & Init Asset/Liab Weights - Risk management parameters relating to collateral and liability. They may influence how a user's position is liquidated if they become over-leveraged.

• Liquidation Fee - A fee charged when a position is forcibly closed (liquidated) due to inadequate collateral.

• Group Insurance Fund - A fund to cover unexpected losses in the market. The 'Is this market covered by the group insurance fund?' field confirms whether this market participates in such a fund.

• Stable Price Delay & Growth Limits - Parameters for controlling how quickly a stable price can change and how much it can grow over certain intervals.

• Min Vault To Deposits Ratio - The minimum amount of deposits that must stay in the vault when borrowing, for maintaining liquidity.

• Net Borrow Limit Per Window & Window Size - Constraints for net borrowing in a specific window of time.

• Borrow & Deposit Weight Scale Start Quote - These parameters control the soft limits on borrowing and collateral and how they are scaled under certain conditions.

• Reset Stable Price & Net Borrow Limit - Options to reset specific market conditions.

• Reduce Only - If activated, users can only reduce their market exposure, not increase it.

• Disabled Force Close - An option to forcefully close particular market functionality.

Enable/Disable individual instructions in Group

This instruction provides granular control over the functionalities available for specific token groups. This allows the administrators to control specific features or functions, either enabling or disabling them within a particular group.

• Account Close - Ends an account, removing it from the active state.

• Account Create - Initiates a new account, setting it up for use within the platform.

• Account Edit - Allows changes to be made to the account's details or settings.

• Account Expand - Enables an account to be expanded, possibly increasing its functionality or capacity.

• Account Toggle Freeze - Allows an account to be frozen or unfrozen, controlling its access to particular functions.

• Alt Extend/Alt Set - Used to modify alternative settings or parameters within the system.

• Flash Loan - Enables the instant borrowing of assets, often used in arbitrage or other time-sensitive trading strategies.

• Group Close/Create - Allows the creation or closing groups within the platform.

• Group Toggle Halt - Can pause or resume activities within a specific group.

• Health Region - Monitors the health or stability of particular regions or sectors within the market.

• Perp Functions - These are related to Perpetual Contracts and include instructions for creating, editing, deactivating, settling fees, updating funding, placing orders, canceling orders, and handling liquidations.

• Serum 3 Functions - These instructions are related to managing the Serum decentralized exchange's markets, including registering, editing, placing orders, canceling orders, and more.

• Stub Oracle Functions - Oracle-related commands that might be used for testing or interacting with price feeds.

• Token Functions - These involve managing tokens within the platform, including adding banks, deposits, withdrawals, registering trustless options, and handling liquidation.

• Account Buyback Fees With Mngo - Specific instruction to handle fees through the buyback with the native Mango token - MNGO.

• Token Force Close Borrows With Token - Closes borrowing positions forcefully with the respective token.

• Perp Force Close Position - Forces the closing of a perpetual position.

• Group Withdraw Insurance Fund - Allows the withdrawal from an insurance fund related to the group.

• Token Conditional Swap Functions - These include creating, triggering, and canceling conditional swaps involving tokens.

• Openbook V2 Functions - Instructions related to managing the Openbook Version 2 market, including registering, editing, placing orders, settling funds, etc.

• Admin Token/Perp Withdraw Fees - Specific instructions for administrators to withdraw fees associated with tokens or perpetual contracts.

Extend Address Lookup Table

Address Lookup Tables, commonly referred to as "lookup tables" or "ALTs" for short, allow developers to create a collection of related addresses to efficiently load more addresses in a single transaction. This instruction adds new entries or updates existing ones in the address lookup table, ensuring efficient tracking and identification of entities within the Mango Markets protocol. Read more about lookup tables here.

• Address Lookup Table - Address of the Lookup Table.

• Index - Specific position within the Address Lookup Table.

• Public Keys - Actual addresses to be included in the Address Lookup Table.

Idl Set Buffer

This instruction sets a buffer or limit for token prices during Initial DEX Offerings (IDLs). IDLs are token sales conducted on decentralized exchanges, and this instruction helps stabilize token prices during the offering process.

• Program - Address of a program that the buffer applies.

• Idl Account - Account where the IDLs is being controlled by the buffer.

• Buffer - Limit set by the instruction, guiding the token price range during the IDL process.

Register Openbook Market

Similar to registering tokens, this instruction enables the addition of new Openbook markets to the Mango Markets platform. It expands the range of trading pairs available for users.

• Name - Label for the market.

• Market Index - Index (e.g., 551) identify the specific market.

• Openbook Market External - This might refer to any external parameters or connections that the Openbook Market interacts with, possibly including other markets or data sources.

• Base Bank and Quote Bank - Two assets being traded in the market, with the "Base Bank" being the main asset and the "Quote Bank" being the secondary asset that the base is traded against.

• Openbook Program - This address refers to the specific smart contract responsible for handling the functions and logic of the Openbook Market.

Register Token

This instruction enables the integration of new tokens into the Mango Markets ecosystem. By registering a token, it becomes tradable on the platform, opening up new markets and expanding the range of assets available for users to trade.

• Mint PublicKey - The public key identifying the mint for the token. This is a unique identifier tied to the specific token being registered.

• Oracle PublicKey - The public key identifying the oracle that will provide price information for the token.

• Oracle Confidence Filter - This sets the confidence level required from the oracle data. The values range between 0 and 1, with higher values requiring more confidence.

• Max Staleness Slots - This determines the maximum number of slots (a measure of time in Solana) that the oracle data can be old before it's considered stale and unusable.

• Token Name - The human-readable name of the token being registered.

• Token Index - A numerical index identifying the token within the system.

• Interest Rate Adjustment Factor - This factor is used to adjust the interest rate dynamically based on market conditions.

• Interest Rate Utilization Points - These values define different levels of utilization that trigger changes in the interest rate.

• Interest Rate Points - These are the corresponding interest rates at the specified utilization points.

• Interest Rate Max Rate - The maximum interest rate that can be charged.

• Loan Fee Rate - The fee charged on loans as a proportion of the loan amount.

• Loan Origination Fee Rate - The fee charged when a loan is initiated.

• Maintenance and Init Asset/Liab Weight - These weights are used in calculating the risk and maintenance requirements of loans.

• Liquidation Fee - The fee charged if a loan has to be liquidated.

• Min Vault To Deposits Ratio - This sets the minimum fraction of deposits that must remain in the vault when borrowing, to ensure a level of collateral.

• Net Borrow Limit Window Size - This defines the time window, in seconds, for tracking net borrow limits.

• Net Borrow Limit Per Window Quote - This sets the net borrow limit per window in quote native currency. A value of -1 disables this limit.

Register Trustless Token

Similar to registering regular tokens, this instruction allows the integration of trustless tokens into the Mango Markets platform.

• Mint PublicKey - The public key identifying the mint for the token. This is a unique identifier tied to the specific token being registered.

• Oracle PublicKey - The public key identifying the oracle that will provide price information for the token.

• Token Name - The human-readable name of the token being registered.

• Token Index (551) - A numerical index identifying the token within the system.

Set Address Lookup Table for Group

This instruction associates a specific address lookup table with a particular group of tokens. It allows different token groups to have separate address lookup tables.

• Address Lookup Table - Address of the Lookup Table.

• Index - Specific position within the Address Lookup Table.

Set Stub Oracle Value

This instruction allows authorized parties to update the value provided by a Stub Oracle. Accurate price data is essential for the correct valuation and functioning of the protocol, and this instruction ensures the data remains up-to-date.

• Price - Up-to-date price of the Stub Oracle.

• Oracle - Address of the previously created Stub Oracle.

Withdraw Perp Fees

Refers to the fees associated with withdrawing from a perpetual contract position.

• Perp - Perpetual contract from which the fees are being withdraw.

Withdraw Token Fees

Refers to the fees associated with withdrawing specific token .

• Token - Token from which the fees are being withdraw.

Conclusion

This is in-depth guide on creating proposals with executable instructions in Mango DAO. Mango Markets is an open-source project. All Mango DAO decisions are being discussed in a forum here.

Learn more

• Mango Markets Documentation

• SPL Governance / Realms Documentation

Need help or have feedback?

You can reach Mango team via Discord and Twitter. However, if you have any questions regarding Realms UI, reach out here.

If you prefer video guide, follow this tutorial.

When you create your DAO for the first time on Realms, it will look a little bit blank. You would want to add your project's logo, banner and other branding material as well as information like twitter handle and website URL.

To do that, you would need to create pull request on the Github that will be merged into the main repository and become visible on your DAO's page. The process is easy and this guide will take you step by step on how to do that. Let's start.

1) How to upload DAO's logo and banner

Make sure to have an Github account.

Head to https://github.com/solana-labs/governance-ui repository and fork it.

Then go to Your repositories and open the fork.

Go to /public/realms folder.

Click on Add File -> Upload files in the top right corner.

Drag and drop a folder with a name of the DAO containing two image files: logo and banner. Commit the changes.

After you commit changes, you can go to /public/realms folder and search for your DAO's name. You will find a folder with two image files.

If you don't want to make any other changes, continue to the Pull request to the governance-ui repository section below.

2) How to upload links and about info

Go to /public/realms folder and scroll down until you find mainnet-beta.json file. Open it.

We will add your DAO's information at the end of the array. Click at the pen in the top right corner to enter edit mode and scroll all the way down.

Add comma after the last object and then add object containing your DAO information in format below. Here is an example of all the information you can add about your DAO.

  {
    "symbol": "MNGO",
    "category": "defi",
    "bannerImage": "https://i.imgur.com/i1gGoIw.jpg",
    "displayName": "Mango DAO",
    "programId": "GqTPL6qRf5aUuqscLh8Rg2HTxPUXfhhAXDptTLhp1t2J",
    "realmId": "DPiH3H3c7t47BMxqTxLsuPQpEC6Kne8GA9VXbxpnZxFE",
    "communityMint": "MangoCzJ36AjZyKwVj3VnYU4GTonjfVEnJmvvWaxLac",
    "ogImage": "https://i.imgur.com/448n6bC.jpg",
    "shortDescription": "Every market, all the power, none of the fuss. Simplifying decentralized finance through easy-to-use products and developer tools.",
    "sortRank": 3,
    "website": "https://mango.markets",
    "keywords": "Mango Markets, REALM, Governance, Serum, SRM, Serum DEX, DEFI, Decentralized Finance, Decentralised Finance, Crypto, ERC20, Ethereum, Decentralize, Solana, SOL, SPL, Cross-Chain, Trading, Fastest, Fast, SerumBTC, SerumUSD, SRM Tokens, SPL Tokens",
    "twitter": "@mangomarkets",
    "discord": "https://discord.com/invite/2uwjsBc5yw",
    "github": "https://github.com/blockworks-foundation/"
  },

At the moment, not all the information is visible in the UI, and that may probably change in the future as the platform further develops.

You don't need to add all the information. Fill the ones that work for you. For example:

{ 
   "symbol": "YDAO",
   "displayName": "yourDAO",
// programId and realmId can be found in the DAO's Dashboard > Params
// programId refers to Owner address
// realmId refers to Pubkey address
   "programId": "GovRp7uazvmYkQ7gqjdfjKFwr6pHDcYFWH3SP9DHzdtR",
   "realmId": "eSkHn3pytkDRnifeULCpUPmKTFmuxiAbSc7jLVEYqbrv",
   "ogImage": "/realms/yourDAO/yourDAO_logo.jpg", // <--- path to logo
   "bannerImage": "/realms/yourDAO/yourDAO_banner.png", // <--- path to banner
   "website": "https://www.yourDAOexample.com", // <--- website url
   "twitter": "@yDAO" // <--- twitter handle
},

Don't forget programId and realmId.

👀 Where to find programId and realmId?

Go to your DAO's dashboard and go to Params:

You will find programId under Owner, and realmId under Pubkey.

Now that we have all we need, add the object with your DAO's information at the end of the array in mainnet-beta.json file.

After you added your DAO's info like in the example below, commit changes directly to the main branch.

✅ Pull request to the governance-ui repository

To make your changes visible in the Realms UI, you need to create a pull request for your changes to be added to the main repository. Follow an example below on how to create a pull request:

After you send your Pull Request, someone from the team will merge it and you will be able to see the changes in Realms UI. Head out to Discord and let them know that you need a merge.

Learn more

• Documentation

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.

You can reach Realms team via Discord and Twitter.

Voting is a fundamental aspect of the SPL Governance system that allows participants to have a say in decision-making. In this chapter, we will explore who can vote on proposals and how is the voting power calculated?

To be eligible to vote, an individual must be the owner of the relevant tokens. When a realm is created within the SPL Governance system, the community and council mints are defined. Ownership of tokens from these mints grants individuals the right to participate in the voting process.

The calculation of voting power is based on the ratio between the number of tokens a voter has locked and the maximum voter weight of tokens for the respective mint. For council tokens, the maximum voter weight is typically equivalent to the total supply of tokens for that mint. However, for community tokens, the maximum voter weight can be configured differently. The realm configuration allows for the community_mint_max_voter_weight_source attribute to be set, which can consider factors such as the total supply of tokens, an absolute number, or a fraction of the total supply (code). The plugin system can also be utilized for additional flexibility in configuring voting power (see below).

In addition to token ownership, the realm configuration also determines how tokens are treated within the governance system (code). If a token is designated as membership type, it is controlled by the realm and cannot be transferred to another wallet. On the other hand, if a token is classified as liquid type, it can be freely traded and transferred, and the authority over the mint is controlled either by the realm or by another entity. The dormant token type indicates that a portion of the voting population is disabled within the realm.

To exercise their voting power, token owners must lock their tokens to the realm. This is accomplished through a deposit call (code), which effectively locks the tokens until an active proposal, in which the voter has participated, exists. To withdraw their tokens, owners must wait until the voting period for the active proposal concludes or choose to relinquish their votes.

For each voter, the SPL Governance system creates a token owner record, associated with their wallet. This record keeps track of the number of tokens locked, the number of active proposals the voter has voted on, and the number of un-relinquished proposals. These factors determine the eligibility for withdrawal.

The voting power of a token owner is determined by the number of locked tokens recorded in their token owner record. It's important to note that an owner can delegate their voting power to another wallet by setting up the delegate field (code) in their token owner record. However, each token owner record can have only one delegate defined.

Vote record

Casting a vote means to add the voting weight to the proposal option (code). The voter can choose to vote for or against the proposal or to abstain from voting. The type of vote is defined by the Vote enum and passed as an argument in the cast vote instruction (code).

When a token owner wishes to cast their vote, they have three options: voting for the proposal, voting against it, or choosing to abstain. The type of vote is defined by the Vote enum, which is passed as an argument in the cast vote instruction.

Once a vote is cast, information about the vote is recorded in two key locations within the Solana blockchain. First, the proposal account is updated to include a summary of the voting weights for each option (code). This information is utilised during the finalisation of the proposal, although vote records themselves are not directly used for this purpose.

The second location where voting information is stored is in a vote record account. This account serves as a repository of details regarding the casted vote. It captures essential information such as the voting weight assigned to the option, the type of vote (for, against, or abstain), and other relevant data. The creation of a vote record account confirms that a vote has been cast by a specific token owner for a particular proposal. The purpose of the vote record is twofold: to prevent double voting by ensuring that a token owner can only cast one vote per proposal and to maintain a historical record of voting activities.

By storing voting information in both the proposal account and the vote record account, the SPL Governance system ensures transparency, integrity, and accountability in the voting process. This data contributes to the determination of the outcome of proposals and allows for auditing and analysis of past voting activities.

Plugin System

The SPL Governance program is built with extensibility in mind, allowing for flexibility and customisation to meet the unique needs of different DAOs. In version 3.1 of the program, there are two available extension points: the voter weight addin and the max voter weight addin. These extensions enhance the functionality of the governance system and provide additional options for calculating voting power.

When configuring a realm in the SPL Governance system, it is possible to specify an addin to be used for the calculation of the voting power, also known as the voter weight, and the maximum voter weight (code). This configuration attribute opens up many possibilities for determining voting power beyond simply relying on the number of locked tokens associated with a specific mint.

By utilising an addin, the voting power calculation can incorporate various factors or metrics that are relevant to the specific DAO's governance model. This means that the voting power can be derived from sources other than just the quantity of locked tokens.

The ability to configure addins for voter weight and max voter weight calculations empowers DAOs to design their governance systems in a way that aligns with their unique dynamics and objectives. It allows for a more nuanced and tailored approach to voting power, reflecting the intricacies of the DAO's token ecosystem, membership structure, or other relevant factors.

Learn more

• SPL Governance: A Technical Overview

• Lifecycle of a Proposal: Understanding Proposals in SPL Governance

This article was originally written by Chalda from Marinade (read here). ❤️

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.

You can reach Realms team via Discord and Twitter.

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.

Where to Find and How to Get

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.

Additional Resources

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.

Terms and Glossary

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.

DAO vs. Realm

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.

Governance vs. DAO Wallet

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.

Proposal

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.

SPL Governance Account Structure

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.

Different Types of Governances

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.

Learn more

• 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). ❤️

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.

You can reach Realms team via Discord and Twitter.

This is part one of a three-part series on creating DAOs in Realms. You can read about the creation of the NFT Community DAO here and the creation of the Community Token DAO here.

What is multi-sig and how is it related to DAOs?

Multi-sig is a shortened term for "multi-signature," which refers to a digital signature scheme that requires more than one person or entity to sign off on a transaction before it can be executed. The purpose of this is to avoid giving a single person or entity too much control over the decision-making process.

For instance, if you're managing funds or assets as part of a group, multi-sig can be useful to require that several people must agree to any transactions that involve those funds or assets. This ensures that no one person can make decisions alone, without the group's consent.

When it comes to DAOs or "decentralized autonomous organizations," multi-sig is especially relevant because they are essentially run by computer code instead of humans. DAOs are typically built on blockchain technology, which allows for decentralized decision-making and transparent record-keeping.

Using multi-sig in a DAO can help to ensure that decisions are made democratically and in a decentralized manner. For example, a DAO might require a certain percentage of its members to sign off on major decisions or transactions. This approach ensures that no one person or entity can unilaterally control the DAO, and that all decisions are made democratically.

In this guide, we'll walk you through the process of creating a multi-signature wallet on Solana using Realms in just four simple steps.

What is Realms?

Realms is a platform built on Solana that provides tools for builders to create and manage their own DAO. Using Realms, builders can create their own DAO, which allows them to manage their members, vote on proposals, and allocate their treasury. Realms provides a user-friendly frontend interface that allows DAO members to interact with the smart contracts that govern the DAO.

Realms is built on top of SPL Governance, which is a DAO and asset-type agnostic standard for building and maintaining DAOs on Solana. This means that builders can create any type of DAO they want, whether it's a multi-sig DAO, an NFT community DAO, or a community token DAO. This article is about creating a multi-sig DAO. For information on other types of DAOs, please refer to the documentation here.

Multi-sig DAO is considered as "startup DAO", when you are at the inception of your DAO, you might not have community/token yet and this allows you to grow it and progressively decentralise. If all you need is Multi-sig for decision-making then I would suggest to use Squads instead.

Now that we cleared the terminology, let's dive in how to create your own multi-sig DAO.

How to create a multi-sig wallet?

Prerequisite: This tutorial assumes that you are familiar with cryptocurrency and crypto wallets, as a Solana wallet is required to use Realms. Help me setup the wallet.

Now that you have your Solana wallet set, let's keep going.

Go to realms.today and connect your wallet in the top right corner by clicking on Sign in with Solana. Once you have connected your wallet, hover over it and choose View DAOs, which will open this page for you:

Click on "Create DAO" button and the following wizard will be shown:

Since we are building multi-sig wallet, click on Multi-Signature Wallet option.

1) Choose a name

Your DAO needs a name, so now is the time to choose one.

TIP:
Realms will provide a governance program ID by default, users can add their own customer Program ID under Advanced Options at this step in the multisig wallet wizard.

2) Invite Members

The primary purpose of a multi-signature wallet is to enable multiple wallet holders to decide on how the funds and assets that belongs to DAO will be used. In this step, you can add Solana addresses to the multi-signature wallet. To add, paste the public wallet addresses.

3) Set approval threshold

In the next step, you are going to set the approval threshold. The approval threshold refers to the minimum percentage of votes required for a proposal or decision to be approved. The default is 60%.

For example, if the approval threshold is set at 60%, this means that a proposal needs to receive 60% or more "yes" votes to be approved. If the proposal receives less than 60% "yes" votes, it will not be approved.

DAOs can set their own approval thresholds, and they can vary depending on the context and the specific rules of the DAO. In some DAOs, the approval threshold may be set very high to ensure that decisions are only made with a broad consensus, while in other DAOs, the approval threshold may be set lower to allow for more flexibility in decision making.

4) Review

After following this steps, you should have something like the image below:

Then just click Create Wallet, your wallet will pop up asking for signature. Approve it to create the tokens and deploy the DAO.

After the transaction is complete, you'll be redirected to the DAO's page.

And that's it. You created a DAO. 👏👏👏

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.

You can reach Realms team via Discord and Twitter.