From c67959de1b6dbc595dc14d3eae4bc9dbd92d1375 Mon Sep 17 00:00:00 2001 From: bengtlofgren Date: Tue, 10 Oct 2023 11:30:53 +0200 Subject: [PATCH 1/5] users section links fixed --- packages/docs/pages/introduction/install.mdx | 8 +++---- .../install/binaries/prerequisites.mdx | 4 ++-- .../pages/introduction/install/source.mdx | 2 +- .../docs/pages/introduction/quick-start.mdx | 4 ++-- packages/docs/pages/networks/testnets.mdx | 16 ++++++------- .../networks/testnets/environment-setup.mdx | 6 ++--- packages/docs/pages/networks/testnets/faq.mdx | 6 ++--- .../testnets/genesis-validator-apply.mdx | 2 +- .../networks/testnets/joining-the-testnet.mdx | 6 ++--- .../testnets/post-genesis-validator.mdx | 4 ++-- .../pages/networks/testnets/pre-genesis.mdx | 4 ++-- .../networks/testnets/testnet-history.mdx | 6 ++--- packages/docs/pages/operators/ledger.mdx | 6 ++--- .../docs/pages/operators/local-network.mdx | 2 +- packages/docs/pages/operators/validators.mdx | 6 ++--- .../validators/genesis-validator-setup.mdx | 2 +- .../post-genesis-validator-setup.mdx | 2 +- packages/docs/pages/users.mdx | 1 - packages/docs/pages/users/delegators.mdx | 6 ++--- packages/docs/pages/users/fees.mdx | 2 +- packages/docs/pages/users/governance.mdx | 4 ++-- .../governance/public-goods-stewards.mdx | 8 +++---- .../public-goods-stewards/electing.mdx | 4 ++-- .../shielded-accounts/shielded-rewards.mdx | 2 +- .../shielded-accounts/shielded-transfers.mdx | 24 +++++++++---------- .../docs/pages/users/transparent-accounts.mdx | 2 +- .../send-and-receive-nam-tokens.mdx | 2 +- packages/docs/pages/users/wallet.mdx | 10 ++++---- .../pages/users/wallet/hardware-wallet.mdx | 4 ++-- .../docs/pages/users/wallet/web-wallet.mdx | 4 ++-- packages/specs/pages/base-ledger.mdx | 4 ++-- .../base-ledger/block-space-allocator.mdx | 2 +- .../pages/base-ledger/fungible-token.mdx | 2 +- .../pages/base-ledger/replay-protection.mdx | 12 +++++----- .../replay-protection/optimizations.mdx | 6 ++--- packages/specs/pages/economics.mdx | 2 +- packages/specs/pages/economics/fee-system.mdx | 4 ++-- .../pages/economics/inflation-system.mdx | 6 ++--- .../specs/pages/economics/proof-of-stake.mdx | 4 ++-- .../proof-of-stake/cubic-slashing.mdx | 2 +- .../proof-of-stake/objects-and-txs.mdx | 8 +++---- .../proof-of-stake/reward-distribution.mdx | 6 ++--- .../becoming-a-steward.mdx | 2 +- .../economics/shielded-pool-incentives.mdx | 2 +- packages/specs/pages/governance.mdx | 2 +- packages/specs/pages/governance/off-chain.mdx | 2 +- packages/specs/pages/governance/on-chain.mdx | 8 +++---- packages/specs/pages/governance/storage.mdx | 2 +- packages/specs/pages/index.mdx | 10 ++++---- packages/specs/pages/interoperability.mdx | 4 ++-- .../interoperability/ethereum-bridge.mdx | 16 ++++++------- .../ethereum-bridge/bootstrapping.mdx | 2 +- .../ethereum-bridge/proofs.mdx | 4 ++-- .../ethereum-bridge/transfers_to_ethereum.mdx | 2 +- packages/specs/pages/interoperability/ibc.mdx | 2 +- packages/specs/pages/masp.mdx | 10 ++++---- .../specs/pages/masp/ledger-integration.mdx | 2 +- 57 files changed, 143 insertions(+), 144 deletions(-) diff --git a/packages/docs/pages/introduction/install.mdx b/packages/docs/pages/introduction/install.mdx index 08c6f5ac..a16896d9 100644 --- a/packages/docs/pages/introduction/install.mdx +++ b/packages/docs/pages/introduction/install.mdx @@ -9,8 +9,8 @@ At the moment, Namada only supports Linux and MacOS. ## Installing Namada Namada can be installed through the following methods: -1. [From source](./install/source.md) -2. [From binaries](./install/binaries.md) -3. [From a docker image](./install/docker.md) +1. [From source](./install/source.mdx) +2. [From binaries](./install/binaries.mdx) +3. [From a docker image](./install/docker.mdx) -The hardware requirements for installing and running a Namada full node can be found [here](../../validators/hardware.md) \ No newline at end of file +The hardware requirements for installing and running a Namada full node can be found [here](../../validators/hardware.mdx) \ No newline at end of file diff --git a/packages/docs/pages/introduction/install/binaries/prerequisites.mdx b/packages/docs/pages/introduction/install/binaries/prerequisites.mdx index 8fc42451..a5131837 100644 --- a/packages/docs/pages/introduction/install/binaries/prerequisites.mdx +++ b/packages/docs/pages/introduction/install/binaries/prerequisites.mdx @@ -1,6 +1,6 @@ ## Installing CometBFT -Follow [these instructions](.introduction/installing-cometbft.md) in order to setup CometBFT. +Follow [these instructions](.introduction/installing-cometbft.mdx) in order to setup CometBFT. ## Installing GLIBC Finally, you should have GLIBC `v2.29` or higher. @@ -9,4 +9,4 @@ Finally, you should have GLIBC `v2.29` or higher. **Ubuntu 20.04**: glibc is installed by default and you don't have to do anything more. -**Ubuntu 18.04**: glibc has `v2.27` by default which is lower than the required version to run Namada. We recommend to directly [install from source](./source.md) or upgrade to Ubuntu 19.04, instead of updating glibc to the required version, since the latter way can be a messy and tedious task. In case updating glibc would interest you, this [website](http://www.linuxfromscratch.org/lfs/view/9.0-systemd/chapter05/glibc.html) gives you the steps to build the package from source. +**Ubuntu 18.04**: glibc has `v2.27` by default which is lower than the required version to run Namada. We recommend to directly [install from source](./source.mdx) or upgrade to Ubuntu 19.04, instead of updating glibc to the required version, since the latter way can be a messy and tedious task. In case updating glibc would interest you, this [website](http://www.linuxfromscratch.org/lfs/view/9.0-systemd/chapter05/glibc.html) gives you the steps to build the package from source. diff --git a/packages/docs/pages/introduction/install/source.mdx b/packages/docs/pages/introduction/install/source.mdx index f5318f96..d44b40a6 100644 --- a/packages/docs/pages/introduction/install/source.mdx +++ b/packages/docs/pages/introduction/install/source.mdx @@ -21,7 +21,7 @@ make install During internal and private testnets, checkout the latest testnet branch using `git checkout $NAMADA_TESTNET_BRANCH`. -Where `$NAMADA_TESTNET_BRANCH` is the name of the testnet branch, which will be specified in the [testnet documentation](../testnets/environment-setup.md). +Where `$NAMADA_TESTNET_BRANCH` is the name of the testnet branch, which will be specified in the [testnet documentation](../testnets/environment-setup.mdx). ## Adding binaries to `$PATH` diff --git a/packages/docs/pages/introduction/quick-start.mdx b/packages/docs/pages/introduction/quick-start.mdx index a7fc584c..1fe65e35 100644 --- a/packages/docs/pages/introduction/quick-start.mdx +++ b/packages/docs/pages/introduction/quick-start.mdx @@ -6,7 +6,7 @@ This guide is for those interested in getting Namada up and running as quickly a ## Installing Namada -See [the installation guide](./install.md) for details on installing the Namada binaries. Commands in this guide will assume you have the Namada binaries (`namada`, `namadan`, `namadaw`, `namadac`) on your `$PATH`. +See [the installation guide](./install.mdx) for details on installing the Namada binaries. Commands in this guide will assume you have the Namada binaries (`namada`, `namadan`, `namadaw`, `namadac`) on your `$PATH`. If the binaries are stored somewhere, but are not on your path (perhaps you downloaded the binaries), you can add the binaries to your $PATH with: @@ -67,4 +67,4 @@ Testnet tokens can be sourced from the faucet, which is available on Discord. ## From here -From here, you can do a variety of cool things. Perhaps try [shielding your NAM](../../users/shielded-transfers.md), bonding your tokens to a validator for [delegating purposes](../../delegators.md), or [becoming a validator](../../validators.md). +From here, you can do a variety of cool things. Perhaps try [shielding your NAM](../../users/shielded-transfers.mdx), bonding your tokens to a validator for [delegating purposes](../../delegators.mdx), or [becoming a validator](../../validators.mdx). diff --git a/packages/docs/pages/networks/testnets.mdx b/packages/docs/pages/networks/testnets.mdx index c1bbada1..5160cf06 100644 --- a/packages/docs/pages/networks/testnets.mdx +++ b/packages/docs/pages/networks/testnets.mdx @@ -11,7 +11,7 @@ For more context read: - Cometbft version: `0.37.2` - CHAIN_ID: `public-testnet-14.5d79b6958580` -The history of all testnets can be found [here](./testnets/testnet-history.md). +The history of all testnets can be found [here](./testnets/testnet-history.mdx). ## Namada protocol versions @@ -23,13 +23,13 @@ If you find a bug, please submit an issue with the `bug` [issue template](https: ## How to join a Namada testnet -1. [Environment setup](./testnets/environment-setup.md) -2. [Pre-genesis instructions](./testnets/pre-genesis.md) -3. [Pre-genesis validator setup](../operators/validators/genesis-validator-setup.md) -4. [Pre-genesis validator apply](./testnets/genesis-validator-apply.md) -5. [Running your genesis validator](../operators/validators/run-your-genesis-validator.md) -6. [Running a full node](../operators/ledger/running-a-full-node.md) -7. [Becoming a validator post-genesis](./testnets/post-genesis-validator.md) +1. [Environment setup](./testnets/environment-setup.mdx) +2. [Pre-genesis instructions](./testnets/pre-genesis.mdx) +3. [Pre-genesis validator setup](../operators/validators/genesis-validator-setup.mdx) +4. [Pre-genesis validator apply](./testnets/genesis-validator-apply.mdx) +5. [Running your genesis validator](../operators/validators/run-your-genesis-validator.mdx) +6. [Running a full node](../operators/ledger/running-a-full-node.mdx) +7. [Becoming a validator post-genesis](./testnets/post-genesis-validator.mdx) ## Testnet flowchart ![testnet_flowchart](/images/testnet_flowchart.png) diff --git a/packages/docs/pages/networks/testnets/environment-setup.mdx b/packages/docs/pages/networks/testnets/environment-setup.mdx index bd80703f..6b5c292a 100644 --- a/packages/docs/pages/networks/testnets/environment-setup.mdx +++ b/packages/docs/pages/networks/testnets/environment-setup.mdx @@ -19,8 +19,8 @@ export NAMADA_TAG=v0.23.0 ### Install all pre-requisites - [Rust](https://www.rust-lang.org/tools/install) - - [CometBFT](../../introduction/installing-cometbft.md) - - [Protobuf](../../introduction/install/source/pre-requisites.md) + - [CometBFT](../../introduction/installing-cometbft.mdx) + - [Protobuf](../../introduction/install/source/pre-requisites.mdx) ### Clone namada repository and checkout the correct versions @@ -40,7 +40,7 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ## Installing CometBFT -### See the installing CometBFT section [here](../../introduction/installing-cometbft.md) for instructions on how to install CometBFT. +### See the installing CometBFT section [here](../../introduction/installing-cometbft.mdx) for instructions on how to install CometBFT. ### Copy both the namada and CometBFT binaries to somewhere on $PATH (or use the relative paths). This step may or may not be necessary. - namada binaries can be found in `/target/release` diff --git a/packages/docs/pages/networks/testnets/faq.mdx b/packages/docs/pages/networks/testnets/faq.mdx index 5264ac38..90329305 100644 --- a/packages/docs/pages/networks/testnets/faq.mdx +++ b/packages/docs/pages/networks/testnets/faq.mdx @@ -2,7 +2,7 @@ ### **Q: How do I join as a validator post-genesis?** -**A:** Joining as a validator post genesis can be done following [these instructions](../../operators/validators/post-genesis-validator-setup.md). +**A:** Joining as a validator post genesis can be done following [these instructions](../../operators/validators/post-genesis-validator-setup.mdx). ### **Q: How do I use the Faucet?** @@ -27,10 +27,10 @@ HINT: `namadac balance` ### **Q: What requirements do I need to be a User/Validator?** -**A:** See [hardware requirements](../../operators/validators/hardware.md). +**A:** See [hardware requirements](../../operators/validators/hardware.mdx). In order to build binaries from source, at least 16GB RAM will be required. ### **Q: Where can I find the binaries to run Namada if I do not want to build from source?** -**A:** See [Installing Namada from binaries](../../introduction/install/binaries.md) +**A:** See [Installing Namada from binaries](../../introduction/install/binaries.mdx) diff --git a/packages/docs/pages/networks/testnets/genesis-validator-apply.mdx b/packages/docs/pages/networks/testnets/genesis-validator-apply.mdx index 38e24387..aadd597e 100644 --- a/packages/docs/pages/networks/testnets/genesis-validator-apply.mdx +++ b/packages/docs/pages/networks/testnets/genesis-validator-apply.mdx @@ -6,7 +6,7 @@ Before a testnet launches, you can apply to be a genesis validator. ### Set up -Follow [this guide](../../operators/validators/genesis-validator-setup.md#pre-genesis) on how to generate your "pre-genesis" validator files. +Follow [this guide](../../operators/validators/genesis-validator-setup.mdx#pre-genesis) on how to generate your "pre-genesis" validator files. After this, you'll have a `validator.toml` file, the contents of which will look something like the following: diff --git a/packages/docs/pages/networks/testnets/joining-the-testnet.mdx b/packages/docs/pages/networks/testnets/joining-the-testnet.mdx index 0b9c2a09..39a6e707 100644 --- a/packages/docs/pages/networks/testnets/joining-the-testnet.mdx +++ b/packages/docs/pages/networks/testnets/joining-the-testnet.mdx @@ -5,11 +5,11 @@ Depending on whether you are a genesis validator, you can join the latest testne ## Joining as a genesis validator Joining the testnet validator is identical to that of a mainnet validator. -For this reason, please refer to [these docs](../../operators/validators/run-your-genesis-validator.md). +For this reason, please refer to [these docs](../../operators/validators/run-your-genesis-validator.mdx). ## Joining as a full node -If you are not a genesis validator, please follow the steps for [joining as a full node](../../operators/ledger/running-a-full-node.md). +If you are not a genesis validator, please follow the steps for [joining as a full node](../../operators/ledger/running-a-full-node.mdx). -It is then possible to test being a validator by [becoming a post-genesis validator](./post-genesis-validator.md). +It is then possible to test being a validator by [becoming a post-genesis validator](./post-genesis-validator.mdx). diff --git a/packages/docs/pages/networks/testnets/post-genesis-validator.mdx b/packages/docs/pages/networks/testnets/post-genesis-validator.mdx index e9d7fa17..a396be69 100644 --- a/packages/docs/pages/networks/testnets/post-genesis-validator.mdx +++ b/packages/docs/pages/networks/testnets/post-genesis-validator.mdx @@ -2,14 +2,14 @@ After genesis, you can still join the network as a user and become a validator through self-bonding. -After [joining the network as a full node](../../operators/ledger/running-a-full-node.md), you must [create a validator account](../../operators/validators/post-genesis-validator-setup.md). +After [joining the network as a full node](../../operators/ledger/running-a-full-node.mdx), you must [create a validator account](../../operators/validators/post-genesis-validator-setup.mdx). After this has been completed, you will need to increase your validator's `bonded-stake`, which can be done by self-bonding tokens sourced from the faucet. ## Bonding -Follow [this guide](../../operators/validators/staking.md#self-bonding) on how to self-bond a validator's tokens. +Follow [this guide](../../operators/validators/staking.mdx#self-bonding) on how to self-bond a validator's tokens. ## Check bonded-stake In order to vote on blocks, a validator must have enough `bonded-stake` to be included in the validators "consensus-set". A validator is in the consensus set if and only if it has enough `bonded-stake` to be in the top 128 validators by `bonded-stake`. diff --git a/packages/docs/pages/networks/testnets/pre-genesis.mdx b/packages/docs/pages/networks/testnets/pre-genesis.mdx index 5b205837..76692fc4 100644 --- a/packages/docs/pages/networks/testnets/pre-genesis.mdx +++ b/packages/docs/pages/networks/testnets/pre-genesis.mdx @@ -4,6 +4,6 @@ Pre-genesis is defined as "before" the first (a.k.a genesis) block. At genesis, there will be a set of validators with a pre-defined amount of tokens (described in the genesis file). For testnets, it is possible to apply to become a pre-genesis validator. -In order to do so, please follow [these steps](./genesis-validator-apply.md). +In order to do so, please follow [these steps](./genesis-validator-apply.mdx). -If the testnet is already running and you have not been selected as a pre-genesis validator, please follow the steps for [joining as a full node](../../ledger/running-a-full-node.md). If you still wish to validate, you can follow the steps to [become a post-genesis-validator](./post-genesis-validator.md). +If the testnet is already running and you have not been selected as a pre-genesis validator, please follow the steps for [joining as a full node](../../ledger/running-a-full-node.mdx). If you still wish to validate, you can follow the steps to [become a post-genesis-validator](./post-genesis-validator.mdx). diff --git a/packages/docs/pages/networks/testnets/testnet-history.mdx b/packages/docs/pages/networks/testnets/testnet-history.mdx index 9c39bd3a..6775f81f 100644 --- a/packages/docs/pages/networks/testnets/testnet-history.mdx +++ b/packages/docs/pages/networks/testnets/testnet-history.mdx @@ -165,7 +165,7 @@ cd namada export NAMADA_TAG=v0.13.4 make build-release ``` -3. Copy the new binaries to path. More in depth instructions can be found at [here](./environment-setup.md) +3. Copy the new binaries to path. More in depth instructions can be found at [here](./environment-setup.mdx) 4. Once this has been completed, **the node must tesync from genesis** (see below) **How to resync from genesis:** @@ -178,7 +178,7 @@ mkdir backup-pregenesis && cp -r .namada/pre-genesis backup-pregenesis/ rm -r .namada/public-testnet-3.0.81edd4d6eb6 rm .namada/public-testnet-3.0.81edd4d6eb6.toml ``` -WARNING: Do not delete the entire `.namada` folder, as it contains your pre-genesis keys. If this is accidentally done, you will have to copy over the backup-pregenesis file. See [these instructions](../../validators/run-your-genesis-validator.md) for more details +WARNING: Do not delete the entire `.namada` folder, as it contains your pre-genesis keys. If this is accidentally done, you will have to copy over the backup-pregenesis file. See [these instructions](../../validators/run-your-genesis-validator.mdx) for more details 3. Rejoin the network ```bash copy export CHAIN_ID="public-testnet-3.0.81edd4d6eb6" @@ -206,7 +206,7 @@ A patch was released [v0.13.3](https://github.com/anoma/namada/releases/tag/v0.1 ***23/01/2023*** -A new testnet was released before the fortnightly testnet release schedule due to the below hardfork not working as intended. Follow the steps in [setting up a new testnet](./environment-setup.md) +A new testnet was released before the fortnightly testnet release schedule due to the below hardfork not working as intended. Follow the steps in [setting up a new testnet](./environment-setup.mdx) ### Hardfork v0.13.1 diff --git a/packages/docs/pages/operators/ledger.mdx b/packages/docs/pages/operators/ledger.mdx index 948af7c0..7d39464f 100644 --- a/packages/docs/pages/operators/ledger.mdx +++ b/packages/docs/pages/operators/ledger.mdx @@ -15,7 +15,7 @@ namada ledger The node will attempt to connect to the persistent validator nodes and other peers in the network, and synchronize to the latest block. -By default, the ledger will store its configuration and state in your [base directory](./ledger/base-directory.md). +By default, the ledger will store its configuration and state in your [base directory](./ledger/base-directory.mdx). You can use the `--base-dir` CLI global argument or `BASE_DIR` environment variable to change it. Assuming you do not have a custom base_dir, you can export the BASE_DIR environment variable as follows: @@ -32,12 +32,12 @@ The ledger will also download the genesis block, which contains the initial stat The ledger also needs access to the built WASM files that are used in the genesis block. These files are included in release and shouldn't be modified, otherwise your node will fail with a consensus error on the genesis block. By default, these are expected to be in the `wasm` directory inside the chain directory that's in the base directory, i.e `$BASE_DIR/$CHAIN_ID/wasm`. -The wasm directory can also be set with the `--wasm-dir` CLI global argument, `NAMADA_WASM_DIR` [environment variable](./ledger/env-vars.md) or the configuration file. +The wasm directory can also be set with the `--wasm-dir` CLI global argument, `NAMADA_WASM_DIR` [environment variable](./ledger/env-vars.mdx) or the configuration file. ### Ledger configuration The ledger configuration is stored in `$BASE_DIR/$CHAIN_ID/config.toml` (with default `--base-dir`). It is created when you join the network. You can modify that file to change the configuration of your node. All values can also be set -via [environment variables](./ledger/env-vars.md). +via [environment variables](./ledger/env-vars.mdx). diff --git a/packages/docs/pages/operators/local-network.mdx b/packages/docs/pages/operators/local-network.mdx index d55dc2f1..c4c3eafa 100644 --- a/packages/docs/pages/operators/local-network.mdx +++ b/packages/docs/pages/operators/local-network.mdx @@ -4,7 +4,7 @@ import Expandable from "../../components/Expandable"; ## Prerequisites -Namada must be installed [from source](../introduction/install/source.md) in order to run a local network. +Namada must be installed [from source](../introduction/install/source.mdx) in order to run a local network. There is a script that has been written specifically for this purpose, which can be found under `scripts` in the [Namada repository](https://github.com/anoma/namada). diff --git a/packages/docs/pages/operators/validators.mdx b/packages/docs/pages/operators/validators.mdx index 6fd8d3ab..5e2bebd5 100644 --- a/packages/docs/pages/operators/validators.mdx +++ b/packages/docs/pages/operators/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.mdx). #### 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.mdx). -See these steps for [setting up a post-genesis validator](./validators/post-genesis-validator-setup.md). \ No newline at end of file +See these steps for [setting up a post-genesis validator](./validators/post-genesis-validator-setup.mdx). \ No newline at end of file diff --git a/packages/docs/pages/operators/validators/genesis-validator-setup.mdx b/packages/docs/pages/operators/validators/genesis-validator-setup.mdx index 44a7da50..460d31a1 100644 --- a/packages/docs/pages/operators/validators/genesis-validator-setup.mdx +++ b/packages/docs/pages/operators/validators/genesis-validator-setup.mdx @@ -6,7 +6,7 @@ A genesis validator is one which is a validator right from the first block of th ### Prerequisites -- a machine that meets the [requirements](./hardware.md) for running a validator node +- a machine that meets the [requirements](./hardware.mdx) for running a validator node - an associated public IPv4 address with ports 26656 reachable from anywhere for P2P connections ## Pre-genesis diff --git a/packages/docs/pages/operators/validators/post-genesis-validator-setup.mdx b/packages/docs/pages/operators/validators/post-genesis-validator-setup.mdx index db058672..0f045183 100644 --- a/packages/docs/pages/operators/validators/post-genesis-validator-setup.mdx +++ b/packages/docs/pages/operators/validators/post-genesis-validator-setup.mdx @@ -52,5 +52,5 @@ Note that the balance of NAM tokens that is in your validator account does not c namada client balance --owner my-validator --token NAM ``` -That is, the balance of your account's address is a regular liquid balance that you can transfer using your validator account key, depending on the rules of the validator account's validity predicate. The default validity predicate allows you to transfer it with a signed transaction and/or stake it in the PoS system. Therefore, in order to increase the voting power of your validator, you need to accrue [some stake](./staking.md). +That is, the balance of your account's address is a regular liquid balance that you can transfer using your validator account key, depending on the rules of the validator account's validity predicate. The default validity predicate allows you to transfer it with a signed transaction and/or stake it in the PoS system. Therefore, in order to increase the voting power of your validator, you need to accrue [some stake](./staking.mdx). diff --git a/packages/docs/pages/users.mdx b/packages/docs/pages/users.mdx index c4fc2112..94d79bad 100644 --- a/packages/docs/pages/users.mdx +++ b/packages/docs/pages/users.mdx @@ -10,5 +10,4 @@ This guide is tailored towards users who are interested in using Namada to its m - [Delegating on Namada](./users/delegators.mdx) - [Governance and Public Goods Funding](./users/governance.mdx) - [Using the Namada wallet](./users/wallet.mdx) -- [Experimental Features](./users/experimental.mdx) diff --git a/packages/docs/pages/users/delegators.mdx b/packages/docs/pages/users/delegators.mdx index dd03aa58..a16e575e 100644 --- a/packages/docs/pages/users/delegators.mdx +++ b/packages/docs/pages/users/delegators.mdx @@ -10,11 +10,11 @@ All accounts on Namada with any amount of *bonded* NAM, is by definition, either > A delegate is an account that has been bonded to by a delegator. ## Becoming a delegator -In order to become a delegator, you must first have an account with positive NAM balance. If you do not have an account, you can follow the instructions [here](../users/an-introduction-to-namada-addresses.md) to create one. +In order to become a delegator, you must first have an account with positive NAM balance. If you do not have an account, you can follow the instructions [here](./transparent-accounts.mdx) to create one. Once you have an account, you can bond your NAM to a delegate. At the time of writing, the only possible delegates are validators. In future Namada versions, there will be the option to delegate to other, non-validating accounts as well. -Delegating to a validator is the same as [staking with a validator](../validators/staking.md). +Delegating to a validator is the same as [staking with a validator](../operators/validators/staking.mdx). First, you may want to list the available validators you can stake to: @@ -34,4 +34,4 @@ If you have the alias saved in your wallet, you can also pass ` Redelegating is the process of changing the delegate you have bonded to. This process takes 4 epochs, after which your NAM will be redelegated. ## Unbonding -Unbonding is the process of removing your bonded NAM from a delegate. This process is identical to [unbonding tokens from a validator](../validators/staking.md#unbonding). +Unbonding is the process of removing your bonded NAM from a delegate. This process is identical to [unbonding tokens from a validator](../operators/validators/staking.mdx#unbonding). diff --git a/packages/docs/pages/users/fees.mdx b/packages/docs/pages/users/fees.mdx index e1c44ee9..9ecd1697 100644 --- a/packages/docs/pages/users/fees.mdx +++ b/packages/docs/pages/users/fees.mdx @@ -31,7 +31,7 @@ namada client transfer \ (Assuming that `keysha2` exists and is in the wallet of the user) -For testnet purposes, we recommend [using the faucet](../networks/testnets/pow.md) to source NAM for transaction fees. +For testnet purposes, we recommend [using the faucet](../networks/testnets/pow.mdx) to source NAM for transaction fees. ## How fees are calculated The fee for a transaction is calculated by multiplying `gas-limit` by the gas price. diff --git a/packages/docs/pages/users/governance.mdx b/packages/docs/pages/users/governance.mdx index 30995c71..e48ef2ba 100644 --- a/packages/docs/pages/users/governance.mdx +++ b/packages/docs/pages/users/governance.mdx @@ -4,5 +4,5 @@ The Namada governance mechanism gives users the possibility to upgrade the proto There are two different mechanism to create a proposal: -- [On-chain proposals](./governance/on-chain-governance.md): 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.md) +- [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) diff --git a/packages/docs/pages/users/governance/public-goods-stewards.mdx b/packages/docs/pages/users/governance/public-goods-stewards.mdx index 70f8eb9c..a274385f 100644 --- a/packages/docs/pages/users/governance/public-goods-stewards.mdx +++ b/packages/docs/pages/users/governance/public-goods-stewards.mdx @@ -1,5 +1,5 @@ # Public Goods Stewards Documentation -The funding of public goods on Namada is conducted through an entity called the "public goods stewards". Each public goods steward is a [multisignature account](./users/multisignature.mdx). +The funding of public goods on Namada is conducted through an entity called the "public goods stewards". Each public goods steward is a [multisignature account](../transparent-accounts/multisignature.mdx). Each steward is elected by governance through separate governance proposals. @@ -7,6 +7,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](./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 proposals](./public-goods-stewards/voting.md#voting-for-pgf-proposals). \ No newline at end of file +1. [How to become a public goods steward](./public-goods-stewards/electing.mdx). +2. [How to submit a public goods funding proposal](./public-goods-stewards/proposing.mdx) +3. [How to vote on steward elections](./public-goods-stewards/voting.mdx#voting-for-stewards) as well as [public goods funding proposals](./public-goods-stewards/voting.mdx#voting-for-pgf-proposals). \ No newline at end of file diff --git a/packages/docs/pages/users/governance/public-goods-stewards/electing.mdx b/packages/docs/pages/users/governance/public-goods-stewards/electing.mdx index 1aab16dd..a1bb04d8 100644 --- a/packages/docs/pages/users/governance/public-goods-stewards/electing.mdx +++ b/packages/docs/pages/users/governance/public-goods-stewards/electing.mdx @@ -70,6 +70,6 @@ where `` is the path to the `steward_proposal.jso ### Becoming elected -Once the proposal is submitted, it will be voted on by the community (see [voting](./voting.md)). If the proposal passes, the account will become a steward. If the proposal fails, the account will not become a steward. +Once the proposal is submitted, it will be voted on by the community (see [voting](./voting.mdx)). If the proposal passes, the account will become a steward. If the proposal fails, the account will not become a steward. -Once a multisignature account becomes elected (which will happen at the end of the `grace_epoch`), it will be able to submit proposals to the public goods funding pool (see [submitting proposals](./proposing.md#proposing-funding). +Once a multisignature account becomes elected (which will happen at the end of the `grace_epoch`), it will be able to submit proposals to the public goods funding pool (see [submitting proposals](./proposing.mdx#proposing-funding)). diff --git a/packages/docs/pages/users/shielded-accounts/shielded-rewards.mdx b/packages/docs/pages/users/shielded-accounts/shielded-rewards.mdx index c229046f..73600601 100644 --- a/packages/docs/pages/users/shielded-accounts/shielded-rewards.mdx +++ b/packages/docs/pages/users/shielded-accounts/shielded-rewards.mdx @@ -2,4 +2,4 @@ Shielded rewards are distributed to all users in the shielded set. Users are rewared `NAM` tokens for each epoch their incentivised assets are in the shielded set. Informally, the amount of `NAM` rewarded for a specific asset is proportional to the amount of that asset in the shielded pool. Each asset has a "reward rate" specified by governance, which sets the constant of proportionality for that asset. -The interested reader should consult [the specs](https://specs.namada.net) for a more precise explanation of how the reward is calculated. \ No newline at end of file +The interested reader should consult [the specs](https://specs.namada.net/economics/proof-of-stake) for a more precise explanation of how the reward is calculated. \ No newline at end of file diff --git a/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx b/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx index 09c3ba4b..fd6f6924 100644 --- a/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx +++ b/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx @@ -19,12 +19,12 @@ We distinguish two kinds of keys: ### Shielding transfers -To try out shielded transfers, you first need to be in possession of a +To conduct a shielding transfer, the user must first be in possession of a transparent account with some token balance. #### Generate your Spending Key -You can randomly generate a new Spending Key with: +One can randomly generate a new spending key with: ```shell copy namadaw masp gen-key --alias @@ -37,7 +37,7 @@ the same alias. #### Create a new payment address -To create a payment address from your Spending key, use: +To create a payment address from one's spending key, one can run: ```shell copy namadaw masp gen-addr \ @@ -46,15 +46,15 @@ namadaw masp gen-addr \ ``` -This command will generate a different payment address each time you run it. -Payment addresses can be reused or discarded as you like, and any relationship -between addresses cannot be deciphered by any user without the spending key. +This command will generate a different payment address each time the user runs the command. +Payment addresses can be reused or discarded as the user likes, and any relationship +between addresses cannot be deciphered by any other user without the spending key. #### Send your shielding transfer -Once you have a payment address, transfer a balance from your -transparent account to your shielded account with something like: +Once one has a payment address, one can transfer a balance from their +transparent account to their shielded account with: ```shell copy namadac transfer \ @@ -64,9 +64,9 @@ namadac transfer \ --amount ``` -#### View your balance +#### View one's balance -Once this transfer has been broadcasted, validated, and executed on the blockchain, you can view your Spending Key's +Once this transfer has been broadcasted, validated, and executed on the blockchain, one can view their spending key's balance: ```shell copy @@ -75,7 +75,7 @@ namadac balance --owner ### Shielded transfers -Now that you have a shielded balance, it can be transferred to a +Once the user has a shielded balance, it can be transferred to a another shielded address: ```shell copy @@ -89,7 +89,7 @@ namadac transfer \ ### Unshielding transfers -You can also transfer back your balance to a transparent account: +It is also possible to transfer the balance to a transparent account: ```shell copy namadac transfer \ diff --git a/packages/docs/pages/users/transparent-accounts.mdx b/packages/docs/pages/users/transparent-accounts.mdx index 1967a7f9..762aedaa 100644 --- a/packages/docs/pages/users/transparent-accounts.mdx +++ b/packages/docs/pages/users/transparent-accounts.mdx @@ -6,7 +6,7 @@ All accounts in Namada have a unique address, exactly one Validity Predicate and There are currently 3 types of account addresses: - **Implicit *(not fully supported yet)*:** An implicit account is derived from your keypair and can be used to authorize certain transactions from the account. They can be used as recipients of transactions even if the account has not been used on-chain before. -- **Established:** Used for accounts that allow the deployment of custom validation logic. These must be created on-chain via a transaction (e.g., [account initialization](./send-and-receive-nam-tokens.md#initialize-an-established-account)). The address is generated on-chain and is not known until the transaction is applied (the user provides randomness). +- **Established:** Used for accounts that allow the deployment of custom validation logic. These must be created on-chain via a transaction (e.g., [account initialization](./transparent-accounts/send-and-receive-nam-tokens.mdx#initialize-an-established-account)). The address is generated on-chain and is not known until the transaction is applied (the user provides randomness). - **Internal:** Special internal accounts, such as protocol parameters account, PoS and IBC. ## Manage keypairs diff --git a/packages/docs/pages/users/transparent-accounts/send-and-receive-nam-tokens.mdx b/packages/docs/pages/users/transparent-accounts/send-and-receive-nam-tokens.mdx index 7c1e1c03..28bce628 100644 --- a/packages/docs/pages/users/transparent-accounts/send-and-receive-nam-tokens.mdx +++ b/packages/docs/pages/users/transparent-accounts/send-and-receive-nam-tokens.mdx @@ -7,7 +7,7 @@ The validity predicate (VP) checks, in particular, that the total supply (of the ### Initialize an established account -If you already have a key in your wallet, you can skip this step. Otherwise, [generate a new keypair](./an-introduction-to-namada-addresses.md#generate-a-keypair) now. +If you already have a key in your wallet, you can skip this step. Otherwise, [generate a new keypair](../transparent-accounts.mdx#generate-a-keypair) now. Then, send a transaction to initialize your new established account and save its address with the alias `establishment`. The `keysha` public key will be written into the account's storage for authorizing future transactions. We also sign this transaction with `keysha`. diff --git a/packages/docs/pages/users/wallet.mdx b/packages/docs/pages/users/wallet.mdx index 8f1d0828..2c7b7ea8 100644 --- a/packages/docs/pages/users/wallet.mdx +++ b/packages/docs/pages/users/wallet.mdx @@ -1,6 +1,6 @@ # Namada Wallet Guide -This document describes the different wallet concepts and options that are available to users of Namada who want to be able to [send, receive and interact](../users/send-and-receive-nam-tokens.md) with NAM tokens on the Namada blockchain. +This document describes the different wallet concepts and options that are available to users of Namada who want to be able to [send, receive and interact](./transparent-accounts/send-and-receive-nam-tokens.mdx) with NAM tokens on the Namada blockchain. ## A brief introduction to the Namada wallet The purpose of the Namada wallet is to provide a user-interface to store and manage both keys and addresses. @@ -8,12 +8,12 @@ The purpose of the Namada wallet is to provide a user-interface to store and man The wallet simply "remembers" these very large numbers on your behalf. Keys are the fundamental building blocks for accounts on Namada. Keys come in the form of *pairs* (of secret and public key), and can be used to derive the **account address** (first 40 chars of the SHA256 hash of the public key). -To read more about addresses see [An introduction to Namada addresses](../users/an-introduction-to-namada-addresses.md). +To read more about addresses see [An introduction to Namada addresses](./transparent-accounts.mdx). ## The wallet options on Namada Check out the different options to generate a wallet: -- [File System Wallet](./wallet/file-system-wallet.md) -- [Web Wallet](./wallet/web-wallet.md) -- [Hardware Wallet](./wallet/hardware-wallet.md) +- [File System Wallet](./wallet/file-system-wallet.mdx) +- [Web Wallet](./wallet/web-wallet.mdx) +- [Hardware Wallet](./wallet/hardware-wallet.mdx) diff --git a/packages/docs/pages/users/wallet/hardware-wallet.mdx b/packages/docs/pages/users/wallet/hardware-wallet.mdx index 83494db0..4696c5d1 100644 --- a/packages/docs/pages/users/wallet/hardware-wallet.mdx +++ b/packages/docs/pages/users/wallet/hardware-wallet.mdx @@ -7,7 +7,7 @@ A ledger device with the latest firmware installed. You can find instructions on Install the javascript npm package [here](https://www.npmjs.com/package/@zondax/ledger-namada). -In order to use the ledger with the web wallet, you will need to install the [Namada Web Wallet](./web-wallet.md#install). +In order to use the ledger with the web wallet, you will need to install the [Namada Web Wallet](./web-wallet.mdx#install). ### Connecting your Ledger 1. Open the Namada web extension. @@ -19,4 +19,4 @@ In order to use the ledger with the web wallet, you will need to install the [Na 7. You can now close the information window and use the ledger to sign transactions. ### Sending transactions with the ledger -See the [web wallet](./web-wallet.md#sending-transactions) guide for instructions on how to send transactions with the web wallet. +See the [web wallet](./web-wallet.mdx#sending-transactions) guide for instructions on how to send transactions with the web wallet. diff --git a/packages/docs/pages/users/wallet/web-wallet.mdx b/packages/docs/pages/users/wallet/web-wallet.mdx index 388be82e..9f9df44a 100644 --- a/packages/docs/pages/users/wallet/web-wallet.mdx +++ b/packages/docs/pages/users/wallet/web-wallet.mdx @@ -6,9 +6,9 @@ When Namada is in `mainnet`, the web wallet will be available in most browser ex ### Installing from source (for development and experiment purposes) #### Connect to a testnet or run a local node -1. Follow the instructions for the [testnets](../../networks/testnets.md) to connect to a testnet or set up a local node using [docker](../introduction/install/docker.md). +1. Follow the instructions for the [testnets](../../networks/testnets.mdx) to connect to a testnet or set up a local node using [docker](../introduction/install/docker.mdx). 2. Figure out where the base directory is stored and save its location as a variable such as `export BASE_DIR=`. - You can follow [these docs](../../networks/testnets/migrating-testnets.md#after-v0153) to save this variable. Go ahead and save the chain id as a variable as well. You can find the chain id by running `cat $BASE_DIR/global-config.toml`. Save this chain-id to the variable `export CHAIN_ID=`. + You can follow [these docs](../../networks/testnets/migrating-testnets.mdx#after-v0153) to save this variable. Go ahead and save the chain id as a variable as well. You can find the chain id by running `cat $BASE_DIR/global-config.toml`. Save this chain-id to the variable `export CHAIN_ID=`. 3. You will need to edit the CometBFT config in order to allow the web wallet to connect to your node. The CometBFT config will be located in `$BASE_DIR/$CHAIN_ID/cometbft/config/config.toml`. You will need to change the `cors_allowed_origins` field to `["*"]`. You can do this by running ```shell copy diff --git a/packages/specs/pages/base-ledger.mdx b/packages/specs/pages/base-ledger.mdx index f58a4288..13eebfb1 100644 --- a/packages/specs/pages/base-ledger.mdx +++ b/packages/specs/pages/base-ledger.mdx @@ -1,6 +1,6 @@ # Base ledger -The base ledger of Namada includes a [consensus mechanism](./base-ledger/consensus.md) and a validity-predicate based [execution system](./base-ledger/execution.md). +The base ledger of Namada includes a [consensus mechanism](./base-ledger/consensus.mdx) and a validity-predicate based [execution system](./base-ledger/execution.mdx). ## Consensus The consensus mechanism on Namada provides an algorithmic way for validators to communicate votes and collectively agree on a consistent state. The algorithm, coupled with a cryptoeconomic voting power allocation mechanism called "proof of stake", is designed so that that non-colluding validators acting in their (economic) self interest will follow the consensus algorithm in a predictable manner. @@ -9,4 +9,4 @@ The consensus mechanism on Namada provides an algorithmic way for validators to The validity-predicate based execution mechanism is inherited from the architectural design philosophy of Anoma. The fundamental idea is that a "valid state" is defined as that which satisfies a set of boolean conditions. These boolean conditions are encoded by functional "validity predicates", which are invoked whenever a state is being proposed. If all validity predicates in the system return the boolean `true`, this defines a valid state which validators can vote on. The validity predicate based mechanism differs from the traditional "smart-contract" based execution model, where a valid state is instead defined as that which results from a series of pre-defined valid execution steps. These execution steps are defined within the smart contract, and verifying the validity of the new state requires *each* validator to run the series of execution steps. ## Replay protection & block space allocator -In addition to describing the execuction model and consensus, this section also documents Namada's [replay protection system](./base-ledger/replay-protection.md), and [block space allocator](./base-ledger/block-space-allocator.md). +In addition to describing the execuction model and consensus, this section also documents Namada's [replay protection system](./base-ledger/replay-protection.mdx), and [block space allocator](./base-ledger/block-space-allocator.mdx). diff --git a/packages/specs/pages/base-ledger/block-space-allocator.mdx b/packages/specs/pages/base-ledger/block-space-allocator.mdx index 3410cabe..eaa8ce4d 100644 --- a/packages/specs/pages/base-ledger/block-space-allocator.mdx +++ b/packages/specs/pages/base-ledger/block-space-allocator.mdx @@ -200,7 +200,7 @@ signatures on a single validator set update. "Chunks" of a proof (i.e. individual votes) are decided and batched together, until a complete proof is constructed. -Validator set updates are covered in more detail in [the Ethereum bridge section](../interoperability/ethereum-bridge.md). +Validator set updates are covered in more detail in [the Ethereum bridge section](../interoperability/ethereum-bridge.mdx). ## Governance diff --git a/packages/specs/pages/base-ledger/fungible-token.mdx b/packages/specs/pages/base-ledger/fungible-token.mdx index 63112eb7..3dc31b69 100644 --- a/packages/specs/pages/base-ledger/fungible-token.mdx +++ b/packages/specs/pages/base-ledger/fungible-token.mdx @@ -6,7 +6,7 @@ The fungible token validity predicate authorises token balance changes on the ba A token balance is stored with a storage key. The token balance key should be `#Multitoken/{token_addr}/balance/{owner_addr}`. These keys can be made with [token functions](https://github.com/anoma/namada/blob/5da82f093f10c0381865accba99f60c557360c51/core/src/types/token.rs). -We can have multitoken balances for the same owner by `{token_addr}`, e.g. a token received over IBC is managed in `#Multitoken/{ibc_token}/balance/{receiver_addr}`. It is distinguished from the receiver's original balance in `#Multitoken/{token_addr}/balance/{receiver_addr}` to know which chain the token was transferred from. The `{ibc_token}` is explained in [IBC](../interoperability/ibc.md). +We can have multitoken balances for the same owner by `{token_addr}`, e.g. a token received over IBC is managed in `#Multitoken/{ibc_token}/balance/{receiver_addr}`. It is distinguished from the receiver's original balance in `#Multitoken/{token_addr}/balance/{receiver_addr}` to know which chain the token was transferred from. The `{ibc_token}` is explained in [IBC](../interoperability/ibc.mdx). Transfers between the balances with the same `{token_addr}` are allowed. Specifically, we can transfer a token from `#Multitoken/{token_addr}/balance/{sender_addr}` to `#Multitoken/{token_addr}/balance/{receiver_addr}`. diff --git a/packages/specs/pages/base-ledger/replay-protection.mdx b/packages/specs/pages/base-ledger/replay-protection.mdx index 67483adc..ae16578d 100644 --- a/packages/specs/pages/base-ledger/replay-protection.mdx +++ b/packages/specs/pages/base-ledger/replay-protection.mdx @@ -32,7 +32,7 @@ This section illustrates the pre-existing context in the replay protection mecha The current implementation of Namada is built on top of CometBFT which provides an encrypted and authenticated communication channel between every two nodes to prevent a _man-in-the-middle_ attack (see the detailed {/* TODO: Fix link to be cometbft is possible*/} -[spec](https://github.com/cometbft/cometbft/blob/main/spec/p2p/legacy-docs/peer.md)). +[spec](https://github.com/cometbft/cometbft/blob/main/spec/p2p/legacy-docs/peer.mdx)). The Namada protocol relies on this substrate to exchange transactions (messages) that defines the state transition of the ledger. More specifically, a @@ -67,7 +67,7 @@ pub struct Tx { ``` The wrapper transaction is composed of some metadata, an optional unshielding tx -for fee payment (see [fee specs](../economics/fee-system.md)), the encrypted +for fee payment (see [fee specs](../economics/fee-system.mdx)), the encrypted inner transaction itself and the hash of the concatenation of these values. {/* TODO: Ensure that the hash of concatentation statement is as accurate as possible. It could be values, it could be the object (which consists of keys + values)*/} The inner `Tx` transaction carries the Wasm code to be executed and the associated data. @@ -100,7 +100,7 @@ the execution steps: The transaction data is effectively prevented from being tampered with by the signature checks, since any such tampering would cause the checks to fail and the transaction to be rejected. For a more in-depth view, please refer to the -[Namada execution spec](./execution.md). +[Namada execution spec](./execution.mdx). ### CometBFT replay protection @@ -123,7 +123,7 @@ semantics of the state transition. This inner transaction must be protected from `WrapperTx` is the only type of transaction currently accepted by the ledger. It must be protected from replay attacks; otherwise, a malicious user could replay the transaction as is. Even if the inner transaction implemented replay protection or was not accepted for any reason, the signer of the wrapper would still incur gas and fees, resulting in economic damage. To prevent the replay of both these transactions, reliance is placed on a set of digests from already processed transactions that are kept in storage. These digests are computed on the **unsigned** transactions, to support replay -protection even for [multisigned](multisignature.md) transactions. In this case, using hashes from the signed transactions would result in a different hash for a different set of signatures on the same transaction, allowing for a replay. To achieve this, the `WrapperTx` hash field contains the hash of the unsigned inner transaction, instead of the signed one. This change does not impact the overall safety of Namada, as the wrapper is still signed over all its bytes, including the inner signature. The modification also allows for early replay attack checks in the mempool and during wrapper block-inclusion. +protection even for [multisigned](multisignature.mdx) transactions. In this case, using hashes from the signed transactions would result in a different hash for a different set of signatures on the same transaction, allowing for a replay. To achieve this, the `WrapperTx` hash field contains the hash of the unsigned inner transaction, instead of the signed one. This change does not impact the overall safety of Namada, as the wrapper is still signed over all its bytes, including the inner signature. The modification also allows for early replay attack checks in the mempool and during wrapper block-inclusion. In addition, a subspace in storage is required, headed by a `ReplayProtection` internal address: ``` bash @@ -178,7 +178,7 @@ the attack explained in this section is performed: #### Governance proposals -Governance [proposals](../base-ledger/governance.md) may carry some wasm code to +Governance [proposals](../base-ledger/governance.mdx) may carry some wasm code to be executed in case the proposal passed. This code is embedded into a `DecryptedTx` directly by the validators at block processing time and is not inserted into the block itself. @@ -264,7 +264,7 @@ In mempool_validation, several checks are performed on the wrapper transaction t - Unshielding transaction (if present) releases the minimum required tokens for fee payment - Successful execution of the unshielding transaction (if present) -More details about gas, fees, and the unshielding transaction can be found in the [fee specs](../economics/fee-system.md). +More details about gas, fees, and the unshielding transaction can be found in the [fee specs](../economics/fee-system.mdx). These checks can all be conducted before executing the transactions themselves. If any of these checks fail, the transaction is considered invalid, and the appropriate action is taken: diff --git a/packages/specs/pages/base-ledger/replay-protection/optimizations.mdx b/packages/specs/pages/base-ledger/replay-protection/optimizations.mdx index 69721852..ddc0573b 100644 --- a/packages/specs/pages/base-ledger/replay-protection/optimizations.mdx +++ b/packages/specs/pages/base-ledger/replay-protection/optimizations.mdx @@ -69,7 +69,7 @@ these conditions doesn't hold the VP will discard the transactions and prevent the changes from being applied to the storage. In the specific case of a shielded transfer, since MASP already comes with -replay protection as part of the Zcash design (see the [MASP specs](../masp.md) +replay protection as part of the Zcash design (see the [MASP specs](../masp.mdx) and [Zcash protocol specs](https://zips.z.cash/protocol/protocol.pdf)), the counter in `SignedTxData` is not required and therefore should be optional. @@ -486,9 +486,9 @@ validate it. These will involve: - Valid signature - `GasLimit` is below the block gas limit (see the - [fee specs](../economics/fee-system.md) for more details) + [fee specs](../economics/fee-system.mdx) for more details) - `Fees` are paid with an accepted token and match the minimum amount required - (see the [fee specs](../economics/fee-system.md) for more details) + (see the [fee specs](../economics/fee-system.mdx) for more details) - Valid chainId - Valid transaction counter - Valid expiration diff --git a/packages/specs/pages/economics.mdx b/packages/specs/pages/economics.mdx index f18c7d70..e9586e58 100644 --- a/packages/specs/pages/economics.mdx +++ b/packages/specs/pages/economics.mdx @@ -1,3 +1,3 @@ ## Economics -Namada users pay transaction fees in NAM and other tokens (see [fee system](./economics/fee-system.md) and [governance](./base-ledger/governance.md)), so demand for NAM can be expected to track demand for block space. On the supply side, the protocol mints NAM at a fixed maximum per-annum rate based on a fraction of the current supply (see [inflation system](./economics/inflation-system.md)), which is directed to three areas of protocol subsidy: [proof-of-stake](./economics/proof-of-stake.md), [shielded pool incentives](./economics/shielded-pool-incentives.md), and [public-goods funding](./economics/public-goods-funding.md). Inflation rates for these three areas are adjusted independently (the first two on PD controllers and the third based on funding decisions) and excess tokens are slowly burned. \ No newline at end of file +Namada users pay transaction fees in NAM and other tokens (see [fee system](./economics/fee-system.mdx) and [governance](./base-ledger/governance.mdx)), so demand for NAM can be expected to track demand for block space. On the supply side, the protocol mints NAM at a fixed maximum per-annum rate based on a fraction of the current supply (see [inflation system](./economics/inflation-system.mdx)), which is directed to three areas of protocol subsidy: [proof-of-stake](./economics/proof-of-stake.mdx), [shielded pool incentives](./economics/shielded-pool-incentives.mdx), and [public-goods funding](./economics/public-goods-funding.mdx). Inflation rates for these three areas are adjusted independently (the first two on PD controllers and the third based on funding decisions) and excess tokens are slowly burned. \ No newline at end of file diff --git a/packages/specs/pages/economics/fee-system.mdx b/packages/specs/pages/economics/fee-system.mdx index e60db548..f06ec5e9 100644 --- a/packages/specs/pages/economics/fee-system.mdx +++ b/packages/specs/pages/economics/fee-system.mdx @@ -30,7 +30,7 @@ transaction itself. Since fees have a purpose in allocating scarce block resources (space and gas limit) they have to be paid upfront, as soon as the transaction is deemed valid and accepted into a block (refer to -[replay protection specs](../base-ledger/replay-protection.md) for more details +[replay protection specs](../base-ledger/replay-protection.mdx) for more details on transactions' validity). Moreover, for the same reasons, the fee payer will pay for the entire `GasLimit` allocated and not the actual gas consumed for the transaction: this will incentivize fee payers to stick to a reasonable gas limit @@ -229,7 +229,7 @@ transactions involving the same addresses. ### Governance proposals -Governance [proposals](../base-ledger/governance.md) may carry some wasm code to +Governance [proposals](../base-ledger/governance.mdx) may carry some wasm code to be executed in case the proposal passed. This code is embedded into a `DecryptedTx` directly by the validators at block processing time and is not inserted into the block itself. These transactions are exempt from fees and diff --git a/packages/specs/pages/economics/inflation-system.mdx b/packages/specs/pages/economics/inflation-system.mdx index 931beab7..012f782c 100644 --- a/packages/specs/pages/economics/inflation-system.mdx +++ b/packages/specs/pages/economics/inflation-system.mdx @@ -4,15 +4,15 @@ The Namada protocol controls the Namada token NAM (the native staking token), wh ### Proof-of-stake rewards -The security of the proof-of-stake voting power allocation mechanism used by Namada is dependent in part upon locking (bonding) tokens to validators, where these tokens can be slashed should the validators misbehave. Funds so locked are only able to be withdrawn after an unbonding period. In order to reward validators and delegators for locking their stake and participating in the consensus mechanism, Namada pays a variable amount of inflation to all delegators and validators. The amount of inflation paid is varied on a PD-controller in order to target a particular bonding ratio (fraction of the NAM token being locked in proof-of-stake). Namada targets a bonding ratio of 2/3, paying up to 10% inflation per annum to proof-of-stake rewards. See [reward distribution mechanism](./proof-of-stake/reward-distribution.md) for details. +The security of the proof-of-stake voting power allocation mechanism used by Namada is dependent in part upon locking (bonding) tokens to validators, where these tokens can be slashed should the validators misbehave. Funds so locked are only able to be withdrawn after an unbonding period. In order to reward validators and delegators for locking their stake and participating in the consensus mechanism, Namada pays a variable amount of inflation to all delegators and validators. The amount of inflation paid is varied on a PD-controller in order to target a particular bonding ratio (fraction of the NAM token being locked in proof-of-stake). Namada targets a bonding ratio of 2/3, paying up to 10% inflation per annum to proof-of-stake rewards. See [reward distribution mechanism](./proof-of-stake/reward-distribution.mdx) for details. ### Shielded pool rewards -Privacy provided by the MASP in practice depends on how many users use the shielded pool and what assets they use it with. To increase the likelihood of a sizeable privacy set, Namada pays a variable portion of inflation, up to 10% per annum, to shielded pool incentives, which are allocated on a per-asset basis by a PD-controller targeting specific amounts of each asset being locked in the shielded pool. See [shielded pool incentives](./shielded-pool-incentives.md) for details. +Privacy provided by the MASP in practice depends on how many users use the shielded pool and what assets they use it with. To increase the likelihood of a sizeable privacy set, Namada pays a variable portion of inflation, up to 10% per annum, to shielded pool incentives, which are allocated on a per-asset basis by a PD-controller targeting specific amounts of each asset being locked in the shielded pool. See [shielded pool incentives](./shielded-pool-incentives.mdx) for details. ### Public goods funding -Namada provides 10% per annum inflation for other non-algorithmically-measurable public goods. See [public goods funding](./public-goods-funding.md) for details. +Namada provides 10% per annum inflation for other non-algorithmically-measurable public goods. See [public goods funding](./public-goods-funding.mdx) for details. ## Detailed inflation calculation model diff --git a/packages/specs/pages/economics/proof-of-stake.mdx b/packages/specs/pages/economics/proof-of-stake.mdx index 7b052b85..74991c68 100644 --- a/packages/specs/pages/economics/proof-of-stake.mdx +++ b/packages/specs/pages/economics/proof-of-stake.mdx @@ -1,8 +1,8 @@ # Proof-of-stake (PoS) -This section of the specification describes the proof-of-stake mechanism of Namada, which is largely modeled after [Cosmos bonded proof-of-stake](https://github.com/cosmos/cosmos-sdk/blob/master/x/staking/spec/README.md), but makes significant changes to bond storage representation, validator set change handling, reward distribution, and slashing, with the general aims of increased precision in reasoning about security, validator decentralisation, and avoiding unnecessary proof-of-stake-related transactions. +This section of the specification describes the proof-of-stake mechanism of Namada, which is largely modeled after [Cosmos bonded proof-of-stake](https://github.com/cosmos/cosmos-sdk/blob/master/x/staking/spec/README.mdx), but makes significant changes to bond storage representation, validator set change handling, reward distribution, and slashing, with the general aims of increased precision in reasoning about security, validator decentralisation, and avoiding unnecessary proof-of-stake-related transactions. -This section is split into three subcomponents: the [bonding mechanism](./proof-of-stake/objects-and-txs.md), [reward distribution](./proof-of-stake/reward-distribution.md), and [cubic slashing](./proof-of-stake/cubic-slashing.md). +This section is split into three subcomponents: the [bonding mechanism](./proof-of-stake/objects-and-txs.mdx), [reward distribution](./proof-of-stake/reward-distribution.mdx), and [cubic slashing](./proof-of-stake/cubic-slashing.mdx). ## Context diff --git a/packages/specs/pages/economics/proof-of-stake/cubic-slashing.mdx b/packages/specs/pages/economics/proof-of-stake/cubic-slashing.mdx index d96b6ea8..b663c7fa 100644 --- a/packages/specs/pages/economics/proof-of-stake/cubic-slashing.mdx +++ b/packages/specs/pages/economics/proof-of-stake/cubic-slashing.mdx @@ -14,7 +14,7 @@ The cubic slash rate is a function of all infractions in a given epoch and its n $$ 9*\left(\sum_{i \in \text{infractions}}\frac{\text{vp}_i}{\text{vp}_{\text{tot}}^i}\right)^2. $$ -For each individual slash, the rate is ultimately determined as the maximum of the cubic slash rate and some nominal minimum rate that is dependent on the infraction type (see [system parameters](./objects-and-txs.md#system-parameters)) and is capped at 1.0. The amount of slashed tokens is the rate multiplied by the stake (voting power) used to commit the infraction. The "cubic" in cubic slashing thus comes from the product of the rate, which is quadratic in the voting power, and the voting power itself. +For each individual slash, the rate is ultimately determined as the maximum of the cubic slash rate and some nominal minimum rate that is dependent on the infraction type (see [system parameters](./objects-and-txs.mdx#system-parameters)) and is capped at 1.0. The amount of slashed tokens is the rate multiplied by the stake (voting power) used to commit the infraction. The "cubic" in cubic slashing thus comes from the product of the rate, which is quadratic in the voting power, and the voting power itself. Expressed in pseudocode: diff --git a/packages/specs/pages/economics/proof-of-stake/objects-and-txs.mdx b/packages/specs/pages/economics/proof-of-stake/objects-and-txs.mdx index 1fa515bf..6d4104a1 100644 --- a/packages/specs/pages/economics/proof-of-stake/objects-and-txs.mdx +++ b/packages/specs/pages/economics/proof-of-stake/objects-and-txs.mdx @@ -57,7 +57,7 @@ A *candidate* validator that is not jailed (see [slashing](#slashing)) can be in From all the *candidate* validators, in each epoch the ones with the most voting power limited up to the `max_validator_slots` [parameter](#system-parameters) are selected for the `consensus` validator set. Whenever stake of a validator is changed, the validator sets must be updated at the appropriate offset matching the stake update. -The limit on `min_validator_stake` [parameter](#system-parameters) is introduced, because the protocol needs to iterate through the validator sets in order to copy the last known state into a new epoch when epoch changes (to avoid offloading this cost to a transaction that is unlucky enough to be the first one to update the validator set(s) in some new epoch) and also to [distribute rewards](./reward-distribution.md) to `consensus` validators and to record unchanged validator products for validators `below_capacity`, who do not receive rewards in the current epoch. +The limit on `min_validator_stake` [parameter](#system-parameters) is introduced, because the protocol needs to iterate through the validator sets in order to copy the last known state into a new epoch when epoch changes (to avoid offloading this cost to a transaction that is unlucky enough to be the first one to update the validator set(s) in some new epoch) and also to [distribute rewards](./reward-distribution.mdx) to `consensus` validators and to record unchanged validator products for validators `below_capacity`, who do not receive rewards in the current epoch. ### Delegator @@ -113,7 +113,7 @@ Once an offense has been reported: 2. Slashing - Individual: Once someone has reported an offense it is reviewed by validators and if confirmed the offender is slashed. -- [cubic slashing](./cubic-slashing.md): escalated slashing +- [cubic slashing](./cubic-slashing.mdx): escalated slashing Instead of absolute values, validators' total bonded token amounts and bonds' and unbonds' token amounts are stored as their deltas (i.e. the change of quantity from a previous epoch) to allow distinguishing changes for different epoch, which is essential for determining whether tokens should be slashed. Slashes for a fault that occurred in epoch `n` may only be applied before the beginning of epoch `n + unbonding_length`. For this reason, in epoch `m` we can sum all the deltas of total bonded token amounts and bonds and unbond with the same source and validator for epoch equal or less than `m - unbonding_length` into a single total bonded token amount, single bond and single unbond record. This is to keep the total number of total bonded token amounts for a unique validator and bonds and unbonds for a unique pair of source and validator bound to a maximum number (equal to `unbonding_length`). @@ -134,7 +134,7 @@ This set is used to initialize the genesis state with epoched data active immedi The default values that are relative to epoch duration assume that an epoch last about 24 hours. - `max_validator_slots`: Maximum consensus validators, default `128` -- `min_validator_stake`: Minimum stake of a validator that allows the validator to enter the `consensus` or `below_capacity` [sets](#validator-sets), in number of native tokens. Because the [inflation system](../inflation-system.md#proof-of-stake-rewards) targets a bonding ratio of 2/3, the minimum should be somewhere around `total_supply * 2/3 / max_validator_slots`, but it can and should be much lower to lower the entry cost, as long as it's enough to prevent validation account creation spam that could slow down PoS system update on epoch change +- `min_validator_stake`: Minimum stake of a validator that allows the validator to enter the `consensus` or `below_capacity` [sets](#validator-sets), in number of native tokens. Because the [inflation system](../inflation-system.mdx#proof-of-stake-rewards) targets a bonding ratio of 2/3, the minimum should be somewhere around `total_supply * 2/3 / max_validator_slots`, but it can and should be much lower to lower the entry cost, as long as it's enough to prevent validation account creation spam that could slow down PoS system update on epoch change - `pipeline_len`: Pipeline length in number of epochs, default `2`, [see this link](https://github.com/cosmos/cosmos-sdk/blob/019444ae4328beaca32f2f8416ee5edbac2ef30b/docs/architecture/adr-039-epoched-staking.md#pipelining-the-epochs) - `unboding_len`: Unbonding duration in number of epochs, default `6` - `cubic_slash_window_width`: The number of epochs above and below the current one in which to collect misbehaviors for use in computing the cubic slash rate, default `1`. @@ -267,7 +267,7 @@ When any validator's voting power changes, we attempt to perform the following u 1. else if `power_after >= min_validator_stake`, insert the validator into `below_capacity` set with `voting_power = power_after` 1. else, do nothing -Additionally, for [rewards distribution](./reward-distribution.md): +Additionally, for [rewards distribution](./reward-distribution.mdx): - When a validator moves from `below_threshold` set to either `below_capacity` or `consensus` set, the transaction must also fill in the validator's reward products from its last known value, if any, in all epochs starting from their `last_known_product_epoch` (exclusive) up to the `current_epoch + pipeline_len - 1` (inclusive) in order to make their look-up cost constant (assuming that validator's stake can only be increased at `pipeline_len` offset). - And on the opposite side, when a stake of a validator from `consensus` or `below_capacity` drops below `min_validator_stake`, we record their `last_known_product_epoch`, so that it can be used if and when the validator's stake goes above `min_validator_stake`. diff --git a/packages/specs/pages/economics/proof-of-stake/reward-distribution.mdx b/packages/specs/pages/economics/proof-of-stake/reward-distribution.mdx index 48a00e7d..a24e58cf 100644 --- a/packages/specs/pages/economics/proof-of-stake/reward-distribution.mdx +++ b/packages/specs/pages/economics/proof-of-stake/reward-distribution.mdx @@ -2,7 +2,7 @@ Namada uses the automatically-compounding variant of the [F1 fee distribution](https://drops.dagstuhl.de/opus/volltexte/2020/11974/pdf/OASIcs-Tokenomics-2019-10.pdf). -Rewards are given to validators for proposing blocks, for voting on finalizing blocks, and for being in the [consensus validator set](objects-and-txs.md#validator-sets). The funds for these rewards come from **minting** (creating new tokens). The amount that is minted depends on how many staking tokens are locked (staked) and some maximum annual inflation rate. The rewards mechanism is implemented as a [PD controller](../inflation-system.md#detailed-inflation-calculation-model) that dynamically adjusts the inflation rate to achieve a target staked token ratio. When the total fraction of tokens staked is very low, the return rate per validator needs to increase, but as the total fraction of stake rises, validators will receive fewer rewards. Once the desired staking fraction is achieved, the amount minted will just be the desired annual inflation. +Rewards are given to validators for proposing blocks, for voting on finalizing blocks, and for being in the [consensus validator set](objects-and-txs.mdx#validator-sets). The funds for these rewards come from **minting** (creating new tokens). The amount that is minted depends on how many staking tokens are locked (staked) and some maximum annual inflation rate. The rewards mechanism is implemented as a [PD controller](../inflation-system.mdx#detailed-inflation-calculation-model) that dynamically adjusts the inflation rate to achieve a target staked token ratio. When the total fraction of tokens staked is very low, the return rate per validator needs to increase, but as the total fraction of stake rises, validators will receive fewer rewards. Once the desired staking fraction is achieved, the amount minted will just be the desired annual inflation. Each delegation to a validator is initiated at an agreed-upon commission rate charged by the validator. Validators pay out rewards to delegators based on this mutually-determined commission rate. The minted rewards are auto-bonded and only transferred when the funds are unbonded. Once the protocol determines the total amount of tokens to mint at the end of the epoch, the minted tokens are effectively divided among the relevant validators and delegators according to their proportional stake. In practice, the reward products, which are the fractional increases in staked tokens claimed, are stored for the validators and delegators, and the reward tokens are only transferred to the validator’s or delegator’s account upon withdrawal. This is described in the following sections. The general system is similar to what Cosmos does. @@ -17,7 +17,7 @@ Consider a system with - bonding is processed after the pipeline length - unbonding is processed after the pipeline + unbonding length - rewards are paid out at the end of each epoch, i.e., in each epoch $e$, a reward $R_{e,i}$ is paid out to validator $V_i$ - - slashing is applied as described in [slashing](cubic-slashing.md). + - slashing is applied as described in [slashing](cubic-slashing.mdx). We wish to approximate as exactly as possible the following ideal delegator reward distribution system: @@ -148,7 +148,7 @@ in order to calculate the new rewards given out to the delegator during withdraw The commission rate $c_V(e)$ is the same for all delegations to a validator $V$ in a given epoch $e$, including for self-bonds. The validator can change the commission rate at any point, subject to a maximum rate of change per epoch, which is a constant specified when the validator is created and immutable once validator creation has been accepted. -While rewards are given out at the end of every epoch, voting power is only updated after the pipeline offset. According to the [proof-of-stake system](objects-and-txs.md#epoched-data), at the current epoch `e`, the validator sets can only be updated for epoch `e + pipeline_offset`, and it should remain unchanged from epoch `e` to `e + pipeline_offset - 1`. Updating voting power in the current epoch would violate this rule. +While rewards are given out at the end of every epoch, voting power is only updated after the pipeline offset. According to the [proof-of-stake system](objects-and-txs.mdx#epoched-data), at the current epoch `e`, the validator sets can only be updated for epoch `e + pipeline_offset`, and it should remain unchanged from epoch `e` to `e + pipeline_offset - 1`. Updating voting power in the current epoch would violate this rule. ## Distribution of block rewards to validators diff --git a/packages/specs/pages/economics/public-goods-funding/becoming-a-steward.mdx b/packages/specs/pages/economics/public-goods-funding/becoming-a-steward.mdx index fd7b4bf1..1b16fc15 100644 --- a/packages/specs/pages/economics/public-goods-funding/becoming-a-steward.mdx +++ b/packages/specs/pages/economics/public-goods-funding/becoming-a-steward.mdx @@ -16,7 +16,7 @@ Nominating oneself as a PGF steward may be done at any time. Before a new PGF steward can either be elected or removed, a governance proposal that specifies this objective must pass. The voting on this proposal is handled by the governance proposal type `StewardProposal`, which is a custom proposal type. -The struct of `StewardProposal` is constructed as follows, and is explained in more detail in the [governance specs](../base-ledger/governance.md) +The struct of `StewardProposal` is constructed as follows, and is explained in more detail in the [governance specs](../base-ledger/governance.mdx) ```rust struct StewardProposal{ diff --git a/packages/specs/pages/economics/shielded-pool-incentives.mdx b/packages/specs/pages/economics/shielded-pool-incentives.mdx index 7966f37a..f02ecc20 100644 --- a/packages/specs/pages/economics/shielded-pool-incentives.mdx +++ b/packages/specs/pages/economics/shielded-pool-incentives.mdx @@ -15,7 +15,7 @@ Namada enacts a shielded pool incentive which pays users a variable rate for kee ### Implementation -When users deposit assets into the shielded pool, the current epoch is appended to the asset type. Users can use these "epoched assets" as normal within the shielded pool. When epochs advance, users can use the [convert circuit](../masp/convert-circuit.md) to convert assets tagged with the old epoch to assets tagged with the new epoch, receiving shielded rewards in NAM proportional to the amount of the asset they had shielded, which automatically compound while the assets are shielded and the epochs progressing. When unshielding from the shielded pool, assets must be first converted to the current epoch (claiming any rewards), after which they can be converted back to the normal (un-epoched) unshielded asset denomination. +When users deposit assets into the shielded pool, the current epoch is appended to the asset type. Users can use these "epoched assets" as normal within the shielded pool. When epochs advance, users can use the [convert circuit](../masp/convert-circuit.mdx) to convert assets tagged with the old epoch to assets tagged with the new epoch, receiving shielded rewards in NAM proportional to the amount of the asset they had shielded, which automatically compound while the assets are shielded and the epochs progressing. When unshielding from the shielded pool, assets must be first converted to the current epoch (claiming any rewards), after which they can be converted back to the normal (un-epoched) unshielded asset denomination. Namada allocates up to 10% per annum inflation of NAM to pay for shielded pool rewards. diff --git a/packages/specs/pages/governance.mdx b/packages/specs/pages/governance.mdx index 174efae4..4ee7a0f2 100644 --- a/packages/specs/pages/governance.mdx +++ b/packages/specs/pages/governance.mdx @@ -38,7 +38,7 @@ It is also possible to attach some payloads to proposals, in specific cases, to Governance on Namada supports both `signaling` and `voting` mechanisms. The signaling mechanism is used for changes which require a hard fork, while the voting mechanism is used for changes which merely alter state. In cases where the chain is not able to produce blocks anymore, Namada relies on [off-chain signaling](#off-chain-protocol) to agree on a common move. -Further information about delegators, validators, and NAM can be found in the [economics section](../economics.md). +Further information about delegators, validators, and NAM can be found in the [economics section](../economics.mdx). ## Outline There are two ways to propose a change to the Namada protocol: diff --git a/packages/specs/pages/governance/off-chain.mdx b/packages/specs/pages/governance/off-chain.mdx index 7e889aa7..c741801f 100644 --- a/packages/specs/pages/governance/off-chain.mdx +++ b/packages/specs/pages/governance/off-chain.mdx @@ -48,5 +48,5 @@ The signature is produced over the hash of the concatenation of: `proposalHash`, ## Tallying votes offline -Offline votes are tallied under the same mechanism as [on chain vote tallying](./on-chain.md#tally), but instead of reading the data from storage it will require a list of serialized json votes. +Offline votes are tallied under the same mechanism as [on chain vote tallying](./on-chain.mdx#tally), but instead of reading the data from storage it will require a list of serialized json votes. The voting power for each delegate/delegator is calculated based on their respective bonded-stake from the latest block in that epoch (in principle it could be any block in the epoch, since voting-power does not change within an epoch). \ No newline at end of file diff --git a/packages/specs/pages/governance/on-chain.mdx b/packages/specs/pages/governance/on-chain.mdx index 6aa60419..bab1f952 100644 --- a/packages/specs/pages/governance/on-chain.mdx +++ b/packages/specs/pages/governance/on-chain.mdx @@ -10,13 +10,13 @@ This address also stores all previous proposals under its address space. Proposals are submitted through the client, and are verified by the `GovernanceAddress` before being added to the pending proposals list. -The structure of proposals is outlined [here](./proposal.md). +The structure of proposals is outlined [here](./proposal.mdx). The correct logic to handle these different types is hardcoded in protocol. We'll also rely on type checking to strictly enforce the correctness of a proposal given its type. These two approaches combined will prevent a user from deviating from the intended logic for a certain proposal type (e.g. providing a wasm code when it's not needed or allowing only validators to vote when also delegators should, etc...). -More details on the specific types supported can be found in the [relative](#supported-proposal-types) section of the [proposals page](./proposal.md). +More details on the specific types supported can be found in the [relative](#supported-proposal-types) section of the [proposals page](./proposal.mdx). ### GovernanceAddress VP @@ -28,7 +28,7 @@ A proposal must satisfy the following mandatory storage writes: - `counter` - The number of proposals submitted so far - `author` - The address of the author of the proposal -- `type` - The [proposal type](./proposal.md#supported-proposal-types) +- `type` - The [proposal type](./proposal.mdx#supported-proposal-types) - `funds` - The amount of funds locked for this proposal - `voting_start` - The epoch specifying when the voting period starts - `voting_end`- The epoch specifying when the voting period ends @@ -95,7 +95,7 @@ struct OnChainVote { ``` where `ProposalVote` is an enum representing a `Yay` or `Nay` vote: the yay variant also contains the specific memo (if any) required for that proposal. -Storage writes for a vote transaction are described [here](./storage.md#votes). +Storage writes for a vote transaction are described [here](./storage.mdx#votes). If non-validating accounts are allowed to vote, delegates will be able to vote only for $\frac{2}{3}$ of the total voting period, while delegators can vote until the end of the voting period. If only validators are allowed to vote for the `ProposalType` in question, they are allowed to vote for the entire voting window. diff --git a/packages/specs/pages/governance/storage.mdx b/packages/specs/pages/governance/storage.mdx index ffd2b9c0..25af7af1 100644 --- a/packages/specs/pages/governance/storage.mdx +++ b/packages/specs/pages/governance/storage.mdx @@ -25,7 +25,7 @@ Each proposal is stored in a sub-key under the internal proposal address. The st An **epoch** is a range of blocks or time that is defined by the base ledger and made available to the PoS system. This document assumes that epochs are identified by consecutive natural numbers. -All the data relevant to PoS are [associated with epochs](../economics/proof-of-stake/objects-and-txs.md#epoched-data). +All the data relevant to PoS are [associated with epochs](../economics/proof-of-stake/objects-and-txs.mdx#epoched-data). `/$GovernanceAddress/proposal/$epoch/$id` is used for efficient iteration over proposals by epoch. diff --git a/packages/specs/pages/index.mdx b/packages/specs/pages/index.mdx index 605d4c86..bbb8071f 100644 --- a/packages/specs/pages/index.mdx +++ b/packages/specs/pages/index.mdx @@ -41,11 +41,11 @@ Users on Namada earn rewards, retain privacy of assets, and contribute to shared The Namada specification documents are organised into four sub-sections: -- [Base ledger](./base-ledger.md) -- [Governance](./governance.md) -- [Multi-asset shielded pool](./masp.md) -- [Interoperability](./interoperability.md) -- [Economics](./economics.md) +- [Base ledger](./base-ledger.mdx) +- [Governance](./governance.mdx) +- [Multi-asset shielded pool](./masp.mdx) +- [Interoperability](./interoperability.mdx) +- [Economics](./economics.mdx) This book is written using [NextraJS](https://nextra.site/). The source can be found in the [Namada Docs repository](https://github.com/anoma/namada-docs/tree/master/packages/specs). diff --git a/packages/specs/pages/interoperability.mdx b/packages/specs/pages/interoperability.mdx index f3144d74..7f49d708 100644 --- a/packages/specs/pages/interoperability.mdx +++ b/packages/specs/pages/interoperability.mdx @@ -1,5 +1,5 @@ ## Interoperability Namada is designed for trust-minimized interoperation with both the Ethereum and Cosmos ecosystems: -- To the Ethereum ecosystem (Ethereum main chain and any rollups bridged to it), Namada connects using a bespoke [Ethereum bridge](./interoperability/ethereum-bridge.md) operated by the Namada validator set. -- To the Cosmos ecosystem (any chain which supports IBC), Namada connects using an [integration of the IBC protocol](./interoperability/ibc.md). \ No newline at end of file +- To the Ethereum ecosystem (Ethereum main chain and any rollups bridged to it), Namada connects using a bespoke [Ethereum bridge](./interoperability/ethereum-bridge.mdx) operated by the Namada validator set. +- To the Cosmos ecosystem (any chain which supports IBC), Namada connects using an [integration of the IBC protocol](./interoperability/ibc.mdx). \ No newline at end of file diff --git a/packages/specs/pages/interoperability/ethereum-bridge.mdx b/packages/specs/pages/interoperability/ethereum-bridge.mdx index da78d5a2..39828b97 100644 --- a/packages/specs/pages/interoperability/ethereum-bridge.mdx +++ b/packages/specs/pages/interoperability/ethereum-bridge.mdx @@ -9,7 +9,7 @@ The Namada Ethereum bridge system consists of: * An Ethereum full node run by each Namada validator, for including relevant Ethereum events into Namada. * A set of validity predicates on Namada which roughly implements - [ICS20](https://github.com/cosmos/ibc/blob/main/spec/app/ics-020-fungible-token-transfer/README.md) fungible token + [ICS20](https://github.com/cosmos/ibc/blob/main/spec/app/ics-020-fungible-token-transfer/README.mdx) fungible token transfers. * A set of Ethereum smart contracts. * An automated process to send validator set updates to the Ethereum smart @@ -22,13 +22,13 @@ bidirectional message passing with reasonably low gas costs on the Ethereum side. ## Topics - - [Bootstrapping](./ethereum-bridge/bootstrapping.md) - - [Security](./ethereum-bridge/security.md) - - [Ethereum Events Attestation](./ethereum-bridge/ethereum_events_attestation.md) - - [Transfers from Ethereum to Namada](./ethereum-bridge/transfers_to_namada.md) - - [Transfers from Namada to Ethereum](./ethereum-bridge/transfers_to_ethereum.md) - - [Proofs and validator set updates](./ethereum-bridge/proofs.md) - - [Smart Contracts](./ethereum-bridge/ethereum_smart_contracts.md) + - [Bootstrapping](./ethereum-bridge/bootstrapping.mdx) + - [Security](./ethereum-bridge/security.mdx) + - [Ethereum Events Attestation](./ethereum-bridge/ethereum_events_attestation.mdx) + - [Transfers from Ethereum to Namada](./ethereum-bridge/transfers_to_namada.mdx) + - [Transfers from Namada to Ethereum](./ethereum-bridge/transfers_to_ethereum.mdx) + - [Proofs and validator set updates](./ethereum-bridge/proofs.mdx) + - [Smart Contracts](./ethereum-bridge/ethereum_smart_contracts.mdx) ## Resources which may be helpful diff --git a/packages/specs/pages/interoperability/ethereum-bridge/bootstrapping.mdx b/packages/specs/pages/interoperability/ethereum-bridge/bootstrapping.mdx index 876f83ec..f6ce1ac5 100644 --- a/packages/specs/pages/interoperability/ethereum-bridge/bootstrapping.mdx +++ b/packages/specs/pages/interoperability/ethereum-bridge/bootstrapping.mdx @@ -16,7 +16,7 @@ enable the Ethereum bridge for a given Namada chain are: to launch the Ethereum bridge by means of a hard fork. - If the proposal passes, the Namada chain must halt after finalizing block `h-1`. This requires -- The [Ethereum bridge smart contracts](./ethereum_smart_contracts.md) are +- The [Ethereum bridge smart contracts](./ethereum_smart_contracts.mdx) are deployed to the relevant EVM chain, with the active validator set at block height `h` as the initial validator set that controls the bridge. - Details are published so that the deployed contracts can be verified by anyone diff --git a/packages/specs/pages/interoperability/ethereum-bridge/proofs.mdx b/packages/specs/pages/interoperability/ethereum-bridge/proofs.mdx index 8c03681e..2f4575de 100644 --- a/packages/specs/pages/interoperability/ethereum-bridge/proofs.mdx +++ b/packages/specs/pages/interoperability/ethereum-bridge/proofs.mdx @@ -5,11 +5,11 @@ bridge header is a proof attached to a message understandable to the Ethereum smart contracts. For transferring value to Ethereum, a proof is a signed Merkle tree root and inclusion proofs of asset transfer messages understandable to the Ethereum smart contracts, as described in the section on -[batching](transfers_to_ethereum.md#batching). +[batching](transfers_to_ethereum.mdx#batching). A message for transferring value to Ethereum is a `TransferToNamada` instance as described -[here](./transfers_to_ethereum.md#bridge-pool-validity-predicate). +[here](./transfers_to_ethereum.mdx#bridge-pool-validity-predicate). Additionally, when the validator set changes, the smart contracts on Ethereum must be updated so that it can continue to recognize valid proofs. diff --git a/packages/specs/pages/interoperability/ethereum-bridge/transfers_to_ethereum.mdx b/packages/specs/pages/interoperability/ethereum-bridge/transfers_to_ethereum.mdx index 83611a65..289c65d6 100644 --- a/packages/specs/pages/interoperability/ethereum-bridge/transfers_to_ethereum.mdx +++ b/packages/specs/pages/interoperability/ethereum-bridge/transfers_to_ethereum.mdx @@ -3,7 +3,7 @@ Moving assets from Namada to Ethereum will not be automatic, as opposed the movement of value in the opposite direction. Instead, users must send an appropriate transaction to Namada to initiate a transfer across the bridge -to Ethereum. Once this transaction is approved, a ["proof"](proofs.md), or +to Ethereum. Once this transaction is approved, a ["proof"](proofs.mdx), or the parts necessary to create a proof, will be created and posted on Namada. It is incumbent on the end user to request an appropriate proof diff --git a/packages/specs/pages/interoperability/ibc.mdx b/packages/specs/pages/interoperability/ibc.mdx index 5c70cc1c..884166e4 100644 --- a/packages/specs/pages/interoperability/ibc.mdx +++ b/packages/specs/pages/interoperability/ibc.mdx @@ -17,7 +17,7 @@ Specifically, the validity predicate mainly consists of two parts. The first part is the state change check. It executes the corresponding IBC operation and gets the post-states of the IBC-related data. Then, it checks whether the actual states of IBC-related data by the transaction are equal to the result of the pseudo execution. The second part is the validation of the IBC-related data. It validates that the corresponding data conforms to the IBC protocol. The pseudo-execution and the validation functions are imported from `ibc-rs`. ## Fungible Token Transfer -The transfer of fungible tokens over an IBC channel on separate chains is defined in [ICS20](https://github.com/cosmos/ibc/blob/master/spec/app/ics-020-fungible-token-transfer/README.md). +The transfer of fungible tokens over an IBC channel on separate chains is defined in [ICS20](https://github.com/cosmos/ibc/blob/master/spec/app/ics-020-fungible-token-transfer/README.mdx). In Namada, the sending tokens is triggered by a transaction having [MsgTransfer](https://github.com/cosmos/ibc-rs/blob/014fec6958fedcfe9ed6ebfb2d0c28c2cb6487af/crates/ibc/src/applications/transfer/msgs/transfer.rs) as transaction data. A packet including [`PacketData`](https://github.com/cosmos/ibc-rs/blob/014fec6958fedcfe9ed6ebfb2d0c28c2cb6487af/crates/ibc/src/applications/transfer/packet.rs) for the transfer is made from the message in the transaction execution. diff --git a/packages/specs/pages/masp.mdx b/packages/specs/pages/masp.mdx index d1a87e9b..289263f6 100644 --- a/packages/specs/pages/masp.mdx +++ b/packages/specs/pages/masp.mdx @@ -4,8 +4,8 @@ The multi-asset shielded pool (MASP) is an extension to the Sapling circuit whic See the following documents: - [Cryptographic specification](https://github.com/anoma/masp/blob/main/docs/multi-asset-shielded-pool.pdf) -- [Ledger integration](./masp/ledger-integration.md) -- [Asset type schema](./masp/asset-type.md) -- [Burn and mint](./masp/burn-and-mint.md) -- [Convert circuit](./masp/convert-circuit.md) -- [Shielded pool incentives](./economics/shielded-pool-incentives.md) \ No newline at end of file +- [Ledger integration](./masp/ledger-integration.mdx) +- [Asset type schema](./masp/asset-type.mdx) +- [Burn and mint](./masp/burn-and-mint.mdx) +- [Convert circuit](./masp/convert-circuit.mdx) +- [Shielded pool incentives](./economics/shielded-pool-incentives.mdx) \ No newline at end of file diff --git a/packages/specs/pages/masp/ledger-integration.mdx b/packages/specs/pages/masp/ledger-integration.mdx index 5acc47f3..b284562d 100644 --- a/packages/specs/pages/masp/ledger-integration.mdx +++ b/packages/specs/pages/masp/ledger-integration.mdx @@ -353,7 +353,7 @@ Let `ZKSpend` be as defined in [4.1.13](https://zips.z.cash/protocol/protocol.pd A convert description comprises `(cv, rt, pi)` where * `cv: ValueCommit.Output` is value commitment to the value of the conversion note * `rt: B[Sapling Merkle]` is an anchor for the current conversion tree or an archived conversion tree -* `pi: ZKConvert.Proof` is a zk-SNARK proof with primary input `(rt, cv)` for the Convert statement defined at [Burn and Mint conversion transactions in MASP](./burn-and-mint.md). +* `pi: ZKConvert.Proof` is a zk-SNARK proof with primary input `(rt, cv)` for the Convert statement defined at [Burn and Mint conversion transactions in MASP](./burn-and-mint.mdx). #### Convert Description Encoding Let `pi_{ZKConvert}` be the zk-SNARK proof of the corresponding Convert statement. `pi_{ZKConvert}` is encoded in the `zkproof` field of the Convert description. From 57bc8686f8568a9137fafaec995bb91b548fe286 Mon Sep 17 00:00:00 2001 From: Bengt Lofgren <51077282+bengtlofgren@users.noreply.github.com> Date: Tue, 10 Oct 2023 03:35:00 -0600 Subject: [PATCH 2/5] Update packages/specs/pages/interoperability/ethereum-bridge.mdx --- packages/specs/pages/interoperability/ethereum-bridge.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/specs/pages/interoperability/ethereum-bridge.mdx b/packages/specs/pages/interoperability/ethereum-bridge.mdx index 39828b97..dbfba781 100644 --- a/packages/specs/pages/interoperability/ethereum-bridge.mdx +++ b/packages/specs/pages/interoperability/ethereum-bridge.mdx @@ -9,7 +9,7 @@ The Namada Ethereum bridge system consists of: * An Ethereum full node run by each Namada validator, for including relevant Ethereum events into Namada. * A set of validity predicates on Namada which roughly implements - [ICS20](https://github.com/cosmos/ibc/blob/main/spec/app/ics-020-fungible-token-transfer/README.mdx) fungible token + [ICS20](https://github.com/cosmos/ibc/blob/main/spec/app/ics-020-fungible-token-transfer/README.md) fungible token transfers. * A set of Ethereum smart contracts. * An automated process to send validator set updates to the Ethereum smart From 9982607912646bf1893497ece931576ee2fbd989 Mon Sep 17 00:00:00 2001 From: Bengt Lofgren <51077282+bengtlofgren@users.noreply.github.com> Date: Tue, 10 Oct 2023 03:35:06 -0600 Subject: [PATCH 3/5] Update packages/specs/pages/interoperability/ibc.mdx --- packages/specs/pages/interoperability/ibc.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/specs/pages/interoperability/ibc.mdx b/packages/specs/pages/interoperability/ibc.mdx index 884166e4..5c70cc1c 100644 --- a/packages/specs/pages/interoperability/ibc.mdx +++ b/packages/specs/pages/interoperability/ibc.mdx @@ -17,7 +17,7 @@ Specifically, the validity predicate mainly consists of two parts. The first part is the state change check. It executes the corresponding IBC operation and gets the post-states of the IBC-related data. Then, it checks whether the actual states of IBC-related data by the transaction are equal to the result of the pseudo execution. The second part is the validation of the IBC-related data. It validates that the corresponding data conforms to the IBC protocol. The pseudo-execution and the validation functions are imported from `ibc-rs`. ## Fungible Token Transfer -The transfer of fungible tokens over an IBC channel on separate chains is defined in [ICS20](https://github.com/cosmos/ibc/blob/master/spec/app/ics-020-fungible-token-transfer/README.mdx). +The transfer of fungible tokens over an IBC channel on separate chains is defined in [ICS20](https://github.com/cosmos/ibc/blob/master/spec/app/ics-020-fungible-token-transfer/README.md). In Namada, the sending tokens is triggered by a transaction having [MsgTransfer](https://github.com/cosmos/ibc-rs/blob/014fec6958fedcfe9ed6ebfb2d0c28c2cb6487af/crates/ibc/src/applications/transfer/msgs/transfer.rs) as transaction data. A packet including [`PacketData`](https://github.com/cosmos/ibc-rs/blob/014fec6958fedcfe9ed6ebfb2d0c28c2cb6487af/crates/ibc/src/applications/transfer/packet.rs) for the transfer is made from the message in the transaction execution. From 6062eb331812f055c078501b556a55ed3a217f02 Mon Sep 17 00:00:00 2001 From: Bengt Lofgren <51077282+bengtlofgren@users.noreply.github.com> Date: Tue, 10 Oct 2023 03:35:11 -0600 Subject: [PATCH 4/5] Update packages/specs/pages/economics/proof-of-stake.mdx --- packages/specs/pages/economics/proof-of-stake.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/specs/pages/economics/proof-of-stake.mdx b/packages/specs/pages/economics/proof-of-stake.mdx index 74991c68..d103fb6d 100644 --- a/packages/specs/pages/economics/proof-of-stake.mdx +++ b/packages/specs/pages/economics/proof-of-stake.mdx @@ -1,6 +1,6 @@ # Proof-of-stake (PoS) -This section of the specification describes the proof-of-stake mechanism of Namada, which is largely modeled after [Cosmos bonded proof-of-stake](https://github.com/cosmos/cosmos-sdk/blob/master/x/staking/spec/README.mdx), but makes significant changes to bond storage representation, validator set change handling, reward distribution, and slashing, with the general aims of increased precision in reasoning about security, validator decentralisation, and avoiding unnecessary proof-of-stake-related transactions. +This section of the specification describes the proof-of-stake mechanism of Namada, which is largely modeled after [Cosmos bonded proof-of-stake](https://github.com/cosmos/cosmos-sdk/blob/master/x/staking/spec/README.md), but makes significant changes to bond storage representation, validator set change handling, reward distribution, and slashing, with the general aims of increased precision in reasoning about security, validator decentralisation, and avoiding unnecessary proof-of-stake-related transactions. This section is split into three subcomponents: the [bonding mechanism](./proof-of-stake/objects-and-txs.mdx), [reward distribution](./proof-of-stake/reward-distribution.mdx), and [cubic slashing](./proof-of-stake/cubic-slashing.mdx). From a4de5b6fd138a4981ae6ec4fff0485b750945a7a Mon Sep 17 00:00:00 2001 From: Bengt Lofgren <51077282+bengtlofgren@users.noreply.github.com> Date: Tue, 10 Oct 2023 03:35:17 -0600 Subject: [PATCH 5/5] Update packages/specs/pages/base-ledger/replay-protection.mdx --- packages/specs/pages/base-ledger/replay-protection.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/specs/pages/base-ledger/replay-protection.mdx b/packages/specs/pages/base-ledger/replay-protection.mdx index ae16578d..e815ff43 100644 --- a/packages/specs/pages/base-ledger/replay-protection.mdx +++ b/packages/specs/pages/base-ledger/replay-protection.mdx @@ -32,7 +32,7 @@ This section illustrates the pre-existing context in the replay protection mecha The current implementation of Namada is built on top of CometBFT which provides an encrypted and authenticated communication channel between every two nodes to prevent a _man-in-the-middle_ attack (see the detailed {/* TODO: Fix link to be cometbft is possible*/} -[spec](https://github.com/cometbft/cometbft/blob/main/spec/p2p/legacy-docs/peer.mdx)). +[spec](https://github.com/cometbft/cometbft/blob/main/spec/p2p/legacy-docs/peer.md)). The Namada protocol relies on this substrate to exchange transactions (messages) that defines the state transition of the ledger. More specifically, a