Merge pull request #52 from anoma/aleks/fixes

Miscellaneous fixes

packages/docs/pages/index.mdx

@@ -17,15 +17,15 @@
 
 ## Overview of features
 
-- Proof-of-Stake with governance to secure and evolve Namada
+- [Proof-of-Stake](./proof-of-stake) with [governance](./governance) to secure and evolve Namada
 - Fast-finality BFT with 4-second blocks
 - Near-zero fees
 - Trust-minimized 2-way Ethereum bridge
 - IBC connections to chains that already speak IBC (all Cosmos chains)
-- Multi-Asset Shielded Pool (MASP)
-- Convert Circuit (shielded set rewards)
+- [Multi-Asset Shielded Pool](./users/shielded-transfers) (MASP)
+- Convert Circuit ([shielded set rewards](./users/shielded-rewards))
 - A reference interface
-- Ledger application
+- [Ledger](./wallet/hardware-wallet) application
 
 For high-level introductions, we recommend:
 

packages/docs/pages/introduction/testnets/pow.mdx

@@ -1,8 +1,12 @@
+import { Callout } from 'nextra-theme-docs'
+
 # The PoW Solution on Namada
 
 In order to combat the "costlessness of blockspace" problem with a testnet, and hence prevent DOS attacks as a result, when a Namada account does not have the required fees to pay for a transaction, the user must complete a Proof of Work challenge. The difficulty of this challenge is a parameter set by governance, and will dictate the (average) computational expenditure needed in order to complete the challenge.
 
-> Note that this current fix will be not be included in Mainnet as it is circumstantial to testnet.
+<Callout type="warning">
+Note that this current fix will be not be included in Mainnet as it is circumstantial to testnet.
+</Callout>
 
 In order to avoid having to complete endless Proof of Work challenges, we recommend using the faucet to fund the implicit account as one of a user's first transactions:
 

packages/docs/pages/ledger/customize.mdx

@@ -1,6 +1,12 @@
+import { Callout } from 'nextra-theme-docs'
+
 # Customize accounts and transactions
-> Note that these features are still a work in progress. At the time of writing, Namada does not allow for custom validity predicates (as there is a whitelist). Custom transactions are possible in certain cases (e.g governance proposals).
 
+<Callout type="warning">
+Note that these features are still a work in progress.
+At the time of writing, Namada does not allow for custom validity predicates (as there is a whitelist).
+Custom transactions are possible in certain cases (e.g., governance proposals).
+</Callout>
 
 On this page, we'll cover how to tailor your account(s) to your use-case with custom-made validity predicates and transactions.
 

packages/docs/pages/public-goods-stewards.mdx

