Network treasury & governance folder

docs/api/building-blocks.md

@@ -77,7 +77,7 @@ Governance proposals used to add new assets and markets, as well as to suggest c
 | Get detailed information about a specific governance proposal using its ID | [Proposal](../api/rest/data-v2/trading-data-service-get-governance-data.api.mdx) | `GET /api/v2/governance`
 |||
 |How to submit proposals using command line | [Submitting proposals](../tutorials/proposals/index.md) | |
-| Understanding the concepts: Governance | [Vega governance](../concepts/governance.md) | 
+| Understanding the concepts: Governance | [Vega governance](../concepts/governance/index.md) | 
 
 ### Governance token
 VEGA token are used for taking part in network, market, asset and freeform governance, and to secure the network by nominating validators that run the network.
@@ -87,4 +87,4 @@ VEGA token are used for taking part in network, market, asset and freeform gover
 | See a list of votes | [List votes](../api/rest/data-v2/trading-data-service-list-votes.api.mdx) | `GET /api/v2/votes` |
 |||
 | How to nominate validators using the smart contracts | [Stake tokens](../tutorials/assets-tokens/staking-tokens.md) | 
-| Understand the concepts: Governance | [Vega governance](../concepts/governance.md) | 
+| Understand the concepts: Governance | [Vega governance](../concepts/governance/index.md) | 

docs/concepts/assets/asset-framework.md

@@ -5,7 +5,7 @@ vega_network: TESTNET
 hide_title: false
 description: Vega supports ERC-20 assets that are added through governance.
 ---
