Mango Markets is a decentralized platform built on the Solana blockchain, offering a one-stop solution to lend, borrow, swap and leverage-trade various crypto assets. The entire platform is governed by MNGO token holders through the Mango DAO.

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.