@@ -8,6 +8,6 @@ See the specs about the public goods funding [here](https://specs.namada.net/eco
 
 This documentation will cover:
 
-1. [How to become a public goods steward](#./electing.md)
-2. [How to submit a public goods funding proposal](#./proposing.md)
-3. [How to vote on steward elections](./voting.md#stewards) as well as public goods funding proposal](#./voting.md)
+1. [How to become a public goods steward](./public-goods-stewards/electing.md).
+2. [How to submit a public goods funding proposal](./public-goods-stewards/proposing.md)
+3. [How to vote on steward elections](./public-goods-stewards/voting.md#voting-for-stewards) as well as [public goods funding proposal](./public-goods-stewards/voting.md#voting-for-pgf-proposals).

packages/docs/pages/public-goods-stewards/electing.mdx

@@ -51,15 +51,12 @@ In the motivation and abstract field, it is important to make clear what type of
 
 The CLI command to submit a proposal is:
 
-```bash copy
+```shell copy
 namadac init-proposal \
         --pgf-stewards \
-        --data-path <path/to/steward_proposal.json> \
+        --data-path <path/to/steward_proposal.json>
 ```
-
-<Callout>
-Where `<path/to/steward_proposal.json>` is the path to the `steward_proposal.json` file.
-</Callout>
+where `<path/to/steward_proposal.json>` is the path to the `steward_proposal.json` file.
 
 ### Becoming elected
 

packages/docs/pages/public-goods-stewards/proposing.mdx

@@ -29,7 +29,7 @@ Below is an example of a `PGFProposal` that a steward could submit. Note that on
                 {
                     "target": {
                         "amount": 420,
-                        "address": "atestatest1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn"
+                        "address": "<address-of-recipient>"
                     }
                     "action" : "add",
                 },
@@ -38,16 +38,14 @@ Below is an example of a `PGFProposal` that a steward could submit. Note that on
                 {
                     "target": {
                         "amount": 1337,
-                        "address": "atestatest1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn"
+                        "address": "<address-of-recipient>"
                     }
                 }
             ]
         },  
 }
 ```
-<Callout>
-The address in target should be changed to the address of the recipient of the funds.
-</Callout>
+where `<address-of-recipient>` should be changed to the address of the recipient of the funds.
 
 Save this file as `PGF_proposal.json` to some memorable path on your machine.
 
@@ -58,7 +56,7 @@ In order to submit the proposal, the steward can use the following command:
 ```shell copy
 namada client init-proposal \
     --pgf-proposal \
-    --data-path PGF_proposal.json \
+    --data-path PGF_proposal.json
 ```
 
 The proposal will then be given a `proposal-id` which can be used to query the proposal.
@@ -69,5 +67,5 @@ The command for querying the proposal is as follows:
 
 ```shell copy
 namada client query-proposal \
-    --proposal-id <the-proposal-id> \
+    --proposal-id <the-proposal-id>
 ```

packages/docs/pages/users/an-introduction-to-namada-addresses.mdx

@@ -1,3 +1,5 @@
+import { Callout } from 'nextra-theme-docs'
+
 # An Introduction to Namada Addresses
 
 All accounts in Namada have a unique address, exactly one Validity Predicate and optionally any additional data in its dynamic storage sub-space.
@@ -25,9 +27,11 @@ It is possible to generate keys using the CLI. By doing so, an implicit account
 namada wallet key gen --alias keysha
 ```
 
-> The derived implicit address shares the same `keysha` alias. The previous command has the same effect as `namada wallet address gen --alias keysha`.
+<Callout type="info">
+The derived implicit address shares the same `keysha` alias. The previous command has the same effect as `namada wallet address gen --alias keysha`.
+</Callout>
 
-By default, the keys are stored in encrypted form.
+By default, the keys are stored encrypted.
 The encryption password is _not_ a part of key generation randomness.
 
 Namada wallet supports keypair generation using a [mnemonic code](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) and [HD derivation path](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki).
@@ -36,12 +40,16 @@ To generate a keypair for a default path use
 namada wallet key gen --alias keysha --hd-path default
 ```
 
-> The default HD path for Namada is `m/44'/877'/0'/0'/0'`.
+<Callout type="info">
+The default HD path for Namada is `m/44'/877'/0'/0'/0'`.
+</Callout>
 
-Optionally, the user may specialize an additional passphrase that _is used_ as a part of keypair generation randomness.
+Optionally, the user may specify an additional passphrase that _is used_ as a part of keypair generation randomness.
 
-> WARNING: Keep your mnemonic code and passphrase safe.
-> Loss of any of them would inevitably lead to the impossibility of the account recovery.
+<Callout type="error" emoji="🚨">
+WARNING: Keep your mnemonic code and passphrase safe.
+Loss of any of them would inevitably lead to the impossibility of the account recovery.
+</Callout>
 
 ### Restore the keypair
 
@@ -72,14 +80,16 @@ Let's call the implicit address `accountant`:
 namada wallet address gen --alias accountant
 ```
 
-> Note that this will also generate and save a key from which the address was derived and save it under the same `accountant` alias. Thus, this command has the same effect as `namada wallet key gen --alias accountant`.
+<Callout type="info">
+Note that this will also generate and save a key from which the address was derived and save it under the same `accountant` alias. Thus, this command has the same effect as `namada wallet key gen --alias accountant`.
+</Callout>
 
 ```shell copy
 namada wallet address gen --alias keysha --hd-path default
 ```
 generates an address using a [mnemonic code](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) and [HD derivation path](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki).
 
-### Restore the keypair
+### Restore the address
 
 ```shell copy
 namada wallet address restore --alias keysha --hd-path default

packages/docs/pages/users/send-and-receive-nam-tokens.mdx

@@ -1,8 +1,9 @@
 import { Callout } from 'nextra-theme-docs'
 
-# Send & Receive NAM tokens
+# Send and Receive NAM tokens
 
-In Namada, tokens are implemented as accounts with the [Token Validity Predicate](https://github.com/anoma/namada/blob/namada/wasm/wasm_source/src/vp_token.rs). The validity predicate (VP) checks that the total supply (of the token) is preserved in any transaction that uses this token. Your wallet will be pre-loaded with some token addresses that are initialized in the genesis block.
+In Namada, tokens are implemented as accounts with the [Token Validity Predicate](https://github.com/anoma/namada/blob/main/wasm/wasm_source/src/vp_token.rs).
+The validity predicate (VP) checks, in particular, that the total supply (of the token) is preserved in any transaction that uses this token. Your wallet will be pre-loaded with some token addresses that are initialized in the genesis block.
 
 ### Initialize an established account
 
@@ -17,9 +18,9 @@ namada client init-account \
   --source keysha
 ```
 
-Once this transaction has been applied, the client will automatically see the new address created by the transaction and add it to your Wallet with the chosen alias `establishment`.
+Once this transaction has been applied, the client will automatically see the new address created by the transaction and add it to your wallet with the chosen alias `establishment`.
 
-This command uses the prebuilt [User Validity Predicate](https://github.com/anoma/namada/blob/namada/wasm/wasm_source/src/vp_token.rs).
+This command uses the prebuilt [User Validity Predicate](https://github.com/anoma/namada/blob/main/wasm/wasm_source/src/vp_user.rs).
 
 ### Send a Payment
 

packages/docs/pages/users/shielded-transfers.mdx

@@ -2,7 +2,8 @@ import { Callout } from 'nextra-theme-docs'
 
 # Shielded Transfers
 
-In Namada, shielded transfers are enabled by the [Multi-Asset Shielded Pool](https://specs.namada.net/masp/ledger-integration.html?highlight=MASP#masp-integration-spec) (MASP). The MASP is a zero-knowledge circuit (zk-SNARK) that extends the Zcash Sapling circuit to add support for sending arbitrary assets. All assets in the pool share the same anonymity set, this means that the more transactions are issued to MASP, the stronger are the privacity guarantees.
+In Namada, shielded transfers are enabled by the [Multi-Asset Shielded Pool](https://specs.namada.net/masp/ledger-integration.html?highlight=MASP#masp-integration-spec) (MASP).
+The MASP is a zero-knowledge circuit ([zk-SNARK](https://en.wikipedia.org/wiki/Non-interactive_zero-knowledge_proof)) that extends the [Zcash Sapling circuit](https://raw.githubusercontent.com/zcash/zips/master/protocol/sapling.pdf) to add support for sending arbitrary assets. All assets in the pool share the same anonymity set, this means that the more transactions are issued to MASP, the stronger are the privacity guarantees.
 
 ## Using MASP
 
@@ -12,18 +13,15 @@ If you are familiar with Zcash, the set of interactions you can execute with the
 - [**Shielded transfers:** shielded to shielded addresses](#shielded-transfers)
 - [**Unshielding transfers:** shielded to transparent addresses](#unshielding-transfers)
 
-```admonish info "Lexicon"
+We distinguish two kinds of keys:
 - A **Spending Key** is a type of private key that allows any user in possession of it to spend the balance of the associated address. For shielded addresses, possessing the Spending Key also allows the user to view the address’ balance and transaction data.
 - A **Viewing Key** allows any user in possession of it to view and disclose transaction details. It is derived from the Spending Key and hold the same alias. 
-```
 
-### Shielded transfers
+### Shielding transfers
 
 To try out shielded transfers, you first need to be in possession of a
 transparent account with some token balance.
 
-
-
 #### Generate your Spending Key
 
 You can randomly generate a new Spending Key with:
@@ -32,10 +30,10 @@ You can randomly generate a new Spending Key with:
 namadaw masp gen-key --alias <your-spending-key-alias>
 ```
 
-```admonish info
+<Callout>
 This command will also generate a corresponding Viewing Key sharing
 the same alias.
-```
+</Callout>
 
 #### Create a new payment address
 
@@ -61,7 +59,7 @@ namadac transfer \
     --source <your-established-account-alias> \
     --target <your-payment-address-alias> \
     --token btc \
-    --amount 100
+    --amount <amount-to-shield>
 ```
 
 #### View your balance
@@ -81,9 +79,9 @@ another shielded address:
 ```shell copy
 namadac transfer \
     --source <your-spending-key-alias> \
-    --target [some-payment-address] \
+    --target <destination-payment-address> \
     --token btc \
-    --amount 50 \
+    --amount <amount-to-transfer> \
     --signer <your-implicit-account-alias>
 ```
 
@@ -94,9 +92,9 @@ You can also transfer back your balance to a transparent account:
 ```shell copy
 namadac transfer \
     --source <your-spending-key-alias> \
-    --target [some-transparent-address-alias> \
+    --target <some-transparent-address-alias> \
     --token btc \
-    --amount 50 \
+    --amount <amount-to-unshield> \
     --signer <your-implicit-account-alias>
 ```
 
@@ -109,7 +107,7 @@ When the client generates a spending key, it automatically derives a viewing key
 
 #### Payment Address Generation
 
-Payment addresses can be derived from both spending keys as well as viewing keys. The payment address acts as a destination address in which any tokens received by this address is spendable by the corresponding spending key. Only the payment address's spending key and viewing key are able to spend and view the payment address's balance, respectively. Below are examples of how payment addresses can be
+Payment addresses can be derived from both spending keys as well as viewing keys. The payment address acts as a destination address in which any tokens received by this address is spendable by the corresponding spending key. Only the payment address' spending key and viewing key are able to spend and view the payment address's balance, respectively. Below are examples of how payment addresses can be
 generated:
 
 ```

packages/docs/pages/validators.mdx

@@ -13,10 +13,10 @@ A post-genesis validator, on the other hand, is a validating account which was c
 #### Pre-requisites
 Validators require stake in the form of NAM in order to participate in the consensus process. The amount of stake required is specified in the genesis file. In order to become a validator, you must have at least the minimum amount of stake required.
 
-In addition, the validator node must meet the [minimum hardware requirements](./validators/hardware.md)
+In addition, the validator node must meet the [minimum hardware requirements](./validators/hardware.md).
 
 #### Steps
 
-See these steps for [setting up a genesis validator](./validators/genesis-validator-setup.md)
+See these steps for [setting up a genesis validator](./validators/genesis-validator-setup.md).
 
-See these steps for [setting up a post-genesis validator](./validators/post-genesis-validator-setup.md)
+See these steps for [setting up a post-genesis validator](./validators/post-genesis-validator-setup.md).

packages/docs/pages/validators/genesis-validator-setup.mdx

@@ -2,7 +2,7 @@ import { Callout } from 'nextra-theme-docs'
 
 # Genesis validator setup
 
-A genesis validator is one which is a validator right from the first block of the chain - i.e. at genesis. The details of genesis validators are hardcoded into the genesis file that is distributed to all users who want to interact with a chain.
+A genesis validator is one which is a validator right from the first block of the chain, i.e., at genesis. The details of genesis validators are hardcoded into the genesis file that is distributed to all users who want to interact with a chain.
 
 ### Prerequisites
 
@@ -26,16 +26,17 @@ namada client utils init-genesis-validator --alias $ALIAS \
 
 ### 2. After generating your keys, the command will print something like this:
 
-<Callout>
+<Callout type="info">
 If you have set the variable $XDG_DATA_HOME this is where the pre-genesis TOML will be written to. Otherwise see below for the default locations.
 </Callout>
 
 #### Linux 
-```shell copy
+```text copy
 Pre-genesis TOML written to $HOME/.local/share/namada
 ```
+
 #### MacOS
-```shell copy
+```text copy
 Pre-genesis TOML written to /Users/$USER/Library/Application\ Support/Namada
 ```
 
@@ -57,15 +58,20 @@ Note that the wallet containing your private keys will also be written into this
 ### 4. You can print the validator.toml by running: 
 
 ### Linux 
-`cat $HOME/.local/share/namada/pre-genesis/$ALIAS/validator.toml`
+```shell copy
+cat $HOME/.local/share/namada/pre-genesis/$ALIAS/validator.toml
+```
+
 ### MacOS 
-`cat $HOME/Library/Application\ Support/Namada/pre-genesis/$ALIAS/validator.toml`
+```shell copy
+cat $HOME/Library/Application\ Support/Namada/pre-genesis/$ALIAS/validator.toml
+```
 
 ## Required keys
 
 - Account key: Can be used to sign transactions that require authorization in the default validator validity predicate, such as a balance transfer.
 - Staking rewards key: Can be used to sign transactions on the PoS staking rewards account.
 - Protocol key: This key is used by the validator's ledger itself to sign protocol transaction on behalf of the validator.
-- DKG key: Special key needed for participation in the DKG protocol
-- Consensus key: Used in Cometbft consensus layer. Currently, this key is written to a file which is read by Cometbft.
-- Cometbft node key: This key is used to derive Cometbft node ID for P2P connection authentication. This key is also written to a file which is read by Cometbft.
+- DKG key: Special key needed for participation in the DKG protocol.
+- Consensus key: Used in CometBFT consensus layer. Currently, this key is written to a file which is read by CometBFT.
+- CometBFT node key: This key is used to derive CometBFT node ID for P2P connection authentication. This key is also written to a file which is read by CometBFT.

packages/docs/pages/validators/run-your-genesis-validator.mdx

@@ -7,7 +7,7 @@ As a genesis validator, it is then possible to join the network with the `CHAIN_
 
 In this case, the genesis validator can join the network with:
 
-``` bash
+``` bash copy
 export CHAIN_ID="namada-mainnet"
 namada client utils join-network \
 --chain-id $CHAIN_ID --genesis-validator $ALIAS