# Localnet

#### On this page

* [<mark style="color:blue;">Single Node</mark>](#single-node)
  * [<mark style="color:blue;">Pre-requisite Readings</mark>](#pre-requisite-readings)
  * [<mark style="color:blue;">Automated Localnet (script)</mark>](#automated-localnet-script)
  * [<mark style="color:blue;">Manual Localnet</mark>](#manual-localnet)
  * [<mark style="color:blue;">Initialize the chain</mark>](#initialize-the-chain)
  * [<mark style="color:blue;">Genesis Procedure</mark>](#genesis-procedure)
  * [<mark style="color:blue;">Adding Genesis Accounts</mark>](#adding-genesis-accounts)
  * [<mark style="color:blue;">Collecting</mark> <mark style="color:blue;"></mark><mark style="color:blue;">`gentx`</mark>](#collecting-gentx)
  * [<mark style="color:blue;">Run Testnet</mark>](#run-testnet)
* [<mark style="color:blue;">Multi Node</mark>](#multi-node)
  * [<mark style="color:blue;">Automated Localnet with Ignite CLI</mark>](#automated-localnet-with-ignite-cli)
  * [<mark style="color:blue;">Automated Localnet with Docker</mark>](#automated-localnet-with-docker)
  * [<mark style="color:blue;">Build & Start</mark>](#build--start)
  * [<mark style="color:blue;">Stop Localnet</mark>](#stop-localnet)
  * [<mark style="color:blue;">Configuration</mark>](#configuration)
  * [<mark style="color:blue;">Logging</mark>](#logging)
  * [<mark style="color:blue;">Interact with the Localnet</mark>](#interact-with-the-localnet)
  * [<mark style="color:blue;">Keys & Accounts</mark>](#keys--accounts)
  * [<mark style="color:blue;">Special Binaries</mark>](#special-binaries)
* [<mark style="color:blue;">Testnet command</mark>](#testnet-command)
  * [<mark style="color:blue;">Initialize Files</mark>](#initialize-files)
  * [<mark style="color:blue;">Gentxs</mark>](#gentxs)
  * [<mark style="color:blue;">Nodes</mark>](#nodes)
  * [<mark style="color:blue;">Start Testnet</mark>](#start-testnet)
  * [<mark style="color:blue;">Testnet Options</mark>](#testnet-options)

### Single Node <mark style="color:blue;">#</mark> <a href="#single-node" id="single-node"></a>

#### Pre-requisite Readings <mark style="color:blue;">#</mark> <a href="#pre-requisite-readings" id="pre-requisite-readings"></a>

* [<mark style="color:blue;">Install Binary</mark>](/icplaza-docs/chain-dev/installation.md)

#### Automated Localnet (script) <mark style="color:blue;">#</mark> <a href="#automated-localnet-script" id="automated-localnet-script"></a>

You can customize the local testnet script by changing values for convenience for example:

```bash
# customize the name of your key, the chain-id, moniker of the node, keyring backend, and log level
KEY="mykey"
CHAINID="ICPlaza_13141619-4"
MONIKER="localtestnet"
KEYRING="test"
LOGLEVEL="info"


# Allocate genesis accounts (ICPlaza formatted addresses)
ICPlazad add-genesis-account $KEY 100000000000000000000000000aICPlaza --keyring-backend $KEYRING

# Sign genesis transaction
ICPlazad gentx $KEY 1000000000000000000000aICPlaza --keyring-backend $KEYRING --chain-id $CHAINID
```

The default configuration will generate a single validator localnet with the chain-id `ICPlazad-1` and one predefined account (`mykey`) with some allocated funds at the genesis.

You can start the local chain using:

```bash
init.sh
```

#### Manual Localnet <mark style="color:blue;">#</mark> <a href="#manual-localnet" id="manual-localnet"></a>

This guide helps you create a single validator node that runs a network locally for testing and other development related uses.

#### Initialize the chain <mark style="color:blue;">#</mark> <a href="#initialize-the-chain" id="initialize-the-chain"></a>

Before actually running the node, we need to initialize the chain, and most importantly its genesis file. This is done with the `init` subcommand:

```bash
$MONIKER=testing
$KEY=mykey
$CHAINID="ICPlaza_9000-4"

# The argument $MONIKER is the custom username of your node, it should be human-readable.
ICPlazad init $MONIKER --chain-id=$CHAINID
```

::: tip You can \[edit] this `moniker` later by updating the `config.toml` file. :::

The command above creates all the configuration files needed for your node and validator to run, as well as a default genesis file, which defines the initial state of the network. All these \[configuration files] are in `~/.ICPlazad` by default, but you can overwrite the location of this folder by passing the `--home` flag.

#### Genesis Procedure <mark style="color:blue;">#</mark> <a href="#genesis-procedure" id="genesis-procedure"></a>

#### Adding Genesis Accounts <mark style="color:blue;">#</mark> <a href="#adding-genesis-accounts" id="adding-genesis-accounts"></a>

Before starting the chain, you need to populate the state with at least one account using the [<mark style="color:blue;">keyring</mark>](/icplaza-docs/chain-dev/account-keys.md#add-keys):

```bash
ICPlazad keys add my_validator
```

Once you have created a local account, go ahead and grant it some ICTech tokens in your chain’s genesis file. Doing so will also make sure your chain is aware of this account’s existence:

```bash
ICPlazad add-genesis-account my_validator 10000000000aICPlaza
```

Now that your account has some tokens, you need to add a validator to your chain.

For this guide, you will add your local node (created via the `init` command above) as a validator of your chain. Validators can be declared before a chain is first started via a special transaction included in the genesis file called a `gentx`:

```bash
# Create a gentx
# NOTE: this command lets you set the number of coins.
# Make sure this account has some coins with the genesis.app_state.staking.params.bond_denom denom
ICPlazad add-genesis-account my_validator 1000000000stake,10000000000aICPlaza
```

A `gentx` does three things:

1. Registers the `validator` account you created as a validator operator account (i.e. the account that controls the validator).
2. Self-delegates the provided `amount` of staking tokens.
3. Link the operator account with a Tendermint node pubkey that will be used for signing blocks. If no `--pubkey` flag is provided, it defaults to the local node pubkey created via the `ICPlazad init` command above.

For more information on `gentx`, use the following command:

```bash
ICPlazad gentx --help
```

#### Collecting `gentx` <mark style="color:blue;">#</mark> <a href="#collecting-gentx" id="collecting-gentx"></a>

By default, the genesis file do not contain any `gentxs`. A `gentx` is a transaction that bonds staking token present in the genesis file under `accounts` to a validator, essentially creating a validator at genesis. The chain will start as soon as more than 2/3rds of the validators (weighted by voting power) that are the recipient of a valid `gentx` come online after `genesis_time`.

A `gentx` can be added manually to the genesis file, or via the following command:

```bash
# Add the gentx to the genesis file
ICPlazad collect-gentxs
```

This command will add all the `gentxs` stored in `~/.ICPlazad/config/gentx` to the genesis file.

#### Run Testnet <mark style="color:blue;">#</mark> <a href="#run-testnet" id="run-testnet"></a>

Finally, check the correctness of the `genesis.json` file:

```bash
ICPlazad validate-genesis
```

Now that everything is set up, you can finally start your node:

```bash
ICPlazad start
```

:::tip To check all the available customizable options when running the node, use the `--help` flag. :::

You should see blocks come in.

The previous command allow you to run a single node. This is enough for the next section on interacting with this node, but you may wish to run multiple nodes at the same time, and see how consensus happens between them.

You can then stop the node using `Ctrl+C`.

### Multi Node <mark style="color:blue;">#</mark> <a href="#multi-node" id="multi-node"></a>

#### Automated Localnet with Ignite CLI <mark style="color:blue;">#</mark> <a href="#automated-localnet-with-ignite-cli" id="automated-localnet-with-ignite-cli"></a>

Once you have installed `ignite`, just run the localnet by using

```bash
ignite chain serve
```

Detailed instructions can be found in [<mark style="color:blue;">the Ignite CLI documentation</mark>](https://docs.ignite.com/kb/serve.html)

#### Automated Localnet with Docker <mark style="color:blue;">#</mark> <a href="#automated-localnet-with-docker" id="automated-localnet-with-docker"></a>

#### Build & Start <mark style="color:blue;">#</mark> <a href="#build--start" id="build--start"></a>

To build start a 4 node testnet run:

```bash
make localnet-start
```

This command creates a 4-node network using the ICTech`node` Docker image. The ports for each node are found in this table:

| Node ID       | P2P Port | Tendermint RPC Port | REST/ Ethereum JSON-RPC Port | WebSocket Port |
| ------------- | -------- | ------------------- | ---------------------------- | -------------- |
| ICTech`node0` | `26656`  | `26657`             | `8545`                       | `8546`         |
| ICTech`node1` | `26659`  | `26660`             | `8547`                       | `8548`         |
| ICTech`node2` | `26661`  | `26662`             | `8549`                       | `8550`         |
| ICTech`node3` | `26663`  | `26664`             | `8551`                       | `8552`         |

To update the binary, just rebuild it and restart the nodes

```bash
make localnet-start
```

The command above command will run containers in the background using Docker compose. You will see the network being created:

```bash
...
Creating network "ICPlaza_localnet" with driver "bridge"
Creating ICPlazadnode0 ... done
Creating ICPlazadnode2 ... done
Creating ICPlazadnode1 ... done
Creating ICPlazadnode3 ... done
```

#### Stop Localnet <mark style="color:blue;">#</mark> <a href="#stop-localnet" id="stop-localnet"></a>

Once you are done, execute:

```bash
make localnet-stop
```

#### Configuration <mark style="color:blue;">#</mark> <a href="#configuration" id="configuration"></a>

The `make localnet-start` creates files for a 4-node testnet in `./build` by calling the `ICPlazad testnet` command. This outputs a handful of files in the `./build` directory:

```bash
tree -L 3 build/

build/
├── ICPlazad
├── ICPlazad
├── gentxs
│   ├── node0.json
│   ├── node1.json
│   ├── node2.json
│   └── node3.json
├── node0
│   ├── ICPlazad
│   │   ├── key_seed.json
│   │   └── keyring-test-ICPlaza
│   └── ICPlazad
│       ├── config
│       ├── data
│       └── ICPlazad.log
├── node1
│   ├── ICPlazad
│   │   ├── key_seed.json
│   │   └── keyring-test-ICPlaza
│   └── ICPlazad
│       ├── config
│       ├── data
│       └── ICPlazad.log
├── node2
│   ├── ICPlazad
│   │   ├── key_seed.json
│   │   └── keyring-test-ICPlaza
│   └── ICPlazad
│       ├── config
│       ├── data
│       └── ICPlazad.log
└── node3
    ├── ICPlazad
    │   ├── key_seed.json
    │   └── keyring-test-ICPlaza
    └── ICPlazad
        ├── config
        ├── data
        └── ICPlazad.log
```

Each `./build/nodeN` directory is mounted to the `/ICPlazad` directory in each container.

#### Logging <mark style="color:blue;">#</mark> <a href="#logging" id="logging"></a>

In order to see the logs of a particular node you can use the following command:

```bash
# node 0: daemon logs
docker exec ICPlazadnode0 tail ICPlazad.log

# node 0: REST & RPC logs
docker exec ICPlazadnode0 tail ICPlazad.log
```

The logs for the daemon will look like:

```bash
I[2020-07-29|17:33:52.452] starting ABCI with Tendermint                module=main
E[2020-07-29|17:33:53.394] Can't add peer's address to addrbook         module=p2p err="Cannot add non-routable address 272a247b837653cf068d39efd4c407ffbd9a0e6f@192.168.10.5:26656"
E[2020-07-29|17:33:53.394] Can't add peer's address to addrbook         module=p2p err="Cannot add non-routable address 3e05d3637b7ebf4fc0948bbef01b54d670aa810a@192.168.10.4:26656"
E[2020-07-29|17:33:53.394] Can't add peer's address to addrbook         module=p2p err="Cannot add non-routable address 689f8606ede0b26ad5b79ae244c14cc67ab4efe7@192.168.10.3:26656"
I[2020-07-29|17:33:58.828] Executed block                               module=state height=88 validTxs=0 invalidTxs=0
I[2020-07-29|17:33:58.830] Committed state                              module=state height=88 txs=0 appHash=90CC5FA53CF8B5EC49653A14DA20888AD81C92FCF646F04D501453FD89FCC791
I[2020-07-29|17:34:04.032] Executed block                               module=state height=89 validTxs=0 invalidTxs=0
I[2020-07-29|17:34:04.034] Committed state                              module=state height=89 txs=0 appHash=0B54C4DB1A0DACB1EEDCD662B221C048C826D309FD2A2F31FF26BAE8D2D7D8D7
I[2020-07-29|17:34:09.381] Executed block                               module=state height=90 validTxs=0 invalidTxs=0
I[2020-07-29|17:34:09.383] Committed state                              module=state height=90 txs=0 appHash=75FD1EE834F0669D5E717C812F36B21D5F20B3CCBB45E8B8D415CB9C4513DE51
I[2020-07-29|17:34:14.700] Executed block                               module=state height=91 validTxs=0 invalidTxs=0
```

::: tip You can disregard the `Can't add peer's address to addrbook` warning. As long as the blocks are being produced and the app hashes are the same for each node, there should not be any issues. :::

Whereas the logs for the REST & RPC server would look like:

```bash
I[2020-07-30|09:39:17.488] Starting application REST service (chain-id: "7305661614933169792")... module=rest-server
I[2020-07-30|09:39:17.488] Starting RPC HTTP server on 127.0.0.1:8545   module=rest-server
...
```

**Follow Logs&#x20;**<mark style="color:blue;">**#**</mark>

You can also watch logs as they are produced via Docker with the `--follow` (`-f`) flag, for example:

```bash
docker logs -f ICPlazadnode0
```

#### Interact with the Localnet <mark style="color:blue;">#</mark> <a href="#interact-with-the-localnet" id="interact-with-the-localnet"></a>

**Ethereum JSON-RPC & Websocket Ports&#x20;**<mark style="color:blue;">**#**</mark>

To interact with the testnet via WebSockets or RPC/API, you will send your request to the corresponding ports:

| EVM JSON-RPC | Eth Websocket |
| ------------ | ------------- |
| `8545`       | `8546`        |

You can send a curl command such as:

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":1}' -H "Content-Type: application/json" 192.162.10.1:8545
```

::: tip The IP address will be the public IP of the docker container. :::

Additional instructions on how to interact with the WebSocket can be found on the [<mark style="color:blue;">events documentation</mark>](/icplaza-docs/chain-dev/ethereum-json-rpc.md#events).

#### Keys & Accounts <mark style="color:blue;">#</mark> <a href="#keys--accounts" id="keys--accounts"></a>

To interact with `ICPlazad` and start querying state or creating txs, you use the `ICPlazad` directory of any given node as your `home`, for example:

```bash
ICPlazad keys list --home ./build/node0/ICPlazad
```

Now that accounts exists, you may create new accounts and send those accounts funds!

::: tip **Note**: Each node’s seed is located at `./build/nodeN/ICPlazad/key_seed.json` and can be restored to the CLI using the `ICPlazad keys add --restore` command :::

#### Special Binaries <mark style="color:blue;">#</mark> <a href="#special-binaries" id="special-binaries"></a>

If you have multiple binaries with different names, you can specify which one to run with the BINARY environment variable. The path of the binary is relative to the attached volume. For example:

```bash
# Run with custom binary
BINARY=ICTech make localnet-start
```

### Testnet command <mark style="color:blue;">#</mark> <a href="#testnet-command" id="testnet-command"></a>

The ICTech `testnet` subcommand makes it easy to initialize and start a simulated test network for testing purposes.

In addition to the commands for [<mark style="color:blue;">running a node</mark>](/icplaza-docs/chain-dev/running-a-validato.md), the `/doc/DAPP/Ethereum/Events` binary also includes a `testnet` command that allows you to start a simulated test network in-process or to initialize files for a simulated test network that runs in a separate process.

#### Initialize Files <mark style="color:blue;">#</mark> <a href="#initialize-files" id="initialize-files"></a>

The `init-files` subcommand initializes the necessary files to run a test network in a separate process (i.e. using a Docker container). Running this command is not a prerequisite for the `start` subcommand (\[see below]).

This is similar to the `init` command when initializing a single node, but in this case we are initializing multiple nodes, generating the genesis transactions for each node, and then collecting those transactions.

In order to initialize the files for a test network, run the following command:

```bash
ICPlazad testnet init-files
```

You should see the following output in your terminal:

```bash
Successfully initialized 4 node directories
```

The default output directory is a relative `.testnets` directory. Let’s take a look at the files created within the `.testnets` directory.

#### Gentxs <mark style="color:blue;">#</mark> <a href="#gentxs" id="gentxs"></a>

The `gentxs` directory includes a genesis transaction for each validator node. Each file includes a JSON encoded genesis transaction used to register a validator node at the time of genesis. The genesis transactions are added to the `genesis.json` file within each node directory during the initialization process.

#### Nodes <mark style="color:blue;">#</mark> <a href="#nodes" id="nodes"></a>

A node directory is created for each validator node. Within each node directory is a ICTech directory. The ICTech directory is the home directory for each node, which includes the configuration and data files for that node (i.e. the same files included in the default `~/.`ICTech directory when running a single node).

#### Start Testnet <mark style="color:blue;">#</mark> <a href="#start-testnet" id="start-testnet"></a>

The `start` subcommand both initializes and starts an in-process test network. This is the fastest way to spin up a local test network for testing purposes.

You can start the local test network by running the following command:

```bash
ICPlazad testnet start
```

You should see something similar to the following:

```bash
acquiring test network lock
preparing test network with chain-id "ICPlaza_1276974-1"


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
++       THIS MNEMONIC IS FOR TESTING PURPOSES ONLY        ++
++                DO NOT USE IN PRODUCTION                 ++
++                                                         ++
++  sustain know debris minute gate hybrid stereo custom   ++
++  divorce cross spoon machine latin vibrant term oblige  ++
++   moment beauty laundry repeat grab game bronze truly   ++
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


starting test network...
started test network
press the Enter Key to terminate
```

The first validator node is now running in-process, which means the test network will terminate once you either close the terminal window or you press the Enter key. In the output, the mnemonic phrase for the first validator node is provided for testing purposes. The validator node is using the same default addresses being used when initializing and starting a single node (no need to provide a `--node` flag).

Check the status of the first validator node:

```bash
ICPlazad status
```

Import the key from the provided mnemonic:

```bash
ICPlazad keys add test --recover
```

Check the balance of the account address:

```bash
ICPlazad q bank balances [address]
```

Use this test account to manually test against the test network.

#### Testnet Options <mark style="color:blue;">#</mark> <a href="#testnet-options" id="testnet-options"></a>

You can customize the configuration of the test network with flags. In order to see all flag options, append the `--help` flag to each command.

[<mark style="color:blue;">← Guides</mark>](/icplaza-docs/chain-dev/guides.md)

[<mark style="color:blue;">Ethereum Tooling →</mark>](/icplaza-docs/chain-dev/ethereum-tooling.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ictech.gitbook.io/icplaza-docs/chain-dev/localnet.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.