feat: overhaul lazy init in gnoland start

docs/getting-started/local-setup/setting-up-a-local-chain.md

@@ -13,7 +13,7 @@ Additionally, you will see the different options you can use to make your Gno in
 
 - [`gnoland` installed](local-setup.md#3-installing-other-gno-tools).
 
-## Starting a node with a default configuration
+## Starting a local node (lazy init)
 
 You can start a Gno blockchain node with the default configuration by navigating to the `gno.land` sub-folder and
 running the following command:
@@ -27,6 +27,17 @@ 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)
 
+:::info Lazy init
+
+Starting a Gno blockchain node using just the `gnoland start` command implies a few things:
+
+- the default configuration will be used, and generated on disk in the `gnoland-data` directory
+- random secrets data will be generated (node private keys, networking keys...)
+- an entirely new `genesis.json` will be used, and generated on disk in the `../gnoland-data` directory. The genesis
+  will have a single validator, whose public key is derived from the previously generated node secrets
+
+:::
+
 To view the command defaults, simply run the `help` command:
 
 ```bash
@@ -40,7 +51,8 @@ Let's break down the most important default settings:
 - `config` - the custom node configuration file
   for more details on utilizing this file
 - `genesis-balances-file` - the initial premine balances file, which contains initial native currency allocations for
-  the chain. By default, the genesis balances file is located in `gno.land/genesis/genesis_balances.txt`, this is also the
+  the chain. By default, the genesis balances file is located in `gno.land/genesis/genesis_balances.txt`, this is also
+  the
   reason why we need to navigate to the `gno.land` sub-folder to run the command with default settings
 - `data-dir` - the working directory for the node configuration and node data (state DB)
 
@@ -52,7 +64,214 @@ to delete this directory and start the node up again. If you are using the defau
 
 :::
 
-## Changing the chain ID
+## Starting a local node (manual configuration)
+
+Manually configuring and starting the Gno blockchain node is a bit more involved than simply initializing it "lazily",
+and involves the following steps:
+
+- generating the node secrets, and configuration
+- generating the `genesis.json`, and populating it
+- starting the node with the generated data
+
+### 1. Generate the node directory
+
+You can generate the default node directory using the following command:
+
+```shell
+gnoland init
+```
+
+This will initialize the following directory structure:
+
+```shell
+.
+└── gnoland-data/
+    ├── secrets/
+    │   ├── priv_validator_state.json
+    │   ├── node_key.json
+    │   └── priv_validator_key.json
+    └── config/
+       └── config.toml
+```
+
+A couple of things to note:
+
+- `gnoland init` initializes a default configuration
+- `gnoland init` initializes new node secrets (validator key, node p2p key)
+
+Essentially, `gnoland init` is simply a combination of `gnoland secrets generate` and `gnoland config generate`, with
+the default options enabled.
+
+#### Changing the node configuration
+
+To change the configuration params, such as for example the node's listen address, you can utilize the following
+command:
+
+```shell
+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
+gnoland config get rpc.laddr
+```
+
+### 2. Generate the `genesis.json`
+
+:::info Where's the `genesis.json`?
+
+In this example, we are starting a completely new network. In case you are connecting to an existing network, you don't
+need to regenerate the `genesis.json`, but simply fetch it from publicly available resources of the Gno chain you're
+trying to connect to.
+
+:::
+
+Generating an empty `genesis.json` is relatively straightforward:
+
+```shell
+gnoland genesis generate
+```
+
+The resulting `genesis.json` is empty:
+
+```json
+{
+  "genesis_time": "2024-05-08T10:25:09Z",
+  "chain_id": "dev",
+  "consensus_params": {
+    "Block": {
+      "MaxTxBytes": "1000000",
+      "MaxDataBytes": "2000000",
+      "MaxBlockBytes": "0",
+      "MaxGas": "10000000",
+      "TimeIotaMS": "100"
+    },
+    "Validator": {
+      "PubKeyTypeURLs": [
+        "/tm.PubKeyEd25519"
+      ]
+    }
+  },
+  "app_hash": null
+}
+```
+
+This will generate a `genesis.json` in the calling directory, by default. To check all configurable options when
+generating the `genesis.json`, you can run the command using the `--help` flag:
+
+```shell
+gnoland genesis generate --help
+
+USAGE
+  generate [flags]
+
+Generates a node's genesis.json based on specified parameters
+
+FLAGS
+  -block-max-data-bytes 2000000  the max size of the block data
+  -block-max-gas 10000000        the max gas limit for the block
+  -block-max-tx-bytes 1000000    the max size of the block transaction
+  -block-time-iota 100           the block time iota (in ms)
+  -chain-id dev                  the ID of the chain
+  -genesis-time 1715163944       the genesis creation time. Defaults to current time
+  -output-path ./genesis.json    the output path for the genesis.json
+```
+
+### 3. 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
+set.
+
+Luckily, we've generated the node secrets in step #1 -- we will utilize the generated node key, so the process we start
+locally will be the validator node for the new Gno network.
+
+To display the generated node key data, run the following command:
+
+```shell
+gnoland secrets get ValidatorPrivateKey
+```
+
+This will display the information we need for updating the `genesis.json`:
+
+```shell
+[Validator Key Info]
+
+Address:     g10e3smsmusjn00n7j75fk9u4zta8djrlglcv6af
+Public Key:  gpub1pggj7ard9eg82cjtv4u52epjx56nzwgjyg9zqhjhrqd7xlhda7spfdtx6lrcjxlk67av46w7eng9z4e2ch478fsk4xmq3j
+```
+
+Updating the `genesis.json` is relatively simple, running the following command will add the generated node info to the
+validator set:
+
+```shell
+gnoland genesis validator add \
+--address g10e3smsmusjn00n7j75fk9u4zta8djrlglcv6af \
+--pub-key gpub1pggj7ard9eg82cjtv4u52epjx56nzwgjyg9zqhjhrqd7xlhda7spfdtx6lrcjxlk67av46w7eng9z4e2ch478fsk4xmq3j \
+--name Cuttlas
+```
+
+We can verify that the new validator was indeed added to the validator set:
+
+```json
+{
+  "genesis_time": "2024-05-08T10:25:09Z",
+  "chain_id": "dev",
+  "consensus_params": {
+    "Block": {
+      "MaxTxBytes": "1000000",
+      "MaxDataBytes": "2000000",
+      "MaxBlockBytes": "0",
+      "MaxGas": "10000000",
+      "TimeIotaMS": "100"
+    },
+    "Validator": {
+      "PubKeyTypeURLs": [
+        "/tm.PubKeyEd25519"
+      ]
+    }
+  },
+  "validators": [
+    {
+      "address": "g1lz2ez3ceeds9f6jllwy7u0hvkphuuv0plcc8pp",
+      "pub_key": {
+        "@type": "/tm.PubKeyEd25519",
+        "value": "AvaVf/cH84urHNuS1lo3DYmtEErxkTLRsrcr71QoAr4="
+      },
+      "power": "1",
+      "name": "Cuttlas"
+    }
+  ],
+  "app_hash": null
+}
+```
+
+### 4. Starting the chain
+
+We have completed the main aspects of setting up a node:
+
+- generated the node directory (secrets and configuration) ✅
+- generated a `genesis.json` ✅
+- added an initial validator set to the `genesis.json` ✅
+
+Now, we can go ahead and start the Gno chain for the first time, by running:
+
+```shell
+gnoland start \
+--genesis ./genesis.json \
+--data-dir ./gnoland-data
+```
+
+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)
+
+## Chain runtime options
+
+### Changing the chain ID
 
 :::info Changing the Gno chain ID has several implications
 
@@ -109,15 +328,15 @@ have no effect.
 
 :::
 
-## Changing the node configuration
+### Changing the node configuration
 
 You can specify a node configuration file using the `--config` flag.
 
 ```bash
 gnoland start --config config.toml
 ```
 
-## Changing the premine list
+### Changing the premine list
 
 You do not need to use the `gno.land/genesis/genesis_balances.txt` file as the source of truth for initial network
 funds.
@@ -140,3 +359,11 @@ Following this pattern, potential entries into the genesis balances file would l
 g1qpymzwx4l4cy6cerdyajp9ksvjsf20rk5y9rtt=10000000000ugnot
 g1u7y667z64x2h7vc6fmpcprgey4ck233jaww9zq=10000000000ugnot
 ```
