Merge branch 'brent/update-governance' (#365)

Update governance + PGF docs

packages/docs/pages/integrating-with-namada/light-sdk/examples.mdx

@@ -12,8 +12,8 @@ let tendermint_addr = "http://localhost:26657";
 ### Transfer
 
 ```rust
-let source_address = namada_light_sdk::namada_sdk::address::Address::from_str("tnam1v4ehgw36xq6ngs3ng5crvdpngg6yvsecx4znjdfegyurgwzzx4pyywfexuuyys69gc6rzdfnryrntx").unwrap(); // replace with a valid source address
-let target_address = namada_light_sdk::namada_sdk::address::Address::from_str("tnam1v4ehgw36xq6ngs3ng5crvdpngg6yvsecx4znjdfegyurgwzzx4pyywfexuuyys69gc6rzdfnryrntx").unwrap(); // replace with a valid target address
+let source_address = namada_light_sdk::namada_sdk::address::Address::from_str("tnam1qp326qxmkncgwavskar9lfwm68x04vu8sg80crm4").unwrap(); // replace with a valid source address
+let target_address = namada_light_sdk::namada_sdk::address::Address::from_str("tnam1qp326qxmkncgwavskar9lfwm68x04vu8sg80crm4").unwrap(); // replace with a valid target address
 let token_address = namada_light_sdk::reading::blocking::query_native_token(tendermint_addr).unwrap();
 let amount = namada_light_sdk::namada_sdk::token::DenominatedAmount::from_str("10000").unwrap();
 // Construct the raw transaction struct

packages/docs/pages/integrating-with-namada/sdk/governance.mdx

@@ -8,7 +8,7 @@ The `namada_impl` object is assumed to have been constructed as described in the
 
 ## Constructing a proposal
 ```rust
-    let source_address = namada_sdk::Address::from_str("tnam1v4ehgw36xq6ngs3ng5crvdpngg6yvsecx4znjdfegyurgwzzx4pyywfexuuyys69gc6rzdfnryrntx").unwrap();
+    let source_address = namada_sdk::Address::from_str("tnam1qp326qxmkncgwavskar9lfwm68x04vu8sg80crm4").unwrap();
     let start_epoch = 420 as u64;
     let end_epoch = 424 as u64;
     let grace_epoch = 428 as u64;

packages/docs/pages/integrating-with-namada/sdk/setting-up-a-client.mdx

@@ -106,7 +106,7 @@ When constructing transactions using the sdk, we almost alwasy need a `namada` o
 ```rust
 use namada_sdk::NamadaImpl; // This module allows us to access the NamadaImpl struct, which is needed for most transactions
 
-let source_address = Address::from_str("tnam1v4ehgw36xq6ngs3ng5crvdpngg6yvsecx4znjdfegyurgwzzx4pyywfexuuyys69gc6rzdfnryrntx").unwrap();
+let source_address = Address::from_str("tnam1qp326qxmkncgwavskar9lfwm68x04vu8sg80crm4").unwrap();
 let http_client = reqwest::Client::new();
 let wallet = Wallet::from_mnemonic("your mnemonic here").unwrap();
 let wallet: namada_sdk::wallet::Wallet<FsWalletUtils> = FsWalletUtils::new(PathBuf::from("wallet.toml"));

packages/docs/pages/users.mdx

@@ -10,8 +10,8 @@ make transparent and shielded transactions, stake tokens, and participate in gov
 - [The MASP](./users/shielded-accounts.mdx)
 - [Fees on Namada](./users/fees.mdx)
 - [Bonding and Proof-of-stake](./users/delegators.mdx)
-- [Governance and Public Goods Funding](./users/governance.mdx)
-- [PGF](./users/public-goods-stewards.mdx)
+- [Governance](./users/governance.mdx)
+- [Public Goods Funding](./users/public-goods-funding.mdx)
 - [IBC transfers](./users/ibc.mdx)
 - [Querying the chain](./users/query.mdx)
 

packages/docs/pages/users/_meta.json

@@ -4,8 +4,8 @@
   "shielded-accounts": "MASP & Shielded Transfers",
   "fees": "Fees on Namada",
   "delegators": "Bonding and Proof-of-stake",
-  "governance": "Governance and Public Goods Funding",
-  "public-goods-stewards": "PGF",
+  "governance": "Governance",
+  "public-goods-funding": "Public Goods Funding (PGF)",
   "ibc": "IBC transfers",
   "query": "Querying the Chain"
-}
+}

packages/docs/pages/users/governance.mdx

@@ -1,8 +1,30 @@
 # Governance
 
-The Namada governance mechanism gives users the possibility to upgrade the protocol dynamically.
+The Namada governance mechanism gives the community of users and operators the ability to upgrade the protocol dynamically.
+Additionally, governance can be used for social coordination.
 
-There are two different mechanism to create a proposal:
+Any user account can submit a governance proposal on-chain that contains some metadata and optionally some code for the protocol to execute if the proposal is accepted.
+Accounts that have active bonds can vote on the proposals with voting power proportional to their bonded token amount.
 
-- [On-chain proposals](./governance/on-chain-governance.mdx): Proposal is voted on and tallied on-chain. This can optionally include proposal code to be executed if the proposal is accepted.
-- [Off-chain proposals](./governance/off-chain-governance.mdx)
+Governance proposals must contain the following metadata related to the epochs for voting and execution:
+- `start_epoch`: the first epoch in which users can vote on the proposal.
+- `end_epoch`: the epoch in which the voting period stops. The last epoch in which votes can be submitted is the epoch before this.
+- `activation_epoch`: the epoch in which any governance proposal code is executed by the protocol. The execution occurs while finalizing the first block of this epoch before processing any transactions.
+
+Additionally, validator accounts may only vote in approximately the first 2/3 of the active voting period.
+
+A user who submits a governance proposal on-chain also must put an additional token amount - the `min_proposal_fund` - to be held while the proposal is active. This fee is refunded to the proposal author if the proposal passes, but otherwise the fee is kept in the governance account.
+
+The governance system is configured by the following parameters:
+
+- `min_proposal_fund:` the fee needed to submit a proposal
+- `min_proposal_voting_period:` minimum allowed number of epochs between a proposal's start and end epochs
+- `max_proposal_period:` maximum allowed number of epochs between a proposal's start and activation_epoch
+- `min_proposal_grace_epochs:` minimum allowed number of epochs between a proposal's end and activation epochs
+- `max_proposal_latency:` maximum allowed epochs between a proposal's start epoch and the current epoch in which the proposal tx is submitted
+
+This documentation covers:
+
+1. [What a governance proposal looks like](./governance/proposal-structure.mdx).
+2. [Different kinds of proposals](./governance/proposal-types.mdx)
+3. [How to query, submit, and vote on proposals](./governance/governance-actions.mdx)

packages/docs/pages/users/governance/_meta.json

@@ -1,4 +1,5 @@
 {
-  "on-chain-governance": "On-chain proposals",
-  "off-chain-governance": "Off-chain proposals"
-}
+  "proposal-structure": "Structure of a proposal",
+  "proposal-types": "Types of proposals",
+  "governance-actions": "Participating in governance"
+}

packages/docs/pages/users/governance/governance-actions.mdx

@@ -0,0 +1,121 @@
+import { Callout } from 'nextra-theme-docs'
+
+# Governance actions
+
+## Submitting the proposal
+While in the same directory as your final `proposal.json` file, you can submit the proposal with:
+
+**For a default proposal:**
+
+```shell copy
+namada client init-proposal --data-path proposal.json 
+```
+
+**For non-default proposals:**
+
+One of the flags `--pgf-stewards`, `--pgf-funding`, `--eth` must be specified. For example, for a PGF steward proposal:
+
+```shell copy
+namada client init-proposal --pgf-stewards --data-path proposal.json
+```
+
+## Query the proposal
+If the submitted transaction was accepted, the user can query the proposal with its proposal ID:
+
+```shell copy
+namada client query-proposal --proposal-id $ID
+```
+
+Additionally, the user can query some of the most recent proposals with:
+
+```shell copy
+namada client query-proposal
+```
+
+## Vote on a proposal
+
+Only delegators and validators can vote on proposals. A delegator or validator can send a vote with the following command:
+
+```shell copy
+namada client vote-proposal \
+    --proposal-id $ID \
+    --vote yay \
+    --address $YOUR_ADDRESS
+```
+where `--vote` can be either `yay`, `nay` or `abstain`.
+
+<Callout type="info">
+The `--address` flag needs to be the address of the delegator or validator that is voting. You may also use the `--gas-payer` flag to specify the address of the account that will pay for the gas.
+</Callout>
+
+
+## Check the result
+
+As soon as the ledger reaches the epoch defined in the json as `voting_end_epoch`, no more votes will be accepted.
+At the beginning of the `activation_epoch`, the votes are tallied.
+If the proposal passes, the code defined in `proposal_code` json field will be executed at this time.
+
+You can use the following commands to check the status of a proposal:
+
+```shell copy
+namada client query-proposal --proposal-id $ID
+```
+
+or to just check the result:
+
+```shell copy
+namada client query-proposal-result --proposal-id $ID
+```
+
+<Callout type="info">
+If the proposal has not passed, it will be rejected, and the code will not be executed.
+
+Another important note is that the voting period differs between validators and non-validators. The validators have a shorter voting period than the delegators. This is to ensure that the non-validators have enough time to vote on the proposals (so that the validators cannot vote in the last block against the non-validators preference). See the specs for more information.
+</Callout>
+
+### Tally types
+The governance mechanism defines different criteria depending on proposal type in order for the proposal to pass:
+
+**Default proposals** require at least 2/3 of the total active voting power to have voted AND the `yay` voting power must be at least 2/3 of the combined `yay + nay` voting power.
+
+**PGF steward proposals** require at least 1/3 of the total acive voting power to have voted AND the `yay` voting power must be larger than the `nay` voting power.
+
+**Funding proposals** are tallied differently depending on if the proposal author is a PGF steward:
+- Non-steward: the funding proposal is tallied in the same way as the PGF steward proposal (above).  
+- Steward: the proposal can pass without any votes at all. However, the network can veto the proposal if 1/3 of the total active voting power votes, and the `nay` votes are larger than the `yay` votes.
+In other words, the proposal passes if less than 1/3 of the total voting power votes OR there are more `yay` votes than `nay` votes.
+
+## Submit a governance proposal with wasm code attached
+
+First you will need a valid `.wasm` file. You then need to read this file into a vector of bytes. This can be done with the following small python script:
+
+```python
+with open(wasm_file_path, "rb") as f:
+    byte_vec = list(f.read())
+print(str(byte_vec))
+```
+
+The output can then be copied into the `data` field of the proposal json. E.g `"data": [1,255,3,4,5,182,7,81,90,10]`.
+
+Additionally, there is a script in the namada repo called [`add_proposal_wasm_code.py`](https://github.com/anoma/namada/blob/main/scripts/add_proposal_wasm_code.py) that can be used to add the wasm data to a proposal template like `template_proposal.json` (LINK TO THIS TOO!):
+
+```shell copy
+python3 add_proposal_wasm_code.py --proposal-path $JSON_FILE --wasm-path $$WASM_FILE
+```
+
+This command will add the wasm data to the `$JSON_FILE`.
+
+When submitting this proposal, it is likely that the gas requirement will be large. Therefore, it is recommended to supply at least the `--gas-limit` flag.
+
+```shell copy
+namadac init-proposal --data-path proposal.json --gas-limit 500000
+```
+
+<Callout type="info">
+Hint: use the `--dry-run` feature to figure out how much gas will be needed and use `namadac query-protocol-paramters` to see the current minimum gas price.
+</Callout>
+
+## A video tutorial
+Skip all the boring text and watch a video tutorial on how to submit a proposal:
+
+<iframe src="https://player.vimeo.com/video/914426953?badge=0&amp;autopause=0&amp;player_id=0&amp;app_id=58479" width="640" height="416" frameBorder="0" allow="autoplay; fullscreen; picture-in-picture" allowFullScreen></iframe>