diff --git a/docs/gno-infrastructure/premining-balances.md b/docs/gno-infrastructure/premining-balances.md index b174398c29e..4f855a307dd 100644 --- a/docs/gno-infrastructure/premining-balances.md +++ b/docs/gno-infrastructure/premining-balances.md @@ -15,7 +15,7 @@ have ample funds to interact with the chain and facilitate contract deployments. ## Prerequisites -- **`gnoland` set up. Reference the [Setting up a local chain](setting-up-a-local-chain.md#installation) guide for steps** +- **`gnoland` set up. Reference the [Setting up a local chain](validators/setting-up-a-local-chain.md#installation) guide for steps** - **`gnokey` set up. Reference the [Installation](../getting-started/local-setup/installation.md#2-installing-the-required-tools-) guide for steps** diff --git a/docs/gno-infrastructure/validators/connect-to-existing-chain.md b/docs/gno-infrastructure/validators/connect-to-existing-chain.md new file mode 100644 index 00000000000..fd70fa77852 --- /dev/null +++ b/docs/gno-infrastructure/validators/connect-to-existing-chain.md @@ -0,0 +1,110 @@ +--- +id: validators-connect-to-and-existing-gno-chain +--- + +# Connect to an Existing Gno Chain + +## Overview + +In this tutorial, you will learn how to start a local Gno node and connect to an existing Gno chain (like a testnet). + +## Prerequisites + +- **Git** +- **`make` (for running Makefiles)** +- **Go 1.21+** +- **Go Environment Setup**: Ensure you have Go set up as outlined in + the [Go official installation documentation](https://go.dev/doc/install) for your environment + +## 1. Initialize the node directory + +To initialize a new Gno.land node working directory (configuration and secrets), make sure to +follow [Step 1](setting-up-a-new-chain#1-generate-the-node-directory-secrets--config) from the +chain setup tutorial. + +## 2. Obtain the `genesis.json` of the remote chain + +The genesis file of target chain is required in order to initialize the local node. + +:::info + +The genesis file will +be [easily downloadable from GitHub](https://github.com/gnolang/gno/issues/1836#issuecomment-2049428623) in the future. + +For now, obtain the file by + +1. Sharing via scp or ftp +2. Fetching it from `{chain_rpc:26657}/genesis` (might result in time-out error due to large file sizes) + +::: + +## 3. Confirm the validator information of the first node. + +```bash +gnoland secrets get node_id + +{ + "id": "g17h5t86vrztm6vuesx0xsyrg90wplj9mt9nsxng", + "p2p_address": "g17h5t86vrztm6vuesx0xsyrg90wplj9mt9nsxng@0.0.0.0:26656" +} +``` + +### Public IP of the Node + +You need the IP information about the network interface that you wish to connect from external nodes. + +If you wish to only connect from nodes in the same network, using a private IP should suffice. + +However, if you wish to connect from all nodes without any specific limitations, use your public IP. + +```bash +curl ifconfig.me/ip # GET PUBLIC IP + +# 1.2.3.4 # USE YOUR OWN PUBLIC IP +``` + +## 4. Configure the `persistent_peers` list + +We need to configure a list of nodes that your validators will always retain a connection with. +To get the local P2P address of the current node (these values should be obtained from remote peers): + +```bash +gnoland secrets get node_id.p2p_address + +"g17h5t86vrztm6vuesx0xsyrg90wplj9mt9nsxng@0.0.0.0:26656" +``` + +We can use this P2P address value to configure the `persistent_peers` configuration value + +```bash +gnoland config set p2p.persistent_peers "g19d8x6tcr2eyup9e2zwp9ydprm98l76gp66tmd6@1.2.3.4:26656" +``` + +## 5. Configure the seeds + +We should configure the list of seed nodes. Seed nodes provide information about other nodes for the validator to +connect with the chain, enabling a fast and stable initial connection. These seed nodes are also called _bootnodes_. + +:::warn + +The option to activate the Seed Mode from the node is currently missing. + +::: + +```bash +gnoland config set p2p.seeds "g19d8x6tcr2eyup9e2zwp9ydprm98l76gp66tmd6@1.2.3.4:26656" +``` + +## 6. Start the node + +Now that we've set up the local node configuration, and added peering info, we can start the Gno.land node: + +```shell +gnoland start \ +--genesis ./genesis.json \ +--data-dir ./gnoland-data +``` + +That's it! πŸŽ‰ + +Your new Gno node should be up and running, and syncing block data from the remote chain. \ No newline at end of file diff --git a/docs/gno-infrastructure/validators/faq.md b/docs/gno-infrastructure/validators/faq.md new file mode 100644 index 00000000000..0808c51969d --- /dev/null +++ b/docs/gno-infrastructure/validators/faq.md @@ -0,0 +1,182 @@ +--- +id: validators-faq +--- + +# Validators FAQ + +## General Concepts + +### What is a Gno.land validator? + +Gno.land is based on [Tendermint2](https://docs.gno.land/concepts/tendermint2) that relies on a set of validators +selected based on [Proof of Contribution](https://docs.gno.land/concepts/proof-of-contribution) (PoC) to secure the +network. Validators are tasked with participating in consensus by committing new blocks and broadcasting votes. +Validators are compensated with a portion of transaction fees generated in the network. In Gno.land, the voting power of +all validators are equally weighted to achieve a high nakamoto coefficient and fairness. + +### What is Tendermint2? + +[Tendermint2](https://docs.gno.land/concepts/tendermint2) (TM2) is the consensus protocol that powers Gno.land. TM2 is a +successor of [Tendermint Core](https://github.com/tendermint/tendermint2), a de facto consensus framework for building +Proof of Stake blockchains. The design philosophy of TM2 is to create β€œcomplete software” without any vulnerabilities +with development focused on minimalism, dependency removal, and modularity. + +### What is Proof of Contribution? + +[Proof of Contribution](https://docs.gno.land/concepts/proof-of-contribution) (PoC) is a novel consensus mechanism that +secures Gno.land. PoC weighs expertise and alignment with the project to evaluate the contribution of individuals or +teams who govern and operate the chain. Unlike Proof of Stake (PoS), validators are selected via governance of +Contributors based on their reputation and technical proficiency. The voting power of the network is equally distributed +across all validators for higher decentralization. A portion of all transaction fees paid to the network are evenly +shared between all validators to provide a fair incentive structure. + +### How does Gno.land differ from the Cosmos Hub? + +In Cosmos Hub, validators are selected based on the amount of staked `ATOM` tokens delegated. This means that anyone +with enough capital can join as a validator only to seek economic incentives without any alignment or technical +expertise. This system leads to an undesirable incentive structure in which validators are rewarded purely based on the +capital delegated, regardless of the quality of their infrastructure or service. + +On the contrary, validators in Gno.land must be reviewed and verified to have made significant contributions in order to +join the validator set. This property resembles the validator selection mechanism +in [Proof of Authority](https://openethereum.github.io/Proof-of-Authority-Chains). Furthermore, all validators are +evenly rewarded to ensure that the entire validator set is fairly incentivized to ensure the sustainability of the +network. + +### What stage is the Gno.land project in? + +Gno.land is currently in Testnet 3, the single-node testnet stage. The next version, Testnet 4, is scheduled to go live +in Q2 2024, which will include a validator set implementation for a multinode environment. + +## Becoming a Validator + +### How do I join the testnet as a validator? + +Out of many official Gno testnets, Testnet4 (`test4`) is the purpose-built network for testing the multi-node validator +environment prior to mainnet launch. Testnet4 is scheduled to go live in Q2 2024 with genesis validators consisting of +the Gno Core Team, partners, and external contributors. + +For more information about joining testnet4, +visit [the relevant issue](https://github.com/gnolang/hackerspace/issues/69). For more information about different +testnets, visit [Gno Testnets](https://docs.gno.land/concepts/testnets). + +### What are the incentives for running a validator? + +Network transaction fees paid on the Gno.land in `GNOT` are collected, from which a portion is directed to reward +validators for their work. All validators fairly receive an equal amount of rewards. + +### How many validators will there be in mainnet? + +The exact plans for mainnet are still TBD. Based on the latest discussions between contributors, the mainnet will likely +have an inital validator set size of 20~50, which will gradually scale with the development and decentralization of the +Gno.land project. + +### How do I make my first contribution? + +Gno.land is in active development and external contributions are always welcome! If you’re looking for tasks to begin +with, we suggest you visit +the [Bounties &](https://github.com/orgs/gnolang/projects/35/views/3) [Worx](https://github.com/orgs/gnolang/projects/35/views/3) +board and search for open tasks up for grabs. Start from small challenges and work your way up to the bigger ones. Every +contribution is acknowledged and highly regarded in PoC. We look forward to having you onboard as a new Contributor! + +## Technical Guides + +### What are the different types of keys? + +1. **Tendermint ( Tendermint2 ) Key :** A unique key used for voting in consensus during creation of blocks. A + Tendermint Key is also often called a Validator Key. It is automatically created when running + the `gnoland secrets init` command. A validator may check their Tendermint Key by running + the `gnoland secrets get validator_key` command. + +2. **User-owned keys :** A key that is generated when a new account is created using the `gnokey` command. It is used to + sign transactions. + +3. **Node Key :** A key used for communicating with other nodes. It is automatically created when running + the `gnoland secrets init` command. A validator may check their Node Key by running the `gnoland secrets get node_id` + command. + +### What is a full node and a pruned node? + +A full node fully validates transactions and blocks of a blockchain and keeps a full record of all historic activity. A +pruned node is a lighter node that processes only block headers and does not keep all historical data of the blockchain +post-verification. Pruned nodes are less resource intensive in terms of storage costs. Although validators may run +either a full node or a pruned node, it is important to retain enough blocks to be able to validate new blocks. + +## Technical References + +### How do I generate `genesis.json`? + +`genesis.json` is the file that is used to create the initial state of the chain. To generate `genesis.json`, use +the `gnoland genesis generate` command. Refer +to [this section](../../gno-tooling/cli/gnoland.md#gnoland-genesis-generate-flags) for various flags that allow you to +manipulate the file. + +:::warn + +Editing generated genesis.json manually is extremely dangerous. It may corrupt chain initial state which leads chain to +not start + +::: + +### How do I add or remove validators from `genesis.json`? + +Validators inside `genesis.json` will be included in the validator set at genesis. To manipulate the genesis validator +set, use the `gnoland genesis validator` command with the `add` or `remove` subcommands. Refer +to [this section](../../gno-tooling/cli/gnoland.md#gnoland-genesis-validator-flags) for flags that allow you to +configure the name or the voting power of the validator. + +### How do I add the balance information to the `genesis.json`? + +You may premine coins to various addresses. To modify the balances of addresses at genesis, use +the `gnoland genesis balances` command with the `add` or `remove` subcommands. Refer +to [this section](../../gno-tooling/cli/gnoland.md#gnoland-genesis-balances-add-flags) for various flags that allow you +to update the entire balance sheet with a file or modify the balance of a single address. + +:::info + +Not only `ugnot`, but other coins are accepted. However, be aware that coins other than `ugnot` may not work(send, and +etc.) properly. + +::: + +### How do I initialize `gno secrets`? + +The `gno secrets init` command allows you to initialize the private information required to run the validator, including +the validator node's private key, the state, and the node ID. Refer +to [this section](../../gno-tooling/cli/gnoland.md#gnoland-secrets-init-flags) for various flags that allow you to +define the output directory or to overwrite the existing secrets. + +### How do I get `gno secrets`? + +To retrieve the private information of your validator node, use the `gnoland-secrets-get` command. Refer +to [this section](../../gno-tooling/cli/gnoland.md#gnoland-secrets-get-flags) for a flag that allows you to define the +output directory. + +### How do I initialize the gno node configurations? + +To initialize the configurations required to run a node, use the `gnoland config init` command. Refer +to [this section](../../gno-tooling/cli/gnoland.md#gnoland-config-init-flags) for various flags that allow you to define +the path or to overwrite the existing configurations. + +### How do I get the current gno node configurations? + +To retrieve the specific values the current gno node configurations, use the `gnoland config get` command. Refer +to [this section](../../gno-tooling/cli/gnoland.md#gnoland-config-get) for a flag that allows you to define the path to +the configurations file. + +### How do I edit the gno node configurations? + +To edit the specific value of gno node configurations, use the `gnoland-config set` command. Refer +to [this section](../../gno-tooling/cli/gnoland.md#gnoland-config-set) for a flag that allows you to define the path to +the configurations file. + +### How do I initialize and start a new gno chain? + +To start an independent gno chain, follow the initialization process available +in [this section](./start-a-new-gno-chain-and-validator.md). + +### How do I connect to an existing gno chain? + +To join the validator set of a gno chain, you must first establish a connection. Refer +to [this section](./connect-to-an-existing-gno-chain.md) for a step-by-step guide on how to connect to an existing gno +chain. diff --git a/docs/gno-infrastructure/validators/overview.md b/docs/gno-infrastructure/validators/overview.md new file mode 100644 index 00000000000..9ae5104e010 --- /dev/null +++ b/docs/gno-infrastructure/validators/overview.md @@ -0,0 +1,98 @@ +--- +id: validators-overview +--- + +# Validator Overview + +## Introduction + +Gno.land is a blockchain powered by the Gno tech stack, which consists of +the [Gno Language](https://docs.gno.land/concepts/gno-language/) ( +Gno), [Tendermint2](https://docs.gno.land/concepts/tendermint2/) (TM2), +and [GnoVM](https://docs.gno.land/concepts/gnovm/). Unlike +existing [Proof of Stake](https://docs.cosmos.network/v0.46/modules/staking/) (PoS) blockchains in the Cosmos ecosystem, +Gno.land runs on [Proof of Contribution](https://docs.gno.land/concepts/proof-of-contribution/) (PoC), a novel +reputation-based consensus mechanism that values expertise and alignment with the project. In PoC, validators are +selected via governance based on their contribution to the project and technical proficiency. The voting power of the +network is equally distributed across all validators to achieve a high nakamoto coefficient. A portion of all +transaction fees paid to the network are evenly shared between all validators to provide a fair incentive structure. + +| **Blockchain** | Cosmos | Gno.land | +|--------------------------------------|-------------------------|-------------------------------| +| **Consensus Protocol** | Comet BFT | Tendermint2 | +| **Consensus Mechanism** | Proof of Stake | Proof of Contribution | +| **Requirement** | Delegation of Stake | Contribution | +| **Voting Power Reward Distribution** | Capital-based | Evenly-distributed | +| **Number of Validators** | 180 | 20~200 (gradually increasing) | +| **Virtual Machine** | N/A | GnoVM | +| **Tokenomics** | Inflationary (Dilutive) | Deflationary (Non-dilutive) | + +## Hardware Requirements + +The following minimum hardware requirements are recommended for running a validator node. + +- Memory: 16 GB RAM (Recommended: 32 GB) +- CPU: 2 cores (Recommended: 4 cores) +- Disk: 100 GB SSD (Depends on the level of pruning) + +:::warn + +These hardware requirements are currently approximate based on the Cosmos validator specifications. Final requirements +will be determined following thorough testing and optimization experiments in Testnet 4. + +::: + +## Good Validators + +Validators for Gno.land are trusted to demonstrate professionalism and responsibility. Below are best practices that can +be expected from a good, reliable validator. + +#### Ecosystem Contribution + +- Contributing to the core development of the Gno.land project +- Providing useful tools or infrastructure services (wallets, explorers, public RPCs, etc.) +- Creating educational materials to guide new members +- Localizing documentation or content to lower language or cultural barriers + +#### Quality Infrastructure + +- Strong connectivity, CPU, and memory setup +- Exercising technical stability by retaining a high uptime with a robust monitoring system +- Robust contingency plans with failover systems, storage backups, and redundant power supplies +- Geographical distribution of servers + +#### Transparency + +- Providing regular updates +- Engaging actively in community discussions +- Being accountable for any failures + +#### Compliance + +- Exercising legal compliance +- Consulting with legal experts to identify regulatory risks +- Conducting internal audits + +## Community + +Join the official Gno.land community in various channels to receive the latest updates about the project and actively +communicate with other validators and contributors. + +- [Gno.land Blog](https://gno.land/r/gnoland/blog) +- [Gno.land Discord](https://discord.gg/w2MpVEunxr) +- [Gno.land Twitter](https://x.com/_gnoland) + +:::info + +The validator set implementation in Gno.land is abstracted away from the consensus mechanism inside the `r/sys/vals` +realm. The realm is not production ready yet, and is still under active development. Proposals and contributions to +improve and complete the implementation are welcome. + +**Links to related efforts:** + +- Validator set injection through a Realm [[gnolang/gno #1823]](https://github.com/gnolang/gno/issues/1823) +- Add Validator Set Realm / Package [[gnolang/gno #1824](https://github.com/gnolang/gno/issues/1824) +- Add `/r/sys/vals` [[gnolang/gno #2130]](https://github.com/gnolang/gno/pull/2130) +- Add valset injection through `r/sys/vals` [[gnolang/gno #2229]](https://github.com/gnolang/gno/pull/2229) + +::: diff --git a/docs/gno-infrastructure/validators/running-a-validator.md b/docs/gno-infrastructure/validators/running-a-validator.md new file mode 100644 index 00000000000..37038d54a07 --- /dev/null +++ b/docs/gno-infrastructure/validators/running-a-validator.md @@ -0,0 +1,27 @@ +--- +id: validators-running-a-validator +--- + +# Running a Validator + +## Becoming a Gno.land validator + +The Gno.land blockchain is powered by the [Tendermint2](https://docs.gno.land/concepts/tendermint2) (TM2) consensus, +which involves committing of new blocks and broadcasting votes by multiple validators selected via governance +in [Proof of Contribution](https://docs.gno.land/concepts/proof-of-contribution) (PoC). While traditional Proof of +Stake (PoS) blockchains such as the Cosmos Hub required validators to secure a delegation of staked tokens to join the +validator set, no bonding of capital is involved in Gno.land. Rather, the validators on Gno.land are expected to +demonstrate their technical expertise and alignment with the project by making continuous, meaningful contributions to +the project. Furthermore, the voting power and the transaction fee rewards between validators are distributed evenly to +achieve higher decentralization. From a technical perspective, the validator set implementation in Gno.land as its +abstracted away into the `r/sys/vals` realm ([work in progress](https://github.com/gnolang/gno/issues/1824)), as a form +of smart-contract, for modularity, whereas existing blockchains include the validator management logic within the +consensus layer. + +# Start a New Gno Chain and a Validator + +- [start a new gno chain and a validator](./start-a-new-gno-chain-and-validator.md) + +# Connect to an Existing Gno Chain + +- [connect to an existing gno chain](./connect-to-an-existing-gno-chain.md) diff --git a/docs/gno-infrastructure/setting-up-a-local-chain.md b/docs/gno-infrastructure/validators/setting-up-a-new-chain.md similarity index 84% rename from docs/gno-infrastructure/setting-up-a-local-chain.md rename to docs/gno-infrastructure/validators/setting-up-a-new-chain.md index e4e3dced37e..2636a884a82 100644 --- a/docs/gno-infrastructure/setting-up-a-local-chain.md +++ b/docs/gno-infrastructure/validators/setting-up-a-new-chain.md @@ -1,5 +1,5 @@ --- -id: setting-up-a-local-chain +id: validators-setting-up-a-new-chain --- # Setting up a Local Chain @@ -40,22 +40,6 @@ it, run the `gnoland` command: gnoland --help ``` -If everything was successful, you should get the following output: - -```bash -❯ gnoland -USAGE - [flags] [...] - -starts the gnoland blockchain node. - -SUBCOMMANDS - start run the full node - secrets gno secrets manipulation suite - config gno config manipulation suite - genesis gno genesis manipulation suite -``` - If you do not wish to install the binary globally, you can build and run it with the following command from the `gno.land/` folder: @@ -77,7 +61,7 @@ gnoland start --lazy The command will trigger a chain initialization process (if you haven't run the node before), and start the Gno node, which is ready to accept transactions and interact with other Gno nodes. -![gnoland start](../assets/getting-started/local-setup/setting-up-a-local-chain/gnoland-start.gif) +![gnoland start](../../assets/getting-started/local-setup/setting-up-a-local-chain/gnoland-start.gif) :::info Lazy init @@ -169,10 +153,30 @@ gnoland config set rpc.laddr tcp://0.0.0.0:26657 This will update the RPC listen address to `0.0.0.0:26657`. You can verify the configuration was updated by running: -```go +```bash gnoland config get rpc.laddr + +# similar behavior for cosmos validator +# gaiad tx staking create-validator `--node string (default:tcp://localhost:26657)` +``` + +:::tip + +A moniker is a human-readable name of your Gno node. You may customize your moniker with the following +command: + +```bash +gnoland config set moniker node01 ``` +:::warn Modify existing secrets + +We can modify existing secrets, or utilize our own (if we have them backed up, for example) for the Gno.land node. +Each secret needs to be placed in the appropriate path within `/secrets`, and it can be replaced or +regenerated with `gnoland secrets init --force` + +::: + ### 2. Generate the `genesis.json` :::info Where's the `genesis.json`? @@ -183,6 +187,15 @@ trying to connect to. ::: +The `genesis.json` defines the initial genesis state for the chain. It contains information like: + +- the current validator set +- any predeployed transactions +- any premined balanced + +When the chain starts, the first block will be produced after all the init content inside the `genesis.json` is +executed. + Generating an empty `genesis.json` is relatively straightforward: ```shell @@ -234,7 +247,18 @@ FLAGS -output-path ./genesis.json the output path for the genesis.json ``` -### 3. Add the initial validator set +## 3. Add the `examples` packages into the `genesis.json` (optional) + +This step is not necessarily required, however, using a Gno.land chain without the `examples` packages predeployed can +present challenges with users who expect them to be present. + +The `examples` directory is located in the `$GNOROOT` location, or the local gno repository clone. + +```bash +gnoland genesis txs add packages ./examples +``` + +### 4. Add the initial validator set A new Gno chain cannot advance without an active validator set. Since this example follows starting a completely new Gno chain, you need to add at least one validator to the validator @@ -249,13 +273,13 @@ To display the generated node key data, run the following command: gnoland secrets get validator_key ``` -This will display the information we need for updating the `genesis.json`: +This will display the information we need for updating the `genesis.json`, in JSON: ```shell -[Validator Key Info] - -Address: g10e3smsmusjn00n7j75fk9u4zta8djrlglcv6af -Public Key: gpub1pggj7ard9eg82cjtv4u52epjx56nzwgjyg9zqhjhrqd7xlhda7spfdtx6lrcjxlk67av46w7eng9z4e2ch478fsk4xmq3j +{ + "address": "g14j4dlsh3jzgmhezzp9v8xp7wxs4mvyskuw5ljl", + "pub_key": "gpub1pggj7ard9eg82cjtv4u52epjx56nzwgjyg9zqaqle3fdduqul4slg6zllypq9r8gj4wlfucy6qfnzmjcgqv675kxjz8jvk" +} ``` Updating the `genesis.json` is relatively simple, running the following command will add the generated node info to the @@ -263,8 +287,8 @@ validator set: ```shell gnoland genesis validator add \ ---address g10e3smsmusjn00n7j75fk9u4zta8djrlglcv6af \ ---pub-key gpub1pggj7ard9eg82cjtv4u52epjx56nzwgjyg9zqhjhrqd7xlhda7spfdtx6lrcjxlk67av46w7eng9z4e2ch478fsk4xmq3j \ +--address g14j4dlsh3jzgmhezzp9v8xp7wxs4mvyskuw5ljl \ +--pub-key gpub1pggj7ard9eg82cjtv4u52epjx56nzwgjyg9zqaqle3fdduqul4slg6zllypq9r8gj4wlfucy6qfnzmjcgqv675kxjz8jvk \ --name Cuttlas ``` @@ -303,11 +327,12 @@ We can verify that the new validator was indeed added to the validator set: } ``` -### 4. Starting the chain +### 5. Starting the chain We have completed the main aspects of setting up a node: - generated the node directory (secrets and configuration) βœ… +- set the adequate configuration params βœ… - generated a `genesis.json` βœ… - added an initial validator set to the `genesis.json` βœ… @@ -323,7 +348,7 @@ That's it! πŸŽ‰ Your new Gno node (chain) should be up and running: -![gnoland start](../assets/getting-started/local-setup/setting-up-a-local-chain/gnoland-start-manual.gif) +![gnoland start](../../assets/getting-started/local-setup/setting-up-a-local-chain/gnoland-start-manual.gif) ## Chain runtime options diff --git a/docs/gno-tooling/cli/faucet/faucet.md b/docs/gno-tooling/cli/faucet/faucet.md index e1ec040cac1..8087d2855b6 100644 --- a/docs/gno-tooling/cli/faucet/faucet.md +++ b/docs/gno-tooling/cli/faucet/faucet.md @@ -26,7 +26,7 @@ the [Working with Key Pairs](../../../getting-started/local-setup/working-with-k ## 2. Start the local chain After ensuring the faucet address will have enough funds in the premine, we -can [run the local blockchain node](../../../gno-infrastructure/setting-up-a-local-chain.md). +can [run the local blockchain node](../../../gno-infrastructure/validators/setting-up-a-local-chain.md). Navigate to the `gno.land` sub-folder and run the appropriate make command: ```bash diff --git a/docs/gno-tooling/cli/gnoland.md b/docs/gno-tooling/cli/gnoland.md index 3d4ba9eac00..e4039e6cc0b 100644 --- a/docs/gno-tooling/cli/gnoland.md +++ b/docs/gno-tooling/cli/gnoland.md @@ -4,72 +4,375 @@ id: gno-tooling-gnoland # gnoland -## Overview +`gnoland` is the Gno.land blockchain client binary, which is capable of managing +node working files, as well as starting the blockchain client itself. -`gnoland` is the Gno.land blockchain client binary, which is capable of managing node working files, as well -as starting the blockchain client itself. +### gnoland start [flags] -## `gnoland init` +Starts the Gnoland blockchain node, with accompanying setup. -`gnoland init` is supposed to initialize the node's working directory in the given path. The node's data directory is -comprised initially from the node's secrets and config (default values). +#### FLAGS -It is meant to be an initial step in starting the gno blockchain client, as the client itself cannot run without secrets -data like private keys, and a configuration. When the blockchain client is started, it will initialize on its own -relevant DB working directories inside the node directory. +| Name | Type | Description | +|----------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `chainid` | String | The ID of the chain. (default: `dev`) | +| `data-dir` | String | The path to the node's data directory. This is an important folder. The chain may fail to start if this folder is contaminated. (default: `gnoland-data`) | +| `flag-config-path` | String | The flag config file (optional). | +| `genesis` | String | The path to the `genesis.json` file. (default: `genesis.json`) | +| `genesis-balance-file` | String | Initial distribution file. (default: `~/gno/gno.land/genesis/genesis_balances.txt`) | +| `genesis-max-vm-cycles` | Int | Sets maximum allowed vm cycles per operation. Zero means no limit. When increasing this option, the `block-max-gas` must also be increased to utilize the max cycles. (default: `100000000`) | +| `genesis-remote` | String | A replacement for `$$REMOTES%%` in genesis. (default: `localhost:26657`) | +| `genesis-txs-file` | String | Initial txs to replay. (default: ~/gno/gno.land/genesis/genesis_txs.jsonl) | +| `gnoroot-dir` | String | The root directory of the `gno` repository. (default: `~/gno`) | +| `lazy` | Boolean | Flag indication if lazy init is enabled. Generates the node secrets, configuration, and `genesis.json`. When set to `true`, you may start the chain without any initialization process, which comes in handy when developing. (default: `false`) | +| `log-format` | String | The log format for the gnoland node. (default: `console`) | +| `log-level` | String | The log level for the gnoland node. (default: `debug`) | +| `skip-failing-genesis-txs` | Boolean | Doesn’t panic when replaying invalid genesis txs. When starting a production-level chain, it is recommended to set this value to `true` to monitor and analyze failing transactions. (default: `false`) | -```shell -gnoland init --help +### gnoland genesis \ [flags] [\...] -USAGE - init [flags] +Gno `genesis.json` manipulation suite for managing genesis parameters. -initializes the node directory containing the secrets and configuration files +#### SUBCOMMANDS -FLAGS - -data-dir gnoland-data the path to the node's data directory - -force=false overwrite existing data, if any +| Name | Description | +|-------------|---------------------------------------------| +| `generate` | Generates a fresh `genesis.json`. | +| `validator` | Validator set management in `genesis.json`. | +| `verify` | Verifies a `genesis.json`. | +| `balances` | Manages `genesis.json` account balances. | +| `txs` | Manages the initial genesis transactions. | + +### gnoland genesis generate [flags] + +Generates a node's `genesis.json` based on specified parameters. + +#### FLAGS + +| Name | Type | Description | +|------------------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `block-max-data-bytes` | Int | The max size of the block data.(default: `2000000`) | +| `block-max-gas` | Int | The max gas limit for the block. (default: `100000000`) | +| `block-max-tx-bytes` | Int | The max size of the block transaction. (default: `1000000`) | +| `block-time-itoa` | Int | The block time itoa (in ms). (default: `100`) | +| `chain-id` | String | The ID of the chain. (default: `dev`) | +| `genesis-time` | Int | The genesis creation time. (default: `utc now timestamp`) | +| `output-path` : | String | The output path for the `genesis.json`. If the genesis-time of the Genesis File is set to a future time, the chain will automatically start at that time if the node is online. (default: `./genesis.json`) | + +### gnoland genesis validator \ [flags] + +Manipulates the `genesis.json` validator set. + +#### SUBCOMANDS + +| Name | Description | +|----------|----------------------------------------------| +| `add` | Adds a new validator to the `genesis.json`. | +| `remove` | Removes a validator from the `genesis.json`. | + +#### FLAGS + +| Name | Type | Description | +|----------------|--------|------------------------------------------------------------| +| `address` | String | The gno bech32 address of the validator. | +| `genesis-path` | String | The path to the `genesis.json`. (default `./genesis.json`) | + +### gnoland genesis validator add [flags] + +Adds a new validator to the `genesis.json`. + +#### FLAGS + +| Name | Type | Description | +|----------------|--------|-----------------------------------------------------------------| +| `address` | String | The gno bech32 address of the validator. | +| `genesis-path` | String | The path to the `genesis.json`. (default: `./genesis.json`) | +| `name` | String | The name of the validator (must be unique). | +| `power` | Uint | The voting power of the validator (must be > 0). (default: `1`) | +| `pub-key` | String | The bech32 string representation of the validator's public key. | + +```bash +gnoland genesis validator add \ +-address g1rzuwh5frve732k4futyw45y78rzuty4626zy6h \ +-name test1 \ +-pub-key gpub1pggj7ard9eg82cjtv4u52epjx56nzwgjyg9zplmcmggxyxyrch0zcyg684yxmerullv3l6hmau58sk4eyxskmny9h7lsnz + +Validator with address g1rzuwh5frve732k4futyw45y78rzuty4626zy6h added to genesis file +``` + +### gnoland genesis validator remove [flags] + +Removes a validator from the `genesis.json`. + +#### FLAGS + +| Name | Type | Description | +|----------------|--------|-------------------------------------------------------------| +| `address` | String | The gno bech32 address of the validator. | +| `genesis-path` | String | The path to the `genesis.json`. (default: `./genesis.json)` | + +```bash +gnoland genesis validator remove \ +-address g1rzuwh5frve732k4futyw45y78rzuty4626zy6h + +Validator with address g1rzuwh5frve732k4futyw45y78rzuty4626zy6h removed from genesis file +``` + +### gnoland genesis verify \ [flags] [\…] + +Verifies a `genesis.json`. + +#### FLAGS + +| Name | Type | Description | +|----------------|--------|-----------------------------------------------------------| +| `genesis-path` | String | The path to the `genesis.json`. (default: `genesis.json`) | + +### gnoland genesis balances \ [flags] [\…] + +Manages `genesis.json` account balances. + +#### SUBCOMMANDS + +| Name | Description | +|----------|--------------------------------------------------------| +| `add` | Adds the balance information. | +| `remove` | Removes the balance information of a specific account. | + +### gnoland genesis balances add [flags] + +#### FLAGS + +| Name | Type | Description | +|-----------------|--------|--------------------------------------------------------------------------------------------| +| `balance-sheet` | String | The path to the balance file containing addresses in the format `
=ugnot`. | +| `genesis-path` | String | The path to the `genesis.json` (default: `./genesis.json`) | +| `parse-export` | String | The path to the transaction export containing a list of transactions (JSONL). | +| `single` | String | The direct balance addition in the format `
=ugnot`. | + +```bash +gnoland genesis balances add \ +-single g1rzuwh5frve732k4futyw45y78rzuty4626zy6h=100ugnot + +1 pre-mines saved + +g1rzuwh5frve732k4futyw45y78rzuty4626zy6h:{[24 184 235 209 35 102 125 21 90 169 226 200 234 208 158 56 197 197 146 186] [{%!d(string=ugnot) 100}]}ugnot +``` + +### gnoland balances remove [flags] + +#### FLAGS + +| Name | Type | Description | +|----------------|--------|---------------------------------------------------------------------------------------------| +| `address` | String | The address of the account whose balance information should be removed from `genesis.json`. | +| `genesis-path` | String | The path to the `genesis.json`. (default: `./genesis.json`) | + +```bash +gnoland genesis balances remove \ +-address=g1rzuwh5frve732k4futyw45y78rzuty4626zy6h + +Pre-mine information for address g1rzuwh5frve732k4futyw45y78rzuty4626zy6h removed +``` + +### gnoland txs \ [flags] [\…] + +Manages genesis transactions through input files. + +#### SUBCOMMANDS + +| Name | Description | +|----------|---------------------------------------------------| +| `add` | Imports transactions into the `genesis.json`. | +| `remove` | Removes the transactions from the `genesis.json`. | +| `export` | Exports the transactions from the `genesis.json`. | + +### gnoland secrets \ [flags] [\…] + +The gno secrets manipulation suite for managing the validator key, p2p key and +validator state. + +#### SUBCOMMANDS + +| Name | Description | +|----------|---------------------------------------------------------| +| `init` | Initializes required Gno secrets in a common directory. | +| `verify` | Verifies all Gno secrets in a common directory. | +| `get` | Shows all Gno secrets present in a common directory. | + +### gnoland secrets init [flags] [\] + +Initializes the validator private key, the node p2p key and the validator's last +sign state. If a key is provided, it initializes the specified key. + +Available keys: + +- `validator_key` : The private key of the validator, which is different from the private key of the wallet. +- `node_id` : A key used for communicating with other nodes. +- `validator_state` : The current state of the validator such as the last signed block. + +#### FLAGS + +| Name | Type | Description | +|------------|--------|-----------------------------------------------------------------| +| `data-dir` | String | The secrets output directory. (default: `gnoland-data/secrets`) | +| `force` | String | Overwrites existing secrets, if any. (default: `false`) | + +```bash +# force initialize all key +gnoland secrets init -force + +Validator private key saved at gnoland-data/secrets/priv_validator_key.json +Validator last sign state saved at gnoland-data/secrets/priv_validator_state.json +Node key saved at gnoland-data/secrets/node_key.json + + +# force initialize a specific key type (ex: NodeKey) +gnoland secrets init node_key -force +Node key saved at gnoland-data/secrets/node_key.json ``` -### Example usage +### gnoland secrets verify [flags] [\] + +Verifies the validator private key, the node p2p key and the validator's last +sign state. If a key is provided, it verifies the specified key value. + +Available keys: [`validator_key`, `node_id`, `validator_state`] -#### Generating fresh secrets / config +#### FLAGS -To initialize the node secrets and configuration to `./example-node-data`, run the following command: +| Name | Type | Description | +|------------|--------|-----------------------------------------------------------------| +| `data-dir` | String | The secrets output directory. (default: `gnoland-data/secrets`) | -```shell -gnoland init --data-dir ./example-node-data +```bash +# verify all keys +gnoland secrets verify +Validator Private Key at gnoland-data/secrets/priv_validator_key.json is valid +Last Validator Sign state at gnoland-data/secrets/priv_validator_state.json is valid +Node P2P key at gnoland-data/secrets/node_key.json is valid + + +# verify a specific key type (ex: NodeKey) +gnoland secrets verify node_key +Node P2P key at gnoland-data/secrets/node_key.json is valid ``` -This will initialize the following directory structure: - -```shell -. -└── example-node-data/ - β”œβ”€β”€ secrets/ - β”‚ β”œβ”€β”€ priv_validator_state.json - β”‚ β”œβ”€β”€ node_key.json - β”‚ └── priv_validator_key.json - └── config/ - └── config.toml +### gnoland secrets get [flags] [\] + +Shows the validator private key, the node p2p key and the validator's last sign +state. If a key is provided, it shows the specified key value. + +Available keys: [`validator_key`, `node_key`, `validator_state`] + +#### FLAGS + +| Name | Type | Description | +|------------|--------|-----------------------------------------------------------------| +| `data-dir` | String | The secrets output directory. (default: `gnoland-data/secrets)` | + +```bash +gnoland secrets get + +{ + "validator_key": { + "address": "g14j4dlsh3jzgmhezzp9v8xp7wxs4mvyskuw5ljl", + "pub_key": "gpub1pggj7ard9eg82cjtv4u52epjx56nzwgjyg9zqaqle3fdduqul4slg6zllypq9r8gj4wlfucy6qfnzmjcgqv675kxjz8jvk" + }, + "validator_state": { + "height": 0, + "round": 0, + "step": 0 + }, + "node_id": { + "id": "g17h5t86vrztm6vuesx0xsyrg90wplj9mt9nsxng", + "p2p_address": "g17h5t86vrztm6vuesx0xsyrg90wplj9mt9nsxng@0.0.0.0:26656" + } +} + +# will return node id info +gnoland secrets get node_id + +# to get node id in cosmos +# gaiad tendermint show-node-id + +# will return validator address and pub key +gnoland secrets get validator_key +# to get validator address in cosmos +# gaiad tendermint show-address + +# to get validator pub key in cosmos +# gaiad tendermint show-validator ``` -#### Overwriting the secrets / config +### gnoland config [subcommand] [flags] -In case there is an already existing node directory at the given path, you will need to provide an additional `--force` -flag to enable data overwrite. +The gno config manipulation suite for editing base and module configurations. -:::warning Back up any secrets +#### SUBCOMMANDS -Running `gnoland init` will generate completely new node secrets (validator private key, node p2p key), so make sure -you back up any existing secrets (located at `/secrets`) if you intend to overwrite them, in case you don't -want to lose them. +| Name | Description | +|--------|-----------------------------------------| +| `init` | Initializes the Gno node configuration. | +| `set` | Edits the Gno node configuration. | +| `get` | Shows the Gno node configuration. | +### gnoland config init [flags] + +Initializes the Gno node configuration locally with default values, which +includes the base and module configurations. + +#### FLAGS + +| Name | Type | Description | +|---------------|---------|------------------------------------------------------------------------------| +| `config-path` | String | The path for the `config.toml`. (default: `gnoland-data/config/config.toml`) | +| `force` | Boolean | Overwrites existing config.toml, if any. (default: `false`) | + +```bash +# initialize the configuration file +gnoland config init + +Default configuration initialized at gnoland-data/config/config.toml +``` + +### gnoland config set \ \ + +Edits the Gno node configuration at the given path by setting the option +specified at `\` to the given `\`. + +#### FLAGS + +| Name | Type | Description | +|---------------|--------|------------------------------------------------------------------------------| +| `config-path` | String | The path for the `config.toml`. (default: `gnoland-data/config/config.toml`) | + +:::info +The `config set` command replaces the complexity of manually editing the `config.toml` file. ::: -Following up from the previous example where our desired node directory is `example-node-data` - to -initialize a completely new node data directory, with overwriting any existing data, run the following command: +### gnoland config get \ + +Shows the Gno node configuration at the given path by fetching the option +specified at `\`. + +#### FLAGS + +| Name | Type | Description | +|---------------|--------|---------------------------------------------------------------------------| +| `config-path` | String | the path for the config.toml (default: `gnoland-data/config/config.toml`) | + +```bash +# check the current monkier (the displayed validator name) +gnoland config get -r moniker +n3wbie-MacBook-Pro.local + +# set a new moniker +gnoland config set moniker hello +Updated configuration saved at gnoland-data/config/config.toml + -```shell -gnoland init --data-dir ./example-node-data --force +# confirm the moniker change +gnoland config get -r moniker +hello ``` diff --git a/docs/gno-tooling/gno-tooling.md b/docs/gno-tooling/gno-tooling.md index a03bf84a5bf..290d56820d0 100644 --- a/docs/gno-tooling/gno-tooling.md +++ b/docs/gno-tooling/gno-tooling.md @@ -4,5 +4,28 @@ id: gno-tooling # Gno Tooling -Welcome to the **Gno Tooling** section for Gno. This section outlines programs & tools -that are commonly used when developing applications with Gno. \ No newline at end of file +Welcome to the **Gno Tooling** section for Gno. This section outlines programs +& tools that are commonly used when developing applications with Gno. + +## Gno Command Syntax Guide + +### gno [subcommand] [flags] [arg...] + +#### Subcommand + +The gno command consists of various purpose-built subcommands. + +- `gno {mod}` : manage gno.mod +- `gno {mod} {download} : download modules to local cache + +#### Flags + +Options of the subcommand. + +- `gno mod download [-remote]` : remote for fetching gno modules + +#### Arg + +The actual value of the flag . + +- `gno mod download -remote {rpc.gno.land:26657}`