+
+:::info Genesis generation
+
+Genesis block generation happens only once during the lifetime of a Gno chain.
+This means that if you specify a balances file using `gnoland start`, and the chain has already started (advanced from
+block 0), the specified balance sheet will not be applied.
+
+:::

docs/gno-tooling/cli/gnoland.md

@@ -4,28 +4,72 @@ id: gno-tooling-gnoland
 
 # gnoland
 
-## Run a Gnoland Node
+## Overview
 
-Start a node on the Gnoland blockchain with the following command.
+`gnoland` is the Gno.land blockchain client binary, which is capable of managing node working files, as well
+as starting the blockchain client itself.
 
-```bash
-gnoland
+## `gnoland init`
+
+`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).
+
+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.
+
+```shell
+gnoland init --help
+
+USAGE
+  init [flags]
+
+initializes the node directory containing the secrets and configuration files
+
+FLAGS
+  -data-dir gnoland-data  the path to the node's data directory
+  -force=false            overwrite existing data, if any
+```
+
+### Example usage
+
+#### Generating fresh secrets / config
+
+To initialize the node secrets and configuration to `./example-node-data`, run the following command:
+
+```shell
+gnoland init --data-dir ./example-node-data
+```
+
+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
 ```
 
-### **Sub Commands**
-| Command   | Description       |
-| --------- | ----------------- |
-| `start`   | Run the full node |
+#### Overwriting the secrets / config
 
+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.
 
-### **Options**
+:::warning Back up any secrets
 
-| Name                       | Type    | Description                                                                             |
-|----------------------------| ------- | --------------------------------------------------------------------------------------- |
-| `chainid`                  | String  | The id of the chain (default: `dev`).                                                   |
-| `genesis-balances-file`    | String  | The initial GNOT distribution file (default: `./gnoland/genesis/genesis_balances.txt`). |
-| `genesis-remote`           | String  | Replacement '%%REMOTE%%' in genesis (default: `"localhost:26657"`).                     |
-| `genesis-txs-file`         | String  | Initial txs to be executed (default: `"./gnoland/genesis/genesis_txs.jsonl"`).          |
-| `data-dir`                 | String  | directory for config and data (default: `gnoland-data`).                                     |
-| `skip-failing-genesis-txs` | Boolean | Skips transactions that fail from the `genesis-txs-file`                                |
-| `skip-start`               | Boolean | Quits after initialization without starting the node.                                   |
+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 `<node-dir>/secrets`) if you intend to overwrite them, in case you don't
+want to lose them.
+
+:::
+
+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:
+
+```shell
+gnoland init --data-dir ./example-node-data --force
+```