Add Proposals section (#132)

src/pages/wasmd/getting-started/_meta.json

@@ -1,5 +1,7 @@
 {
   "setup": "Set Up Your Local Environment",
   "run-node": "Run A Node",
-  "cli": "Interact via the CLI"
+  "cli": "Interact via the CLI",
+  "proposals": "Proposals",
+  "permissions": "Permissions"
 }

src/pages/wasmd/getting-started/proposals.mdx

@@ -0,0 +1,195 @@
+# Proposals
+
+Proposals are a fundamental part of the governance process in the Cosmos ecosystem. They enable
+validators to vote on important decisions that impact the network, such as software upgrades,
+parameter changes, and the allocation of community funds.
+
+## Overview of the Proposal Process
+
+1. Submission: A proposal is submitted along with a deposit to the network.
+2. Deposit Period: Other participants can contribute to the deposit. If the minimum deposit is met,
+   the proposal moves to the voting stage.
+3. Voting Period: Validators and delegators vote on the proposal.
+4. Tallying: After the voting period ends, the votes are tallied to determine whether the proposal
+   has passed or failed.
+5. Execution: If the proposal passes, it is executed according to the details specified in the
+   proposal, such as implementing a parameter change or initiating a software upgrade.
+
+In this section, we'll dive into how to submit CosmWasm proposals. The submission process is a bit
+different from the Cosmos SDK, but the rest, including the deposit period, voting, tallying, and
+execution, follows the usual Cosmos SDK governance process.
+
+For more details on the `gov` module, check out the
+[Cosmos SDK Governance Documentation](https://docs.cosmos.network/v0.50/build/modules/gov) and the
+[Cosmos SDK Proposal Tutorial](https://tutorials.cosmos.network/tutorials/8-understand-sdk-modules/4-gov.html).
+
+## Submit a CosmWasm proposal
+
+You can submit a CosmWasm proposal using the `wasmd tx wasm submit-proposal` command. To see a full
+list of available proposal types, simply add the `--help` flag. Many of these commands, like
+`wasm-store`, `instantiate-contract`, `execute-contract`, `migrate-contract`, are similar to the
+standard `tx` commands and won't be covered in detail here. Instead, we'll focus on the commands
+that are only available through a proposal such as `pin-codes`, `unpin-codes` and `sudo-contract`.
+
+### Pin Codes
+
+Pinning a code means keeping a specific WASM code stored in the cache. This improves the performance
+of frequently used contracts by avoiding the need to reload the code from the blockchain, which
+leads to lower gas costs during contract execution. For more details about code pinning you can
+check the [Contract pinning section](../../core/architecture/pinning.mdx).
+
+To submit a proposal for pinning a code, you can use the following command:
+
+```sh
+wasmd tx wasm submit-proposal pin-codes $CODE_ID \
+  --title "Pin Code $CODE_ID" \
+  --summary "Pin Code $CODE_ID Proposal" \
+  --from alice \
+  --gas 1500000 \
+  -y \
+  --chain-id=docs-chain-1 \
+  -o json \
+  --keyring-backend=test \
+  --deposit 100000stake
+```
+
+You can pin multiple codes by providing a list of code IDs instead of just a single `code_id`. The
+`title` flag specifies the title of the proposal, which should be descriptive and concise, while the
+`summary` flag provides a brief explanation of what the proposal aims to achieve. The `deposit` flag
+indicates the amount of tokens required to submit the proposal, avoiding spam proposals submissions.
+
+To check the details of a submitted proposal, you can query the transaction using the `txhash`
+provided in the command output. This allows you to inspect the emitted events and retrieve the
+`proposal ID`, as shown in the following example:
+
+```json
+{
+  ...
+  "events": [
+    ...
+    {
+      "type": "submit_proposal",
+      "attributes": [
+        {
+          "key": "proposal_id",
+          "value": "2",
+          "index": true
+        },
+        {
+          "key": "proposal_proposer",
+          "value": "wasm10gftgfm8my3f3hymne8327rrzyvy7dqrkucej5",
+          "index": true
+        },
+        {
+          "key": "proposal_messages",
+          "value": ",/cosmwasm.wasm.v1.MsgPinCodes",
+          "index": true
+        },
+        {
+          "key": "msg_index",
+          "value": "0",
+          "index": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+Once you have the `proposal ID`, you can fetch the full proposal details using the following
+command:
+
+```sh
+wasmd q gov proposal 2 -o json
+```
+
+The command will return a JSON object similar to the following:
+
+```json
+{
+  "proposal": {
+    "id": "2",
+    "messages": [
+      {
+        "type": "wasm/MsgPinCodes",
+        "value": {
+          "authority": "wasm10d07y265gmmuvt4z0w9aw880jnsr700js7zslc",
+          "code_ids": ["1"]
+        }
+      }
+    ],
+    "status": 1,
+    "final_tally_result": {
+      "yes_count": "0",
+      "abstain_count": "0",
+      "no_count": "0",
+      "no_with_veto_count": "0"
+    },
+    "submit_time": "2024-08-08T16:48:32.640792888Z",
+    "deposit_end_time": "2024-08-10T16:48:32.640792888Z",
+    "total_deposit": [
+      {
+        "denom": "stake",
+        "amount": "100000"
+      }
+    ],
+    "title": "Pin Code 1",
+    "summary": "Pin Code 1 Proposal",
+    "proposer": "wasm10gftgfm8my3f3hymne8327rrzyvy7dqrkucej5"
+  }
+}
+```
+
+- `id`: This is the unique identifier for the proposal.
+- `messages`: This array contains the specific actions or commands the proposal intends to execute.
+- `status`: Indicates the current status of the proposal.
+- `final_tally_result`: Shows the results of the voting on the proposal.
+- `submit_time`: The timestamp indicating when the proposal was submitted.
+- `deposit_end_time`: The timestamp indicating when the deposit period ends.
+- `total_deposit`: This is the amount of tokens that has been deposited to support the proposal.
+- `title`: Title of the proposal.
+- `summary`: Summary of the proposal.
+- `proposer`: The address of the entity that submitted the proposal.
+
+After the deposit period and voting period, if the proposal passes and is executed, the code is then
+pinned. You can verify the pinned codes by querying them with the following command:
+
+```sh
+wasmd q wasm pinned -o json
+```
+
+The command will return a JSON object similar to the following:
+
+```json
+{
+  "code_ids": [1, 2, 3],
+  "pagination": {
+    "next_key": null,
+    "total": "0"
+  }
+}
+```
+
+The `code_ids` array lists all the code IDs that are currently pinned.
+
+### Unpin codes
+
+To remove a code from the cache and unpin it, you can submit an unpin proposal using the following
+command:
+
+```sh
+wasmd tx wasm submit-proposal unpin-codes $CODE_ID \
+  --title "Pin Code $CODE_ID" \
+  --summary "Pin Code $CODE_ID Proposal" \
+  --from alice \
+  --gas 1500000 \
+  -y \
+  --chain-id=docs-chain-1 \
+  -o json \
+  --keyring-backend=test \
+  --deposit 100000stake
+```
+
+The rest of the process follows the same steps as pinning codes, so we won't go into detail again.
+After the proposal is executed, you can confirm that the code is no longer pinned by using the
+`wasmd q wasm pinned` command.