-Vega currently supports exclusively using ERC-20 tokens for markets on Vega. Those assets must be [proposed through governance](../governance.md#asset-governance) and pass the voting threshold, and be enabled on the Vega bridge. ERC-20 tokens originate on the Ethereum chain, not the Vega chain. Inter-chain asset interactions between Vega and Ethereum are facilitated through the Ethereum bridges. 
+Vega currently supports exclusively using ERC-20 tokens for markets on Vega. Those assets must be [proposed through governance](../governance/asset.md) and pass the voting threshold, and be enabled on the Vega bridge. ERC-20 tokens originate on the Ethereum chain, not the Vega chain. Inter-chain asset interactions between Vega and Ethereum are facilitated through the Ethereum bridges. 
 
 The assets on Vega are used for margining and settling positions, paying fees, and supplying liquidity on markets. Assets can also be transferred between keys and accounts.
 
@@ -56,7 +56,7 @@ ERC-20 is a ubiquitous smart contract interface that allows users to mint, issue
 Assets need to be proposed and pass a governance vote before they can be used on the Vega network. After a new asset vote passes, the change has to be submitted to the asset bridge on Ethereum. Until it has been submitted, no one can start depositing that asset. 
 
 :::note Read more
-* [Concept: Asset governance](../governance.md#asset-governance)
+* [Concept: Asset governance](../governance/asset.md)
 * [Tutorial: Proposing an asset](../../tutorials/proposals/new-asset-proposal.md)
 * [Tutorial: Proposing a change to an asset](../../tutorials/proposals/update-asset-proposal.md)
 :::

docs/concepts/assets/transfers.md

@@ -90,6 +90,6 @@ The table below details which types of transfers need to be done using a governa
 | Any other account | Any | No |
 
 :::note Read more
-* [Concept: Transfers initiated by governance](../governance.md#transferring-assets)
+* [Concept: Transfers initiated by governance](../governance/asset.md#propose-an-asset-transfer)
 * [Tutorial: Asset transfer proposal](../../tutorials/proposals/asset-transfer-proposal.md)
 :::

docs/concepts/governance/_category_.json

@@ -0,0 +1,5 @@
+{
+    "label": "Governance",
+    "collapsed": false,
+    "position": 3
+}

docs/concepts/governance/asset.md

@@ -0,0 +1,85 @@
+---
+sidebar_position: 4
+title: Asset governance
+vega_network: TESTNET
+hide_title: false
+description: Add assets or move network-held funds.
+---
+import NetworkParameter from '@site/src/components/NetworkParameter';
+
+## Asset governance
+Assets need to be proposed and pass a governance vote before they can be used on the Vega network.
+
+The protocol currently supports adding ERC-20 assets. Those ERC-20 assets that are successfully validated and pass a governance vote are can be enabled via the Vega bridge. In practice, that means that assets on Vega are deposited from and withdrawn to Ethereum.
+
+After a new asset vote passes, the change has to be submitted to the asset bridge on Ethereum. Until it has been submitted, no one can start depositing that asset. 
+
+Certain asset details can also be changed through a governance proposal. While the [contract-level details](../assets/asset-framework.md#contract-level-details) are immutable, the [protocol-level details](../assets/asset-framework.md#protocol-level-details) can be changed.
+
+:::note Learn more
+See the tutorials to: 
+* [Propose a new asset](../../tutorials/proposals/new-asset-proposal.md)
+* [Propose an update to an asset](../../tutorials/proposals/update-asset-proposal.md)
+:::
+
+### ERC-20 asset validation
+When adding an ERC-20 asset to the bridge, the key details are compared to the smart contract on Ethereum. 
+
+Specifically:
+* The contract must be an ERC-20 asset
+* The name and symbol must match the contract
+* There cannot be multiple assets on a Vega network for the same ERC-20 asset
+
+### Transferring assets
+For assets that are held in certain accounts - those with pooled assets, the community determines if the assets should be moved, and how they should be used. Generally speaking, those accounts have accumulated assets from settled markets, market protection movements, or are entirely funded by community members that transfer assets into them.
+
+These proposals give community members a chance to determine what they think the assets should be spent on, whether that's to fund [trading or validator rewards](../trading-on-vega/discounts-rewards.md#trading-rewards), to move money from [insurance pools](../assets/accounts.md#insurance-pool-accounts) into [network treasury accounts](../assets/accounts.md#network-treasury-accounts), or for other purposes.
+
+Transferring assets from network-managed account types can only be initiated by on-chain governance proposals. 
+
+The transfers from those asset pools can be one-off or recurring. A recurring transfer that's initiated by governance can only be cancelled when a governance proposal to cancel it is submitted and passes the governance vote.
+
+To see a full table of which types of transfers can only be initiated through governance, see the [transfers page](../assets/transfers.md#governance-initiated-transfers).
+
+:::info Read more
+* [Transfers](../assets/transfers.md)
+* [Tutorial: Propose transferring assets](../../tutorials/proposals/asset-transfer-proposal.md)
+:::
+
+### Propose an asset transfer
+Tokenholders can propose asset transfers from certain accounts, which then need to be voted on by other tokenholders. Not all transfers need to be proposed by governance.
+
+The proposer will need to have at least <NetworkParameter frontMatter={frontMatter} param="governance.proposal.transfer.minProposerBalance" hideName={true} suffix="tokens" />, associated with the public key you're using to propose the market, and staked to a validator. Note, this amount is set through the network parameter <NetworkParameter frontMatter={frontMatter} param="governance.proposal.transfer.minProposerBalance" hideValue={true} />.
+
+If the proposal gets a <NetworkParameter frontMatter={frontMatter} param="governance.proposal.transfer.requiredMajority" hideName={true} formatter="percent"/> majority of tokenholder support, then it will be enacted. The required majority is defined by the network parameter <NetworkParameter frontMatter={frontMatter} param="governance.proposal.transfer.requiredMajority" hideValue={true} />. It would also need to pass the required participation threshold: <NetworkParameter frontMatter={frontMatter} param="governance.proposal.transfer.requiredParticipation" hideName={true} formatter="percent" />.
+
+To propose assets be transferred, you'll need to provide the details required for the transfer to be successful. While some of the fields are free-text, others are constrained by a range set through network parameters, to ensure that the values provided are fit for purpose.
+
+Proposal fields include:
+* Source account type: The type of account that the assets are to be transferred from, such as the network treasury
+* Source: The actual account ID. For network treasury, leave it blank.
+* Asset: Asset to transfer
+* Transfer type, which can be 'all or nothing' or 'best effort'
+  * All or nothing: Transfers the specified amount, or nothing 
+  * Best effort: Transfers the specified amount or the max allowable amount if it's less than the specified amount
+* Amount: Maximum amount to transfer; can be used to add an upper limit the fractional amount described below
+* Fraction of balance: Maximum fraction of the source account's balance to transfer, submitted as a decimal (i.e. 0.1 = 10% of the balance)
+* Destination type: Type of account to transfer to, such as reward pool, individual party, market insurance pool
+* Destination: Specific account to transfer to, using an ID or public key. For network treasury, leave it blank.
+* If the proposal is for a one-off transfer, it can optionally define a time, based on Vega time, for delivery. If there is no delivery time, it will execute immediately
+* If the proposal is for a recurring transfer, it must include a start epoch. It can optionally include an end epoch for the last transfer
+
+#### Calculating amount to be transferred
+The final amount transferred is determined based on the inputs into the proposal as well as the values of the relevant network parameters:
+* <NetworkParameter frontMatter={frontMatter} param="governance.transfer.max.amount" /> specifies the maximum amount that can be transferred from a source account in a proposal
+* <NetworkParameter frontMatter={frontMatter} param="governance.transfer.max.fraction" /> specifies the maximum fraction of the balance that can be transferred from a source account.
+
+The final amount is calculated with the following formula:
+
+```
+  transfer_amount = min(
+    proposal.fraction_of_balance * source.balance,
+    proposal.amount,
+    governance.transfer.max.amount,
+    governance.transfer.max.fraction * source.balance )
+```

docs/concepts/governance/index.md

@@ -0,0 +1,33 @@
+---
+sidebar_position: 1
+title: Governance
+vega_network: TESTNET
+hide_title: false
+description: Governance allows tokenholders to make on-chain decision.
+---
+import NetworkParameter from '@site/src/components/NetworkParameter';
+import DocCardList from '@theme/DocCardList';
+import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+
+## Overview
+Governance allows the Vega network to arrive at on-chain decisions, where tokenholders can create proposals that other tokenholders can vote to approve or reject. Contribute to the network by voting or submitting proposals.
+
+Proposals are enacted if they get enough votes from VEGA holders. There's no limit to how many active proposals you can vote on.
+
+Vega supports on-chain proposals for governing:
+* **Markets**: Creating new markets and changing parameters for existing ones
+* **Assets** - Adding new assets and changing parameters for existing ones
+* **Transferring network assets** - Moving network-held assets to different accounts or keys
+* **Network parameters** - Changing the values of existing parameters to change network and market behaviour
+* **Freeform** - Exploring community sentiment for actions that may or may not be enacted on-chain
+
+:::tip Try it out
+**[Vega governance dApp ↗](https://governance.fairground.wtf)**: Read through and vote on active proposals.
+:::
+
+:::note Looking for proposal templates?
+**[Tutorials: Governance proposals](../../tutorials/proposals/index.md)**: See the full range of proposal templates and descriptions of the fields.
+:::
+
+## Governance topics
+<DocCardList items={useCurrentSidebarCategory().items}/>