diff --git a/packages/docs/components/Expandable.tsx b/packages/docs/components/Expandable.tsx new file mode 100644 index 00000000..e8b00f6a --- /dev/null +++ b/packages/docs/components/Expandable.tsx @@ -0,0 +1,56 @@ +import clsx from "clsx"; +import { useState, useRef} from "react"; + +const Expandable = ({ children }) => { + const [expanded, setExpanded] = useState(false); + const containerRef = useRef(null); + + const toggleExpand = () => { + setExpanded(!expanded); + if (!expanded) { + containerRef.current.scrollIntoView({ behavior: "smooth" }); + } + }; + + const styles = { + collapsed: { + height: "200px", + WebkitMaskImage: `linear-gradient(rgba(0, 0, 0, 1) 65%, transparent 100%)`, + maskImage: `linear-gradient(rgba(0, 0, 0, 1) 65%, transparent 100%)`, + }, + expanded: { + height: "auto", + }, + }; + +return ( +
+
+ {children} +
+ + +
+ ); +}; + +export default Expandable; diff --git a/packages/docs/next.config.js b/packages/docs/next.config.js index adf14f38..4d04e042 100644 --- a/packages/docs/next.config.js +++ b/packages/docs/next.config.js @@ -1,7 +1,17 @@ const withNextra = require("nextra")({ theme: "nextra-theme-docs", themeConfig: "./theme.config.tsx", - latex: true + latex: true, + markdown: { + // options for markdown-it-anchor + anchor: { permalink: false }, + // options for markdown-it-toc + toc: { includeLevel: [1, 2] }, + extendMarkdown: (md) => { + // use more markdown-it plugins! + md.use(require("markdown-it-xxx")); + }, + }, }); module.exports = { @@ -9,14 +19,4 @@ module.exports = { images: { unoptimized: true, }, - markdown: { - // options for markdown-it-anchor - anchor: { permalink: false }, - // options for markdown-it-toc - toc: { includeLevel: [1, 2] }, - extendMarkdown: md => { - // use more markdown-it plugins! - md.use(require('markdown-it-xxx')) - } - } }; diff --git a/packages/docs/pages/_meta.json b/packages/docs/pages/_meta.json index 9873a475..ebdebf5c 100644 --- a/packages/docs/pages/_meta.json +++ b/packages/docs/pages/_meta.json @@ -1,8 +1,7 @@ { "index": "Namada", "introduction": "Introduction", - "running-a-full-node": "Full nodes", - "ledger": "Running the ledger", + "ledger": "Full nodes", "validators": "Validators", "delegators": "Delegators", "users": "(Power) Users", diff --git a/packages/docs/pages/introduction/quick-start.mdx b/packages/docs/pages/introduction/quick-start.mdx index 63551c21..b84bf464 100644 --- a/packages/docs/pages/introduction/quick-start.mdx +++ b/packages/docs/pages/introduction/quick-start.mdx @@ -1,4 +1,4 @@ -# Quickstart +# Quickstart ## About this guide @@ -34,7 +34,8 @@ namadan ledger run # can detach the tmux (Ctrl-B then D) ``` -For a more verbose output, one can run +For a more verbose output, one can run + ```shell copy NAMADA_LOG=info TM_LOG_LEVEL=p2p:none,pex:error NAMADA_CMT_STDOUT=true namada ledger ``` @@ -42,11 +43,13 @@ NAMADA_LOG=info TM_LOG_LEVEL=p2p:none,pex:error NAMADA_CMT_STDOUT=true namada le This should sync your node to the ledger and will take a while (depending on your machine's hardware as well as the time between genesis and the start of sync). Subsequent commands (generating an account, etc.) are unlikely to work until your node is fully synced. Enquire the current block height with other participants to make sure you are synced in order to proceed. ## Generate an account and grab some tokens + First you will need an implicit account in order to receive tokens. You can generate one with: ```shell copy namadaw address gen --alias ``` + For the remainder of this introduction, let's assume your go-to alias is `stanley`. This will generate a new account and store it in the default keychain. You can see the account with: @@ -55,9 +58,10 @@ This will generate a new account and store it in the default keychain. You can s namadaw address list ``` -{/* #TODO: ADD some output */ } +{/* #TODO: ADD some output */} ## Grabbing the tokens (testnet only) + The "faucet" is a native established account on Namada that is willing to give a maximum of 1000 tokens to any user at request. Let's transfer ourselves `1000 NAM` from the faucet with the same alias using: ```shell copy @@ -77,4 +81,5 @@ namadac balance \ ``` ## 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). diff --git a/packages/docs/pages/introduction/testnets.mdx b/packages/docs/pages/introduction/testnets.mdx index b56890f7..edb75a59 100644 --- a/packages/docs/pages/introduction/testnets.mdx +++ b/packages/docs/pages/introduction/testnets.mdx @@ -19,7 +19,7 @@ If you find a bug, please submit an issue with the `bug` [issue template](https: 3. [Pre-genesis validator setup](../../validators/genesis-validator-setup.md) 4. [Pre-genesis validator apply](./testnets/genesis-validator-apply.md) 5. [Running your genesis validator](../../validators/run-your-genesis-validator.md) -6. [Running a full node](../../running-a-full-node.md) +6. [Running a full node](../../ledger/running-a-full-node.md) 7. [Becoming a validator post-genesis](./testnets/post-genesis-validator.md) ![testnet_flowchart](/images/testnet_flowchart.png) diff --git a/packages/docs/pages/introduction/testnets/joining-the-testnet.mdx b/packages/docs/pages/introduction/testnets/joining-the-testnet.mdx index 8199fb4f..56935ae6 100644 --- a/packages/docs/pages/introduction/testnets/joining-the-testnet.mdx +++ b/packages/docs/pages/introduction/testnets/joining-the-testnet.mdx @@ -8,7 +8,7 @@ Joining the testnet validator is identical to that of a mainnet validator. For this reason, please refer to [these docs](../../validators/run-your-genesis-validator.md). ## Joining as a full node -If you are not a genesis validator, please follow the steps for [joining as a full node](../../running-a-full-node.md). +If you are not a genesis validator, please follow the steps for [joining as a full node](../../ledger/running-a-full-node.md). It is then possible to test being a validator by [becoming a post-genesis validator](./post-genesis-validator.md). diff --git a/packages/docs/pages/introduction/testnets/post-genesis-validator.mdx b/packages/docs/pages/introduction/testnets/post-genesis-validator.mdx index 5933f5ae..e7556f8e 100644 --- a/packages/docs/pages/introduction/testnets/post-genesis-validator.mdx +++ b/packages/docs/pages/introduction/testnets/post-genesis-validator.mdx @@ -2,7 +2,7 @@ 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](../../running-a-full-node.md), you must [create a validator account](../../validators/post-genesis-validator-setup.md). +After [joining the network as a full node](../../ledger/running-a-full-node.md), you must [create a validator account](../../validators/post-genesis-validator-setup.md). 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. diff --git a/packages/docs/pages/introduction/testnets/pre-genesis.mdx b/packages/docs/pages/introduction/testnets/pre-genesis.mdx index d24e786f..34df5232 100644 --- a/packages/docs/pages/introduction/testnets/pre-genesis.mdx +++ b/packages/docs/pages/introduction/testnets/pre-genesis.mdx @@ -6,4 +6,4 @@ At genesis, there will be a set of validators with a pre-defined amount of token 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). -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](../../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.md). If you still wish to validate, you can follow the steps to [become a post-genesis-validator](./post-genesis-validator.md). diff --git a/packages/docs/pages/introduction/testnets/upgrades.mdx b/packages/docs/pages/introduction/testnets/upgrades.mdx index b5781e7a..ccf9d8d0 100644 --- a/packages/docs/pages/introduction/testnets/upgrades.mdx +++ b/packages/docs/pages/introduction/testnets/upgrades.mdx @@ -13,7 +13,7 @@ No upgrade needed on `public-testnet-9` (yet). The testnet launches on 20/06/2023 at 17:00 UTC with the genesis validators from `public-testnet-9`. It launches with [version v0.17.3](https://github.com/anoma/namada/releases/tag/v0.17.3) and chain-id `TBD`. If your genesis transaction is contained in [this folder](https://github.com/anoma/namada-testnets/tree/main/namada-public-testnet-9), you are one of the genesis validators. In order for the testnet to come online, at least 2/3 of those validators need to be online. -The installation docs are updated and can be found [here](./environment-setup.md). The running docs for validators/full nodes can be found [here](../../running-a-full-node.md). +The installation docs are updated and can be found [here](./environment-setup.md). The running docs for validators/full nodes can be found [here](../../ledger/running-a-full-node.md). ## Previous upgrades: @@ -32,7 +32,7 @@ The intended fix to solve the storage issue was only partially solved. This led The testnet launches on 29/03/2023 at 17:00 UTC with the genesis validators from `public-testnet-6`. It launches with [version v0.14.3](https://github.com/anoma/namada/releases/tag/v0.14.3) and chain-id `public-testnet-6.0.a0266444b06`. If your genesis transaction is contained in [this folder](https://github.com/anoma/namada-testnets/tree/main/namada-public-testnet-5), you are one of the genesis validators. In order for the testnet to come online, at least 2/3 of those validators need to be online. -The installation docs are updated and can be found [here](./environment-setup.md). The running docs for validators/full nodes can be found [here](../../running-a-full-node.md). +The installation docs are updated and can be found [here](./environment-setup.md). The running docs for validators/full nodes can be found [here](../../ledger/running-a-full-node.md). ***13/02/2023*** `public-testnet-3` diff --git a/packages/docs/pages/ledger.mdx b/packages/docs/pages/ledger.mdx index f79cb259..0ffa6bf7 100644 --- a/packages/docs/pages/ledger.mdx +++ b/packages/docs/pages/ledger.mdx @@ -2,7 +2,9 @@ import { Callout } from 'nextra-theme-docs' # The Namada Ledger -To start a local Namada ledger node, run: +In order to make any interactions with the Namada blockchain through the Namada *client* `namadac`, the ledger must be running. + +To start a local Namada ledger node, one can run: ```shell copy namada ledger @@ -15,38 +17,27 @@ The node will attempt to connect to the persistent validator nodes and other pee By default, the ledger will store its configuration and state in your [base directory](./introduction/base-directory.md). 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: ```shell copy export BASE_DIR=$(namadac utils default-base-dir) ``` + -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. This can also be set with the `--wasm-dir` CLI global argument, `NAMADA_WASM_DIR` environment variable or the configuration file. +When the ledger is run for the first time, the MASP-parameters will be downloaded. This is essential for producing the zero knowledge proofs required to make shielded transactions. -The ledger configuration is stored in `$BASE_DIR/{chain_id}/config.toml` (with +### The ledger wasm files +The ledger will also download the genesis block, which contains the initial state of the blockchain. +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. + +### 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. +via [environment variables](./ledger/env-vars.md). -Names of the recognized environment variables are -derived from the configuration keys by: uppercase every letter of the key, -insert `.` or `__` for each nested value and prepend `NAMADA_`. For example, -option `p2p_pex` in `[ledger.cometbft]` can be set by -```shell copy -NAMADA_LEDGER__COMETBFT__P2P_PEX=true # or false, depending on your heart's desires -``` -or -```shell copy -NAMADA_LEDGER.COMETBFT.P2P_PEX=true # or false, depending on your heart's desires -``` -in the environment - - -**Note**: -Only the double underscore form can be -used in Bash, because Bash doesn't allow dots in -environment variable names - diff --git a/packages/docs/pages/ledger/_meta.json b/packages/docs/pages/ledger/_meta.json new file mode 100644 index 00000000..22eac3fe --- /dev/null +++ b/packages/docs/pages/ledger/_meta.json @@ -0,0 +1,4 @@ +{ + "env-vars": "Environment variables", + "running-a-full-node": "Running a full node" +} \ No newline at end of file diff --git a/packages/docs/pages/ledger/env-vars.mdx b/packages/docs/pages/ledger/env-vars.mdx new file mode 100644 index 00000000..28627f1d --- /dev/null +++ b/packages/docs/pages/ledger/env-vars.mdx @@ -0,0 +1,147 @@ +import { Callout } from 'nextra-theme-docs' +import Expandable from "../../components/Expandable"; // TODO: Use this component when properly css'd + +# Environment variables + +By default, whenever the namada ledger is started, it will apply the confirguration found in the ledger configuration file. + +An example of a ledger configuration file is displayed below. + + +```toml +wasm_dir = "wasm" + +[ledger] +genesis_time = "2023-06-29T17:00:00+00:00" +chain_id = "" + +[ledger.shell] +base_dir = "/Users/fraccaman/Library/Application Support/Namada" +storage_read_past_height_limit = 3600 +db_dir = "db" +cometbft_dir = "cometbft" +tendermint_mode = "Full" + +[ledger.cometbft] +proxy_app = "tcp://127.0.0.1:26658" +moniker = "1337-leet-1337" +db_backend = "goleveldb" +db_dir = "data" +log_level = "info" +log_format = "plain" +genesis_file = "config/genesis.json" +node_key_file = "config/node_key.json" +abci = "socket" +filter_peers = false +priv_validator_key_file = "config/priv_validator_key.json" +priv_validator_state_file = "data/priv_validator_state.json" +priv_validator_laddr = "" + +[ledger.cometbft.rpc] +laddr = "tcp://127.0.0.1:26657" +cors_allowed_origins = [] +cors_allowed_methods = ["HEAD", "GET", "POST"] +cors_allowed_headers = ["Origin", "Accept", "Content-Type", "X-Requested-With", "X-Server-Time"] +unsafe = false +max_open_connections = 900 +max_subscription_clients = 100 +max_subscriptions_per_client = 5 +timeout_broadcast_tx_commit = "10000ms" +max_body_bytes = 1000000 +max_header_bytes = 1048576 +tls_cert_file = "" +tls_key_file = "" +pprof_laddr = "" + +[ledger.cometbft.p2p] +laddr = "tcp://0.0.0.0:26656" +external_address = "" +seeds = "" +persistent_peers = "@:, ..." +upnp = false +addr_book_file = "config/addrbook.json" +addr_book_strict = true +max_num_inbound_peers = 40 +max_num_outbound_peers = 10 +unconditional_peer_ids = "" +persistent_peers_max_dial_period = "0ms" +flush_throttle_timeout = "100ms" +max_packet_msg_payload_size = 1024 +send_rate = 5120000 +recv_rate = 5120000 +pex = true +seed_mode = false +private_peer_ids = "" +allow_duplicate_ip = false +handshake_timeout = "20000ms" +dial_timeout = "3000ms" + +[ledger.cometbft.mempool] +recheck = true +broadcast = true +wal_dir = "" +size = 5000 +max_txs_bytes = 1073741824 +cache_size = 10000 +keep-invalid-txs-in-cache = false +max_tx_bytes = 1048576 +max_batch_bytes = 0 + +[ledger.cometbft.consensus] +wal_file = "data/cs.wal/wal" +double_sign_check_height = 0 +create_empty_blocks = true +create_empty_blocks_interval = "0ms" +peer_gossip_sleep_duration = "100ms" +peer_query_maj23_sleep_duration = "2000ms" +timeout_propose = "3000ms" +timeout_propose_delta = "500ms" +timeout_prevote = "1000ms" +timeout_prevote_delta = "500ms" +timeout_precommit = "1000ms" +timeout_precommit_delta = "500ms" +timeout_commit = "10000ms" + +[ledger.cometbft.tx_index] +indexer = "null" + +[ledger.cometbft.instrumentation] +prometheus = false +prometheus_listen_addr = ":26660" +max_open_connections = 3 +namespace = "namada_tm" + +[ledger.cometbft.statesync] +enable = false +rpc_servers = "" +trust_height = 0 +trust_hash = "" +trust_period = "168h0m0s" +discovery_time = "15000ms" +temp_dir = "" +``` + + +However, it is possible to override the configuration by setting environment variables. +Any variable found in the config can be accessed through environment variables that are constructed in the below manner. + +### Constructing environment variables +Names of the recognized environment variables are derived from the configuration keys by: + +1. Prepend `NAMADA_` to the key +2. Uppercase every letter of the key. For example `p2p_pex` becomes `P2P_PEX` +3. Insert a `__` for each nested value. For example, `ledger.cometbft` becomes `LEDGER__COMETBFT` + +Hence, the option `p2p_pex` in `[ledger.cometbft]` can be set by +```shell copy +NAMADA_LEDGER__COMETBFT__P2P_PEX=true # or false, depending on your heart's desires +``` +in the environment + + +**Note**: +In principle, even `.` can be used for environment variable names. +However, in Bash, only the double underscore form can be +used, because Bash doesn't allow dots in environment variable names. +Therefore, we omit the dot form. + \ No newline at end of file diff --git a/packages/docs/pages/running-a-full-node.mdx b/packages/docs/pages/ledger/running-a-full-node.mdx similarity index 100% rename from packages/docs/pages/running-a-full-node.mdx rename to packages/docs/pages/ledger/running-a-full-node.mdx