feat: overhaul lazy init in gnoland start

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

@@ -13,20 +13,31 @@ 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:
 
 ```bash
-gnoland start
+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)
 
+:::info Lazy init
+
+Starting a Gno blockchain node using just the `gnoland start --lazy` 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
@@ -37,26 +48,240 @@ Let's break down the most important default settings:
 
 - `chainid` - the ID of the Gno chain. This is used for Gno clients, and distinguishing the chain from other Gno
   chains (ex. through IBC)
-- `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)
 
 :::info Resetting the chain
 
 As mentioned, the working directory for the node is located in `data-dir`. To reset the chain, you need
 to delete this directory and start the node up again. If you are using the default node configuration, you can run
-`make fclean` from the `gno.land` sub-folder to delete the `tempdir` working directory.
+`make fclean` from the `gno.land` sub-folder to delete the `gnoland-data` working directory.
+
+:::
+
+## 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 (secrets + config)
+
+You can generate the default node directory secrets using the following command:
+
+```shell
+gnoland secrets init
+```
+
+And generate the default node config using the following command:
+
+```shell
+gnoland config 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 config init` initializes a default configuration
+- `gnoland secrets init` initializes new node secrets (validator key, node p2p key)
+
+Essentially, `gnoland start --lazy` 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.
 
 :::
 
-## Changing the chain ID
+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:
 
-:::info Changing the Gno chain ID has several implications
+```shell
+gnoland genesis generate --help
 
-- It affects how the Gno node communicates with other Gno nodes / chains
+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
+
+Below are some implications to consider when changing the chain ID:
+
+- it affects how the Gno node communicates with other Gno nodes / chains
 - Gno clients that communicate through JSON-RPC need to match this value
 
 It's important to configure your node properly before launching it in a distributed network.
@@ -109,15 +334,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 +365,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.
+
+:::