github.com/gnolang/gno@v0.0.0-20240520182011-228e9d0192ce/docs/getting-started/local-setup/setting-up-a-local-chain.md (about)

     1  ---
     2  id: setting-up-a-local-chain
     3  ---
     4  
     5  # Setting up a Local Chain
     6  
     7  ## Overview
     8  
     9  In this tutorial, you will learn how to start a local Gno node (and chain!).
    10  Additionally, you will see the different options you can use to make your Gno instance unique.
    11  
    12  ## Prerequisites
    13  
    14  - [`gnoland` installed](local-setup.md#3-installing-other-gno-tools).
    15  
    16  ## Starting a node with a default configuration
    17  
    18  You can start a Gno blockchain node with the default configuration by navigating to the `gno.land` sub-folder and
    19  running the following command:
    20  
    21  ```bash
    22  gnoland start
    23  ```
    24  
    25  The command will trigger a chain initialization process (if you haven't run the node before), and start the Gno node,
    26  which is ready to accept transactions and interact with other Gno nodes.
    27  
    28  ![gnoland start](../../assets/getting-started/local-setup/setting-up-a-local-chain/gnoland-start.gif)
    29  
    30  To view the command defaults, simply run the `help` command:
    31  
    32  ```bash
    33  gnoland start --help
    34  ```
    35  
    36  Let's break down the most important default settings:
    37  
    38  - `chainid` - the ID of the Gno chain. This is used for Gno clients, and distinguishing the chain from other Gno
    39    chains (ex. through IBC)
    40  - `config` - the custom node configuration file
    41    for more details on utilizing this file
    42  - `genesis-balances-file` - the initial premine balances file, which contains initial native currency allocations for
    43    the chain. By default, the genesis balances file is located in `gno.land/genesis/genesis_balances.txt`, this is also the
    44    reason why we need to navigate to the `gno.land` sub-folder to run the command with default settings
    45  - `data-dir` - the working directory for the node configuration and node data (state DB)
    46  
    47  :::info Resetting the chain
    48  
    49  As mentioned, the working directory for the node is located in `data-dir`. To reset the chain, you need
    50  to delete this directory and start the node up again. If you are using the default node configuration, you can run
    51  `make fclean` from the `gno.land` sub-folder to delete the `tempdir` working directory.
    52  
    53  :::
    54  
    55  ## Changing the chain ID
    56  
    57  :::info Changing the Gno chain ID has several implications
    58  
    59  - It affects how the Gno node communicates with other Gno nodes / chains
    60  - Gno clients that communicate through JSON-RPC need to match this value
    61  
    62  It's important to configure your node properly before launching it in a distributed network.
    63  Keep in mind that changes may not be applicable once connected.
    64  
    65  :::
    66  
    67  To change the Gno chain ID, run the following command:
    68  
    69  ```bash
    70  gnoland start --chainid NewChainID
    71  ```
    72  
    73  We can verify the chain ID has been changed, by fetching the status of the node and seeing the
    74  associated chain ID. By default, the node exposes the JSON-RPC API on `http://127.0.0.1:26657`:
    75  
    76  ```bash
    77  curl -H "Content-type: application/json" -d '{
    78      "jsonrpc": "2.0",
    79      "method": "status",
    80      "params": [],
    81      "id": 1
    82  }' 'http://127.0.0.1:26657'
    83  ```
    84  
    85  We should get a response similar to this:
    86  
    87  ```json
    88  {
    89    "jsonrpc": "2.0",
    90    "id": 1,
    91    "result": {
    92      "node_info": {
    93        "version_set": [
    94          // ...
    95        ],
    96        "net_address": "g10g9r37g9xa54a6clttzmhk2gmdkzsntzty0cvr@0.0.0.0:26656",
    97        "network": "NewChainID"
    98        // ...
    99      }
   100    }
   101  }
   102  ```
   103  
   104  :::danger Chain ID can be set only once
   105  
   106  Since the chain ID information is something bound to a chain, you can
   107  only change it once upon chain initialization, and further attempts to change it will
   108  have no effect.
   109  
   110  :::
   111  
   112  ## Changing the node configuration
   113  
   114  You can specify a node configuration file using the `--config` flag.
   115  
   116  ```bash
   117  gnoland start --config config.toml
   118  ```
   119  
   120  ## Changing the premine list
   121  
   122  You do not need to use the `gno.land/genesis/genesis_balances.txt` file as the source of truth for initial network
   123  funds.
   124  
   125  To specify a custom balance sheet for a fresh local chain, you can use the `-genesis-balances-file`:
   126  
   127  ```bash
   128  gnoland start -genesis-balances-file custom-balances.txt
   129  ```
   130  
   131  Make sure the balances file follows the following format:
   132  
   133  ```text
   134  <address>=<balance>ugnot
   135  ```
   136  
   137  Following this pattern, potential entries into the genesis balances file would look like:
   138  
   139  ```text
   140  g1qpymzwx4l4cy6cerdyajp9ksvjsf20rk5y9rtt=10000000000ugnot
   141  g1u7y667z64x2h7vc6fmpcprgey4ck233jaww9zq=10000000000ugnot
   142  ```