Added governance functionalities page (#385)

ndatta-nethermind · varex83 · web-flow · commit 732674c35f53 · 2025-08-27T14:35:15.000+08:00
* Added governance functionalities page

* Update vocs-docs/docs/pages/interaction/data/governance.mdx

Co-authored-by: Bohdan Ohorodnii &lt;35969035+varex83@users.noreply.github.com&gt;

* Added 7th section and links to the source of current liquidity

* Moved governance page to concepts/trading/Configuration, Controls &amp; Environment

---------

Co-authored-by: Bohdan Ohorodnii &lt;35969035+varex83@users.noreply.github.com&gt;
diff --git a/vocs-docs/docs/pages/concepts/trading/governance.mdx b/vocs-docs/docs/pages/concepts/trading/governance.mdx
@@ -0,0 +1,158 @@
+# Governance Functionalities
+
+Below is a current list of all module parameters that `x/gov` has the ability to update directly. Further documentation will be released which outlines overviews of each custom module, how modules interact with one another, and technical guides regarding how to properly submit governance proposals. 
+
+## Trading Stats & Fees
+
+### Stats Module
+
+The Stats Module tracks user maker and taker volumes over a period of time (aka look-back window). This is currently set to 30 days. The maker and taker volume info is used to place users in corresponding fee-tiers. 
+
+Governance has the ability to update the params of the Stats Module, which defines the look-back window (measured in seconds). [Proto](https://github.com/dydxprotocol/v4-chain/blob/4eb219b1b726df9ba17c9939e8bb9296f5e98bb3/proto/dydxprotocol/stats/params.proto#L10-L14)
+
+### FeeTiers Module
+
+Governance has the ability to update fee tiers ([proto](https://github.com/dydxprotocol/v4-chain/blob/4eb219b1b726df9ba17c9939e8bb9296f5e98bb3/proto/dydxprotocol/feetiers/params.proto#L6-L10)). To read more about fee tiers head to [V4 Deep Dive: Rewards and Parameters](https://dydx.exchange/blog/v4-rewards-and-parameters). 
+
+## Trading Core
+
+### Insurance Fund
+
+Governance has the ability to send funds from the Protocol’s Insurance Fund. Funds can be sent to individual accounts, or other modules. 
+
+Note: any account has the ability to send assets to the Insurance Fund. 
+
+### Liquidations Config
+
+Governance has the ability to adjust how liquidations are processed. [Proto](https://github.com/dydxprotocol/v4-chain/blob/4eb219b1b726df9ba17c9939e8bb9296f5e98bb3/proto/dydxprotocol/clob/liquidations_config.proto#L8-L34)
+
+- Max Insurance Fund quantums for deleveraging: The maximum number of quote quantums (exclusive) that the insurance fund can have for deleverages to be enabled.
+- The maximum liquidation fee, in parts-per-million. 100% of this fee goes to the Insurance Fund
+- The maximum amount of how much a single position can be liquidated within one block.
+- The maximum amount of how much a single subaccount can be liquidated within a single block
+- Fillable price config: configuration regarding how the fillable-price spread from the oracle price increases based on the adjusted bankruptcy rating of the subaccount.
+
+### Funding Rate
+
+Governance has the ability to adjust Funding Rate parameters: 
+
+- Funding rate clamp factor, premium vote clamp factor, and min number of votes per premium sample. [Proto](https://github.com/dydxprotocol/v4-chain/blob/4eb219b1b726df9ba17c9939e8bb9296f5e98bb3/proto/dydxprotocol/perpetuals/params.proto#L6-L19)
+- Epoch information, which defines the funding interval and premium sampling interval. [Proto](https://github.com/dydxprotocol/v4-chain/blob/4eb219b1b726df9ba17c9939e8bb9296f5e98bb3/proto/dydxprotocol/epochs/epoch_info.proto#L6-L43)
+- Liquidity Tier, which defines the impact notional value. [Proto](https://github.com/dydxprotocol/v4-chain/blob/4eb219b1b726df9ba17c9939e8bb9296f5e98bb3/proto/dydxprotocol/perpetuals/perpetual.proto#L100-L139)
+
+## Trading Rewards
+
+### Vest Module
+
+The Vest Module is responsible for determining the rate of tokens that vest from Vester Accounts to other accounts such as a Community Treasury Account and a Rewards Treasury Account. The rate of token transfers is linear with respect to time. Thus, block timestamps are used to vest tokens.
+
+Governance has the ability to create, update, or delete a `VestEntry` ([proto](https://github.com/dydxprotocol/v4-chain/blob/4eb219b1b726df9ba17c9939e8bb9296f5e98bb3/proto/dydxprotocol/vest/vest_entry.proto#L9-L30)), which defines:   
+
+- The start and end time of vesting
+- The token that is vested
+- The account to vest tokens to
+- The account to vest tokens from
+
+### Rewards Module
+
+The Rewards Module distributes trading rewards to traders (previously written about [V4 Deep Dive: Rewards and Parameters](https://dydx.exchange/blog/v4-rewards-and-parameters)). Governance has the ability to adjust the following ([proto](https://github.com/dydxprotocol/v4-chain/blob/4eb219b1b726df9ba17c9939e8bb9296f5e98bb3/proto/dydxprotocol/rewards/params.proto#L6-L26)): 
+
+- Which account Trading Rewards are funded from
+- The token Trading Rewards are funded in
+- The market which tracks the oracle price of the token that Trading Rewards are funded in
+- `C` which is a protocol constant further explained in the post linked above
+
+## Markets
+
+### Oracles
+
+Governance has the ability to adjust the list of oracles used for each market. [Proto](https://github.com/dydxprotocol/v4-chain/blob/4eb219b1b726df9ba17c9939e8bb9296f5e98bb3/proto/dydxprotocol/prices/market_param.proto#L31-L33) 
+
+Note that this functionality does not include creating / removing an exchange-source supported by the protocol as a whole, which will require a binary upgrade. 
+
+### Liquidity Tiers
+
+Liquidity Tiers group markets of similar risk into standardized risk parameters. Liquidity tiers specify the margin requirements needed for each market and should be determined based on the depth of the relative market’s spot book as well as the token’s market capitalization. 
+
+[Current Liquidity](https://dydx-ops-rest.kingnodes.com/dydxprotocol/perpetuals/liquidity_tiers) Tiers include:
+
+| ID | Name | initial margin fraction | maintenance fraction (what fraction MMF is of IMF) | impact notional |  maintenance margin fraction (as is) | impact notional (as is) | Lower Cap (USDC Millions) | Upper Cap (USDC Millions) |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 0 | Large-Cap | 0.02 | 0.6 | 500 USDC / IM | 0.012 | 25_000 USDC | None | None |
+| 1 | Small-Cap | 0.1 | 0.5 | 500 USDC / IM | 0.05 | 5_000 USDC | 20 | 50 |
+| 2 | Long-Tail | 0.2 | 0.5 | 500 USDC / IM | 0.1 | 2_500 USDC | 5 | 10 |
+| 3 | Safety | 1 | 0.2 | 2500 USDC / IM | 0.2 | 2_500 USDC | 2 | 5 |
+| 4 | Isolated | 0.05 | 0.6 | 125 USDC / IM | 0.03 | 2_500 USDC | 0.5 | 1 |
+| 5 | Mid-Cap | 0.05 | 0.6 | 250 USDC / IM | 0.03 | 5_000 USDC | 40 | 100 |
+| 6 | FX | 0.01 | 0.5 | 25 USDC / IM | 0.0005 | 2_500 USDC | 0.5 | 1 |
+| 7 | IML 5x | 0.2 | 0.5 | 25 USDC / IM | 0.1 | 125 USDC | 0.5 | 1 |
+
+- Each market has a `Lower Cap` and `Upper Cap` denominated in USDC.
+- Each market already has a `Base IMF`.
+- At any point in time, for each market:
+    - Define
+        - `Open Notional = Open Interest * Oracle Price`
+        - `Scaling Factor = (Open Notional - Lower Cap) / (Upper Cap - Lower Cap)`
+        - `IMF Increase = Scaling Factor * (1 - Base IMF)`
+    - Then a market’s `Effective IMF = Min(Base IMF + Max(IMF Increase, 0), 1.0)`
+- The effective IMF is the base IMF while the Open Notional < Lower Cap, and increases linearly until Open Notional = Upper Cap, at which point the IMF stays at 1.0 (requiring 1:1 collateral for trading)
+
+Governance has the ability to create and modify Liquidity Tiers as well as update existing markets’ Liquidity Tier placements. ([proto](https://github.com/dydxprotocol/v4-chain/blob/4eb219b1b726df9ba17c9939e8bb9296f5e98bb3/proto/dydxprotocol/perpetuals/perpetual.proto#L100-L139))
+
+### Updating a Live Market
+
+This functionality allows the community to update parameters of a live market, which can be composed of 4 parts
+
+- Updating a liquidity tier
+- Perpetual (`x/perpetuals`), governance-updatable through `MsgUpdatePerpetualFeeParams` ([proto definition](https://github.com/dydxprotocol/v4-chain/blob/4eb219b1b726df9ba17c9939e8bb9296f5e98bb3/proto/dydxprotocol/feetiers/tx.proto#L19))
+- Market (`x/prices`), governance-updatable through `MsgUpdateMarketParam` ([proto](https://github.com/dydxprotocol/v4-chain/blob/4eb219b1b726df9ba17c9939e8bb9296f5e98bb3/proto/dydxprotocol/prices/market_param.proto#L6-L34))
+- Clob pair (`x/clob`), governance-updatable through `MsgUpdateClobPair` ([proto](https://github.com/dydxprotocol/v4-chain/blob/b2c6062b4e588b98a51454f50da9e8e712cfc2d9/proto/dydxprotocol/clob/tx.proto#L102))
+
+### Adding New Markets
+
+The action of a governance proposal is defined by the [list of messages that are executed](https://github.com/dydxprotocol/cosmos-sdk/blob/4fadfe5a4606b6dc76644d377ed34420f3b80801/x/gov/abci.go#L72-L90) when it’s accepted. A proposal to add a new market should include the following messages (in this particular order):
+
+```
+MsgCreateOracle (create objects in x/prices)
+MsgCreatePerpetual (create object in x/perpetual)
+MsgCreatePerpetualClobPair (create object in x/clob)
+MsgDelayMessage (schedule a MsgSetClobPairStatus to enable trading in x/clob)
+```
+
+## Safety
+
+### Spam Mitigation
+
+To prevent spam on the orderbook and prevent the blockchain state from getting too large, governance has the ability to adjust: 
+
+- How many open orders a subaccount can have based on its equity tier. [Proto](https://github.com/dydxprotocol/v4-chain/blob/4eb219b1b726df9ba17c9939e8bb9296f5e98bb3/proto/dydxprotocol/clob/equity_tier_limit_config.proto#L8-L19)
+- Order placement rate limits. [Proto](https://github.com/dydxprotocol/v4-chain/blob/4eb219b1b726df9ba17c9939e8bb9296f5e98bb3/proto/dydxprotocol/clob/block_rate_limit_config.proto#L8-L35)
+
+## Bridge
+
+### Bridge Module
+
+The Bridge Module is responsible for receiving bridged tokens from the Ethereum blockchain.
+
+Governance has the ability to update: 
+
+- Event Parameters: Specifies which events to recognize and which tokens to mint. [Proto](https://github.com/dydxprotocol/v4-chain/blob/4eb219b1b726df9ba17c9939e8bb9296f5e98bb3/proto/dydxprotocol/bridge/params.proto#L9-L20)
+- Proposal Parameters: Determines how long a validator should wait until it proposes a bridge event to other validators, and how many or often to propose new bridge events. [Proto](https://github.com/dydxprotocol/v4-chain/blob/4eb219b1b726df9ba17c9939e8bb9296f5e98bb3/proto/dydxprotocol/bridge/params.proto#L22-L45)
+- Safety Parameters: Determines if bridging is enabled/disabled and how many blocks mints are delayed after being accepted by consensus. [Proto](https://github.com/dydxprotocol/v4-chain/blob/4eb219b1b726df9ba17c9939e8bb9296f5e98bb3/proto/dydxprotocol/bridge/params.proto#L47-L55)
+
+## Community Assets
+
+### Community Pool & Treasury
+
+There are two addresses intended for managing funds owned by the community: 
+
+1. a Community Pool and 
+2. a Community Treasury. 
+
+The Community Pool is the recipient of any Community Tax that is implemented via the Distribution Module. The Community Pool is controllable by governance.  
+
+The Community Treasury is an account controlled by governance and can be funded via any account or module sending tokens to it.  
+
+## CosmosSDK Default Modules
+
+For more information on default modules, head to the [Cosmos SDK official documentation](https://docs.cosmos.network/v0.47/modules). dYdX Chain inherits the same governance properties of any standard CosmosSDK modules that are present on dYdX Chain,
diff --git a/vocs-docs/vocs.config.ts b/vocs-docs/vocs.config.ts
@@ -60,7 +60,7 @@ export default defineConfig({
                         {
                             text: 'Watch Orderbook',
                             link: '/interaction/data/watch-orderbook',
-                        },
+                        }
                     ],
                 },
                 {
@@ -248,7 +248,7 @@ export default defineConfig({
                                 {
                                     text: 'Quantums and Subticks',
                                     link: '/concepts/trading/quantums'
-                                },
+                                }
                             ],
                         },
                         {
@@ -322,6 +322,10 @@ export default defineConfig({
                                         }
                                     ],
                                 },
+                                {
+                                    text: 'Governance Functionalities',
+                                    link: '/concepts/trading/governance'
+                                }
                             ],
                         },
                     ],

Original file line number	Diff line number	Diff line change
`@@ -60,7 +60,7 @@ export default defineConfig({`
`60`	`60`	`{`
`61`	`61`	`text: 'Watch Orderbook',`
`62`	`62`	`link: '/interaction/data/watch-orderbook',`
`63`		`- },`
	`63`	`+ }`
`64`	`64`	`],`
`65`	`65`	`},`
`66`	`66`	`{`
`@@ -248,7 +248,7 @@ export default defineConfig({`
`248`	`248`	`{`
`249`	`249`	`text: 'Quantums and Subticks',`
`250`	`250`	`link: '/concepts/trading/quantums'`
`251`		`- },`
	`251`	`+ }`
`252`	`252`	`],`
`253`	`253`	`},`
`254`	`254`	`{`
`@@ -322,6 +322,10 @@ export default defineConfig({`
`322`	`322`	`}`
`323`	`323`	`],`
`324`	`324`	`},`
	`325`	`+ {`
	`326`	`+ text: 'Governance Functionalities',`
	`327`	`+ link: '/concepts/trading/governance'`
	`328`	`+ }`
`325`	`329`	`],`
`326`	`330`	`},`
`327`	`331`	`],`