diff --git a/packages/docs/pages/index.mdx b/packages/docs/pages/index.mdx index bfb69be8..3cc4ebcb 100644 --- a/packages/docs/pages/index.mdx +++ b/packages/docs/pages/index.mdx @@ -17,15 +17,15 @@ ## Overview of features -- Proof-of-Stake with governance to secure and evolve Namada +- [Proof-of-Stake](./proof-of-stake) with [governance](./governance) to secure and evolve Namada - Fast-finality BFT with 4-second blocks - Near-zero fees - Trust-minimized 2-way Ethereum bridge - IBC connections to chains that already speak IBC (all Cosmos chains) -- Multi-Asset Shielded Pool (MASP) -- Convert Circuit (shielded set rewards) +- [Multi-Asset Shielded Pool](./users/shielded-transfers) (MASP) +- Convert Circuit ([shielded set rewards](./users/shielded-rewards)) - A reference interface -- Ledger application +- [Ledger](./wallet/hardware-wallet) application For high-level introductions, we recommend: diff --git a/packages/docs/pages/introduction/testnets/pow.mdx b/packages/docs/pages/introduction/testnets/pow.mdx index 59310453..bc436352 100644 --- a/packages/docs/pages/introduction/testnets/pow.mdx +++ b/packages/docs/pages/introduction/testnets/pow.mdx @@ -1,8 +1,12 @@ +import { Callout } from 'nextra-theme-docs' + # The PoW Solution on Namada In order to combat the "costlessness of blockspace" problem with a testnet, and hence prevent DOS attacks as a result, when a Namada account does not have the required fees to pay for a transaction, the user must complete a Proof of Work challenge. The difficulty of this challenge is a parameter set by governance, and will dictate the (average) computational expenditure needed in order to complete the challenge. -> Note that this current fix will be not be included in Mainnet as it is circumstantial to testnet. + +Note that this current fix will be not be included in Mainnet as it is circumstantial to testnet. + In order to avoid having to complete endless Proof of Work challenges, we recommend using the faucet to fund the implicit account as one of a user's first transactions: diff --git a/packages/docs/pages/ledger/customize.mdx b/packages/docs/pages/ledger/customize.mdx index 05c9efb3..936d7376 100644 --- a/packages/docs/pages/ledger/customize.mdx +++ b/packages/docs/pages/ledger/customize.mdx @@ -1,6 +1,12 @@ +import { Callout } from 'nextra-theme-docs' + # Customize accounts and transactions -> Note that these features are still a work in progress. At the time of writing, Namada does not allow for custom validity predicates (as there is a whitelist). Custom transactions are possible in certain cases (e.g governance proposals). + +Note that these features are still a work in progress. +At the time of writing, Namada does not allow for custom validity predicates (as there is a whitelist). +Custom transactions are possible in certain cases (e.g., governance proposals). + On this page, we'll cover how to tailor your account(s) to your use-case with custom-made validity predicates and transactions. diff --git a/packages/docs/pages/public-goods-stewards.mdx b/packages/docs/pages/public-goods-stewards.mdx index 3f369dd7..14ccc8d0 100644 --- a/packages/docs/pages/public-goods-stewards.mdx +++ b/packages/docs/pages/public-goods-stewards.mdx @@ -8,6 +8,6 @@ See the specs about the public goods funding [here](https://specs.namada.net/eco This documentation will cover: -1. [How to become a public goods steward](#./electing.md) -2. [How to submit a public goods funding proposal](#./proposing.md) -3. [How to vote on steward elections](./voting.md#stewards) as well as public goods funding proposal](#./voting.md) \ No newline at end of file +1. [How to become a public goods steward](./public-goods-stewards/electing.md). +2. [How to submit a public goods funding proposal](./public-goods-stewards/proposing.md) +3. [How to vote on steward elections](./public-goods-stewards/voting.md#voting-for-stewards) as well as [public goods funding proposal](./public-goods-stewards/voting.md#voting-for-pgf-proposals). \ No newline at end of file diff --git a/packages/docs/pages/public-goods-stewards/electing.mdx b/packages/docs/pages/public-goods-stewards/electing.mdx index 79fe89d5..16bcfa9e 100644 --- a/packages/docs/pages/public-goods-stewards/electing.mdx +++ b/packages/docs/pages/public-goods-stewards/electing.mdx @@ -51,15 +51,12 @@ In the motivation and abstract field, it is important to make clear what type of The CLI command to submit a proposal is: -```bash copy +```shell copy namadac init-proposal \ --pgf-stewards \ - --data-path \ + --data-path ``` - - -Where `` is the path to the `steward_proposal.json` file. - +where `` is the path to the `steward_proposal.json` file. ### Becoming elected diff --git a/packages/docs/pages/public-goods-stewards/proposing.mdx b/packages/docs/pages/public-goods-stewards/proposing.mdx index 840bacab..b4bd76bd 100644 --- a/packages/docs/pages/public-goods-stewards/proposing.mdx +++ b/packages/docs/pages/public-goods-stewards/proposing.mdx @@ -29,7 +29,7 @@ Below is an example of a `PGFProposal` that a steward could submit. Note that on { "target": { "amount": 420, - "address": "atestatest1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn" + "address": "" } "action" : "add", }, @@ -38,16 +38,14 @@ Below is an example of a `PGFProposal` that a steward could submit. Note that on { "target": { "amount": 1337, - "address": "atestatest1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn" + "address": "" } } ] }, } ``` - -The address in target should be changed to the address of the recipient of the funds. - +where `` should be changed to the address of the recipient of the funds. Save this file as `PGF_proposal.json` to some memorable path on your machine. @@ -58,7 +56,7 @@ In order to submit the proposal, the steward can use the following command: ```shell copy namada client init-proposal \ --pgf-proposal \ - --data-path PGF_proposal.json \ + --data-path PGF_proposal.json ``` The proposal will then be given a `proposal-id` which can be used to query the proposal. @@ -69,5 +67,5 @@ The command for querying the proposal is as follows: ```shell copy namada client query-proposal \ - --proposal-id \ + --proposal-id ``` \ No newline at end of file diff --git a/packages/docs/pages/users/an-introduction-to-namada-addresses.mdx b/packages/docs/pages/users/an-introduction-to-namada-addresses.mdx index 6002f63a..d7c96557 100644 --- a/packages/docs/pages/users/an-introduction-to-namada-addresses.mdx +++ b/packages/docs/pages/users/an-introduction-to-namada-addresses.mdx @@ -1,3 +1,5 @@ +import { Callout } from 'nextra-theme-docs' + # An Introduction to Namada Addresses All accounts in Namada have a unique address, exactly one Validity Predicate and optionally any additional data in its dynamic storage sub-space. @@ -25,9 +27,11 @@ It is possible to generate keys using the CLI. By doing so, an implicit account namada wallet key gen --alias keysha ``` -> The derived implicit address shares the same `keysha` alias. The previous command has the same effect as `namada wallet address gen --alias keysha`. + +The derived implicit address shares the same `keysha` alias. The previous command has the same effect as `namada wallet address gen --alias keysha`. + -By default, the keys are stored in encrypted form. +By default, the keys are stored encrypted. The encryption password is _not_ a part of key generation randomness. Namada wallet supports keypair generation using a [mnemonic code](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) and [HD derivation path](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki). @@ -36,12 +40,16 @@ To generate a keypair for a default path use namada wallet key gen --alias keysha --hd-path default ``` -> The default HD path for Namada is `m/44'/877'/0'/0'/0'`. + +The default HD path for Namada is `m/44'/877'/0'/0'/0'`. + -Optionally, the user may specialize an additional passphrase that _is used_ as a part of keypair generation randomness. +Optionally, the user may specify an additional passphrase that _is used_ as a part of keypair generation randomness. -> WARNING: Keep your mnemonic code and passphrase safe. -> Loss of any of them would inevitably lead to the impossibility of the account recovery. + +WARNING: Keep your mnemonic code and passphrase safe. +Loss of any of them would inevitably lead to the impossibility of the account recovery. + ### Restore the keypair @@ -72,14 +80,16 @@ Let's call the implicit address `accountant`: namada wallet address gen --alias accountant ``` -> Note that this will also generate and save a key from which the address was derived and save it under the same `accountant` alias. Thus, this command has the same effect as `namada wallet key gen --alias accountant`. + +Note that this will also generate and save a key from which the address was derived and save it under the same `accountant` alias. Thus, this command has the same effect as `namada wallet key gen --alias accountant`. + ```shell copy namada wallet address gen --alias keysha --hd-path default ``` generates an address using a [mnemonic code](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) and [HD derivation path](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki). -### Restore the keypair +### Restore the address ```shell copy namada wallet address restore --alias keysha --hd-path default diff --git a/packages/docs/pages/users/send-and-receive-nam-tokens.mdx b/packages/docs/pages/users/send-and-receive-nam-tokens.mdx index 8327f453..d6c0e010 100644 --- a/packages/docs/pages/users/send-and-receive-nam-tokens.mdx +++ b/packages/docs/pages/users/send-and-receive-nam-tokens.mdx @@ -1,8 +1,9 @@ import { Callout } from 'nextra-theme-docs' -# Send & Receive NAM tokens +# Send and Receive NAM tokens -In Namada, tokens are implemented as accounts with the [Token Validity Predicate](https://github.com/anoma/namada/blob/namada/wasm/wasm_source/src/vp_token.rs). The validity predicate (VP) checks that the total supply (of the token) is preserved in any transaction that uses this token. Your wallet will be pre-loaded with some token addresses that are initialized in the genesis block. +In Namada, tokens are implemented as accounts with the [Token Validity Predicate](https://github.com/anoma/namada/blob/main/wasm/wasm_source/src/vp_token.rs). +The validity predicate (VP) checks, in particular, that the total supply (of the token) is preserved in any transaction that uses this token. Your wallet will be pre-loaded with some token addresses that are initialized in the genesis block. ### Initialize an established account @@ -17,9 +18,9 @@ namada client init-account \ --source keysha ``` -Once this transaction has been applied, the client will automatically see the new address created by the transaction and add it to your Wallet with the chosen alias `establishment`. +Once this transaction has been applied, the client will automatically see the new address created by the transaction and add it to your wallet with the chosen alias `establishment`. -This command uses the prebuilt [User Validity Predicate](https://github.com/anoma/namada/blob/namada/wasm/wasm_source/src/vp_token.rs). +This command uses the prebuilt [User Validity Predicate](https://github.com/anoma/namada/blob/main/wasm/wasm_source/src/vp_user.rs). ### Send a Payment diff --git a/packages/docs/pages/users/shielded-transfers.mdx b/packages/docs/pages/users/shielded-transfers.mdx index 0fc5548f..7e0bea8a 100644 --- a/packages/docs/pages/users/shielded-transfers.mdx +++ b/packages/docs/pages/users/shielded-transfers.mdx @@ -2,7 +2,8 @@ import { Callout } from 'nextra-theme-docs' # Shielded Transfers -In Namada, shielded transfers are enabled by the [Multi-Asset Shielded Pool](https://specs.namada.net/masp/ledger-integration.html?highlight=MASP#masp-integration-spec) (MASP). The MASP is a zero-knowledge circuit (zk-SNARK) that extends the Zcash Sapling circuit to add support for sending arbitrary assets. All assets in the pool share the same anonymity set, this means that the more transactions are issued to MASP, the stronger are the privacity guarantees. +In Namada, shielded transfers are enabled by the [Multi-Asset Shielded Pool](https://specs.namada.net/masp/ledger-integration.html?highlight=MASP#masp-integration-spec) (MASP). +The MASP is a zero-knowledge circuit ([zk-SNARK](https://en.wikipedia.org/wiki/Non-interactive_zero-knowledge_proof)) that extends the [Zcash Sapling circuit](https://raw.githubusercontent.com/zcash/zips/master/protocol/sapling.pdf) to add support for sending arbitrary assets. All assets in the pool share the same anonymity set, this means that the more transactions are issued to MASP, the stronger are the privacity guarantees. ## Using MASP @@ -12,18 +13,15 @@ If you are familiar with Zcash, the set of interactions you can execute with the - [**Shielded transfers:** shielded to shielded addresses](#shielded-transfers) - [**Unshielding transfers:** shielded to transparent addresses](#unshielding-transfers) -```admonish info "Lexicon" +We distinguish two kinds of keys: - A **Spending Key** is a type of private key that allows any user in possession of it to spend the balance of the associated address. For shielded addresses, possessing the Spending Key also allows the user to view the address’ balance and transaction data. - A **Viewing Key** allows any user in possession of it to view and disclose transaction details. It is derived from the Spending Key and hold the same alias. -``` -### Shielded transfers +### Shielding transfers To try out shielded transfers, you first need to be in possession of a transparent account with some token balance. - - #### Generate your Spending Key You can randomly generate a new Spending Key with: @@ -32,10 +30,10 @@ You can randomly generate a new Spending Key with: namadaw masp gen-key --alias ``` -```admonish info + This command will also generate a corresponding Viewing Key sharing the same alias. -``` + #### Create a new payment address @@ -61,7 +59,7 @@ namadac transfer \ --source \ --target \ --token btc \ - --amount 100 + --amount ``` #### View your balance @@ -81,9 +79,9 @@ another shielded address: ```shell copy namadac transfer \ --source \ - --target [some-payment-address] \ + --target \ --token btc \ - --amount 50 \ + --amount \ --signer ``` @@ -94,9 +92,9 @@ You can also transfer back your balance to a transparent account: ```shell copy namadac transfer \ --source \ - --target [some-transparent-address-alias> \ + --target \ --token btc \ - --amount 50 \ + --amount \ --signer ``` @@ -109,7 +107,7 @@ When the client generates a spending key, it automatically derives a viewing key #### Payment Address Generation -Payment addresses can be derived from both spending keys as well as viewing keys. The payment address acts as a destination address in which any tokens received by this address is spendable by the corresponding spending key. Only the payment address's spending key and viewing key are able to spend and view the payment address's balance, respectively. Below are examples of how payment addresses can be +Payment addresses can be derived from both spending keys as well as viewing keys. The payment address acts as a destination address in which any tokens received by this address is spendable by the corresponding spending key. Only the payment address' spending key and viewing key are able to spend and view the payment address's balance, respectively. Below are examples of how payment addresses can be generated: ``` diff --git a/packages/docs/pages/validators.mdx b/packages/docs/pages/validators.mdx index f747508e..6fd8d3ab 100644 --- a/packages/docs/pages/validators.mdx +++ b/packages/docs/pages/validators.mdx @@ -13,10 +13,10 @@ A post-genesis validator, on the other hand, is a validating account which was c #### Pre-requisites Validators require stake in the form of NAM in order to participate in the consensus process. The amount of stake required is specified in the genesis file. In order to become a validator, you must have at least the minimum amount of stake required. -In addition, the validator node must meet the [minimum hardware requirements](./validators/hardware.md) +In addition, the validator node must meet the [minimum hardware requirements](./validators/hardware.md). #### Steps -See these steps for [setting up a genesis validator](./validators/genesis-validator-setup.md) +See these steps for [setting up a genesis validator](./validators/genesis-validator-setup.md). -See these steps for [setting up a post-genesis validator](./validators/post-genesis-validator-setup.md) \ No newline at end of file +See these steps for [setting up a post-genesis validator](./validators/post-genesis-validator-setup.md). \ No newline at end of file diff --git a/packages/docs/pages/validators/genesis-validator-setup.mdx b/packages/docs/pages/validators/genesis-validator-setup.mdx index a87a87de..5d64de55 100644 --- a/packages/docs/pages/validators/genesis-validator-setup.mdx +++ b/packages/docs/pages/validators/genesis-validator-setup.mdx @@ -2,7 +2,7 @@ import { Callout } from 'nextra-theme-docs' # Genesis validator setup -A genesis validator is one which is a validator right from the first block of the chain - i.e. at genesis. The details of genesis validators are hardcoded into the genesis file that is distributed to all users who want to interact with a chain. +A genesis validator is one which is a validator right from the first block of the chain, i.e., at genesis. The details of genesis validators are hardcoded into the genesis file that is distributed to all users who want to interact with a chain. ### Prerequisites @@ -26,16 +26,17 @@ namada client utils init-genesis-validator --alias $ALIAS \ ### 2. After generating your keys, the command will print something like this: - + If you have set the variable $XDG_DATA_HOME this is where the pre-genesis TOML will be written to. Otherwise see below for the default locations. #### Linux -```shell copy +```text copy Pre-genesis TOML written to $HOME/.local/share/namada ``` + #### MacOS -```shell copy +```text copy Pre-genesis TOML written to /Users/$USER/Library/Application\ Support/Namada ``` @@ -57,15 +58,20 @@ Note that the wallet containing your private keys will also be written into this ### 4. You can print the validator.toml by running: ### Linux -`cat $HOME/.local/share/namada/pre-genesis/$ALIAS/validator.toml` +```shell copy +cat $HOME/.local/share/namada/pre-genesis/$ALIAS/validator.toml +``` + ### MacOS -`cat $HOME/Library/Application\ Support/Namada/pre-genesis/$ALIAS/validator.toml` +```shell copy +cat $HOME/Library/Application\ Support/Namada/pre-genesis/$ALIAS/validator.toml +``` ## Required keys - Account key: Can be used to sign transactions that require authorization in the default validator validity predicate, such as a balance transfer. - Staking rewards key: Can be used to sign transactions on the PoS staking rewards account. - Protocol key: This key is used by the validator's ledger itself to sign protocol transaction on behalf of the validator. -- DKG key: Special key needed for participation in the DKG protocol -- Consensus key: Used in Cometbft consensus layer. Currently, this key is written to a file which is read by Cometbft. -- Cometbft node key: This key is used to derive Cometbft node ID for P2P connection authentication. This key is also written to a file which is read by Cometbft. +- DKG key: Special key needed for participation in the DKG protocol. +- Consensus key: Used in CometBFT consensus layer. Currently, this key is written to a file which is read by CometBFT. +- CometBFT node key: This key is used to derive CometBFT node ID for P2P connection authentication. This key is also written to a file which is read by CometBFT. diff --git a/packages/docs/pages/validators/run-your-genesis-validator.mdx b/packages/docs/pages/validators/run-your-genesis-validator.mdx index 4160342b..6a8b72af 100644 --- a/packages/docs/pages/validators/run-your-genesis-validator.mdx +++ b/packages/docs/pages/validators/run-your-genesis-validator.mdx @@ -7,7 +7,7 @@ As a genesis validator, it is then possible to join the network with the `CHAIN_ In this case, the genesis validator can join the network with: -``` bash +``` bash copy export CHAIN_ID="namada-mainnet" namada client utils join-network \ --chain-id $CHAIN_ID --genesis-validator $ALIAS