Skip to content

Commit ab7db7c

Browse files
chong-hechong-he
authored
Update local testnet documentation (#5896)
* Update local testnet doc * Update doc * Minor revision * Fix directory path * Update scripts/local_testnet/README.md Co-authored-by: Pawan Dhananjay <pawandhananjay@gmail.com> * Add kurtosis web * Add save logs command * Log of a service * Update scripts/local_testnet/README.md Co-authored-by: Jimmy Chen <jchen.tc@gmail.com> * Update scripts/local_testnet/README.md Co-authored-by: Jimmy Chen <jchen.tc@gmail.com> * Minor revision * Merge branch 'local-testnet-doc' of https://github.com/chong-he/lighthouse into local-testnet-doc
1 parent c2838ba commit ab7db7c

File tree

1 file changed

+36
-152
lines changed

1 file changed

+36
-152
lines changed

‎scripts/local_testnet/README.md

Lines changed: 36 additions & 152 deletions
Original file line numberDiff line numberDiff line change
@@ -1,201 +1,85 @@
11
# Simple Local Testnet
22

3-
These scripts allow for running a small local testnet with multiple beacon nodes and validator clients and a geth execution client.
3+
These scripts allow for running a small local testnet with a default of 4 beacon nodes, 4 validator clients and 4 geth execution clients using Kurtosis.
44
This setup can be useful for testing and development.
55

6-
## Requirements
6+
## Installation
77

8-
The scripts require `lcli`, `lighthouse`, `geth`, `bootnode` to be installed on `PATH` (run `echo $PATH` to view all `PATH` directories).
8+
1. Install [Docker](https://docs.docker.com/get-docker/). Verify that Docker has been successfully installed by running `sudo docker run hello-world`.
99

10+
1. Install [Kurtosis](https://docs.kurtosis.com/install/). Verify that Kurtosis has been successfully installed by running `kurtosis version` which should display the version.
1011

11-
MacOS users need to install GNU `sed` and GNU `grep`, and add them both to `PATH` as well.
12-
13-
The first step is to install Rust and dependencies. Refer to the [Lighthouse Book](https://lighthouse-book.sigmaprime.io/installation-source.html#dependencies) for installation. We will also need [jq](https://jqlang.github.io/jq/), which can be installed with `sudo apt install jq`.
14-
15-
Then, we clone the Lighthouse repository:
16-
```bash
17-
cd ~
18-
git clone https://github.com/sigp/lighthouse.git
19-
cd lighthouse
20-
```
21-
We are now ready to build Lighthouse. Run the command:
22-
23-
```bash
24-
make
25-
make install-lcli
26-
```
27-
28-
This will build `lighthouse` and `lcli`. For `geth` and `bootnode`, go to [geth website](https://geth.ethereum.org/downloads) and download the `Geth & Tools`. For example, to download and extract `Geth & Tools 1.13.1`:
29-
30-
```bash
31-
cd ~
32-
curl -LO https://gethstore.blob.core.windows.net/builds/geth-alltools-linux-amd64-1.13.1-3f40e65c.tar.gz
33-
tar xvf geth-alltools-linux-amd64-1.13.1-3f40e65c.tar.gz
34-
```
35-
36-
After extraction, copy `geth` and `bootnode` to the `PATH`. A typical directory is `/usr/local/bin`.
37-
38-
```bash
39-
cd geth-alltools-linux-amd64-1.13.1-3f40e65c
40-
sudo cp geth bootnode /usr/local/bin
41-
```
42-
43-
After that We can remove the downloaded files:
44-
45-
```bash
46-
cd ~
47-
rm -r geth-alltools-linux-amd64-1.13.1-3f40e65c geth-alltools-linux-amd64-1.13.1-3f40e65c.tar.gz
48-
```
49-
50-
We are now ready to start a local testnet.
12+
1. Install [yq](https://github.com/mikefarah/yq). If you are on Ubuntu, you can install `yq` by running `sudo apt install yq -y`.
5113

5214
## Starting the testnet
5315

54-
To start a testnet using the predetermined settings:
16+
To start a testnet, from the Lighthouse root repository:
5517

5618
```bash
57-
cd ~
58-
cd ./lighthouse/scripts/local_testnet
59-
./start_local_testnet.sh genesis.json
19+
cd ./scripts/local_testnet
20+
./start_local_testnet.sh
6021
```
6122

62-
This will execute the script and if the testnet setup is successful, you will see "Started!" at the end.
63-
64-
The testnet starts with a post-merge genesis state.
65-
The testnet starts a consensus layer and execution layer boot node along with `BN_COUNT`
66-
(the number of beacon nodes) each connected to a geth execution client and `VC_COUNT` (the number of validator clients). By default, `BN_COUNT=4`, `VC_COUNT=4`.
23+
It will build a Lighthouse docker image from the root of the directory and will take an approximately 12 minutes to complete. Once built, the testing will be started automatically. You will see a list of services running and "Started!" at the end.
24+
You can also select your own Lighthouse docker image to use by specifying it in `network_params.yml` under the `cl_image` key.
25+
Full configuration reference for kurtosis is specified [here](https://github.com/ethpandaops/ethereum-package?tab=readme-ov-file#configuration).
6726

68-
The `start_local_testnet.sh` script takes four options `-v VC_COUNT`, `-d DEBUG_LEVEL`, `-p` to enable builder proposals and `-h` for help. It also takes a mandatory `GENESIS_FILE` for initialising geth's state.
69-
A sample `genesis.json` is provided in this directory.
70-
71-
The options may be in any order or absent in which case they take the default value specified.
72-
- VC_COUNT: the number of validator clients to create, default: `BN_COUNT`
73-
- DEBUG_LEVEL: one of { error, warn, info, debug, trace }, default: `info`
74-
75-
The `ETH1_BLOCK_HASH` environment variable is set to the block_hash of the genesis execution layer block which depends on the contents of `genesis.json`. Users of these scripts need to ensure that the `ETH1_BLOCK_HASH` variable is updated if genesis file is modified.
76-
77-
To view the beacon, validator client and geth logs:
27+
To view all running services:
7828

7929
```bash
80-
tail -f ~/.lighthouse/local-testnet/testnet/beacon_node_1.log
81-
tail -f ~/.lighthouse/local-testnet/testnet/validator_node_1.log
82-
tail -f ~/.lighthouse/local-testnet/testnet/geth_1.log
30+
kurtosis enclave inspect local-testnet
8331
```
8432

85-
where `beacon_node_1` can be changed to `beacon_node_2`, `beacon_node_3` or `beacon_node_4` to view logs for different beacon nodes. The same applies to validator clients and geth nodes.
86-
87-
## Stopping the testnet
88-
89-
To stop the testnet, navigate to the directory `cd ~/lighthouse/scripts/local_testnet`, then run the command:
33+
To view the logs:
9034

9135
```bash
92-
./stop_local_testnet.sh
36+
kurtosis service logs local-testnet $SERVICE_NAME
9337
```
9438

95-
Once a testnet is stopped, it cannot be continued from where it left off. When the start local testnet command is run, it will start a new local testnet.
96-
97-
## Manual creation of local testnet
98-
99-
In [Starting the testnet](./README.md#starting-the-testnet), the testnet is started automatically with predetermined parameters (database directory, ports used etc). This section describes some modifications of the local testnet settings, e.g., changing the database directory, or changing the ports used.
100-
101-
102-
The testnet also contains parameters that are specified in `vars.env`, such as the slot time `SECONDS_PER_SLOT=3` (instead of 12 seconds on mainnet). You may change these parameters to suit your testing purposes. After that, in the `local_testnet` directory, run the following command to create genesis state with embedded validators and validator keys, and also to update the time in `genesis.json`:
39+
where `$SERVICE_NAME` is obtained by inspecting the running services above. For example, to view the logs of the first beacon node, validator client and geth:
10340

10441
```bash
105-
./setup.sh
106-
./setup_time.sh genesis.json
42+
kurtosis service logs local-testnet -f cl-1-lighthouse-geth
43+
kurtosis service logs local-testnet -f vc-1-geth-lighthouse
44+
kurtosis service logs local-testnet -f el-1-geth-lighthouse
10745
```
10846

109-
Note: The generated genesis validators are embedded into the genesis state as genesis validators and hence do not require manual deposits to activate.
110-
111-
Generate bootnode enr and start an EL and CL bootnode so that multiple nodes can find each other
112-
```bash
113-
./bootnode.sh
114-
./el_bootnode.sh
115-
```
47+
If you would like to save the logs, use the command:
11648

117-
Start a geth node:
11849
```bash
119-
./geth.sh <DATADIR> <NETWORK-PORT> <HTTP-PORT> <AUTH-HTTP-PORT> <GENESIS_FILE>
120-
```
121-
e.g.
122-
```bash
123-
./geth.sh $HOME/.lighthouse/local-testnet/geth_1 7001 6001 5001 genesis.json
50+
kurtosis dump $OUTPUT_DIRECTORY
12451
```
12552

126-
Start a beacon node:
53+
This will create a folder named `$OUTPUT_DIRECTORY` in the present working directory that contains all logs and other information. If you want the logs for a particular service and saved to a file named `logs.txt`:
12754

12855
```bash
129-
./beacon_node.sh <DATADIR> <NETWORK-PORT> <QUIC-PORT> <HTTP-PORT> <EXECUTION-ENDPOINT> <EXECUTION-JWT-PATH> <OPTIONAL-DEBUG-LEVEL>
130-
```
131-
e.g.
132-
```bash
133-
./beacon_node.sh $HOME/.lighthouse/local-testnet/node_1 9001 9101 8001 http://localhost:5001 ~/.lighthouse/local-testnet/geth_1/geth/jwtsecret
56+
kurtosis service logs local-testnet $SERVICE_NAME -a > logs.txt
13457
```
58+
where `$SERVICE_NAME` can be viewed by running `kurtosis enclave inspect local-testnet`.
13559

136-
In a new terminal, start the validator client which will attach to the first
137-
beacon node:
60+
Kurtosis comes with a Dora explorer which can be opened with:
13861

13962
```bash
140-
./validator_client.sh <DATADIR> <BEACON-NODE-HTTP> <OPTIONAL-DEBUG-LEVEL>
141-
```
142-
e.g. to attach to the above created beacon node
143-
```bash
144-
./validator_client.sh $HOME/.lighthouse/local-testnet/node_1 http://localhost:8001
63+
open $(kurtosis port print local-testnet dora http)
14564
```
14665

147-
You can create additional geth, beacon node and validator client instances by changing the ports, e.g., for a second geth, beacon node and validator client:
66+
Some testnet parameters can be varied by modifying the `network_params.yaml` file. Kurtosis also comes with a web UI which can be open with `kurtosis web`.
14867

149-
```bash
150-
./geth.sh $HOME/.lighthouse/local-testnet/geth_2 7002 6002 5002 genesis.json
151-
./beacon_node.sh $HOME/.lighthouse/local-testnet/node_2 9002 9102 8002 http://localhost:5002 ~/.lighthouse/local-testnet/geth_2/geth/jwtsecret
152-
./validator_client.sh $HOME/.lighthouse/local-testnet/node_2 http://localhost:8002
153-
```
154-
155-
## Additional Info
156-
157-
### Adjusting number and distribution of validators
158-
The `VALIDATOR_COUNT` parameter is used to specify the number of insecure validator keystores to generate and make deposits for.
159-
The `BN_COUNT` parameter is used to adjust the division of these generated keys among separate validator client instances.
160-
For e.g. for `VALIDATOR_COUNT=80` and `BN_COUNT=4`, the validator keys are distributed over 4 datadirs with 20 keystores per datadir. The datadirs are located in `$DATADIR/node_{i}` which can be passed to separate validator client
161-
instances using the `--datadir` parameter.
162-
163-
### Starting fresh
68+
## Stopping the testnet
16469

165-
You can delete the current testnet and all related files using the following command. Alternatively, if you wish to start another testnet, doing the steps [Starting the testnet](./README.md#starting-the-testnet) will automatically delete the files and start a fresh local testnet.
70+
To stop the testnet, from the Lighthouse root repository:
16671

16772
```bash
168-
./clean.sh
73+
cd ./scripts/local_testnet
74+
./stop_local_testnet.sh
16975
```
17076

171-
### Updating the genesis time of the beacon state
77+
You will see "Local testnet stopped." at the end.
17278

173-
If it's been a while since you ran `./setup` then the genesis time of the
174-
genesis state will be far in the future, causing lots of skip slots.
79+
## CLI options
17580

176-
Update the genesis time to now using:
81+
The script comes with some CLI options, which can be viewed with `./start_local_testnet.sh --help`. One of the CLI options is to avoid rebuilding Lighthouse each time the testnet starts, which can be configured with the command:
17782

17883
```bash
179-
./reset_genesis_time.sh
180-
```
181-
182-
> Note: you probably want to just rerun `./start_local_testnet.sh` to start over
183-
> but this is another option.
184-
185-
### Testing builder flow
186-
187-
1. Add builder URL to `BN_ARGS` in `./vars.env`, e.g. `--builder http://localhost:8650`. Some mock builder server options:
188-
- [`mock-relay`](https://github.com/realbigsean/mock-relay)
189-
- [`dummy-builder`](https://github.com/michaelsproul/dummy_builder)
190-
2. The above mock builders do not support non-mainnet presets as of now, and will require setting `SECONDS_PER_SLOT` and `SECONDS_PER_ETH1_BLOCK` to `12` in `./vars.env`.
191-
3. Start the testnet with the following command (the `-p` flag enables the validator client `--builder-proposals` flag):
192-
```bash
193-
./start_local_testnet.sh -p genesis.json
194-
```
195-
4. Block production using builder flow will start at epoch 4.
196-
197-
### Testing sending a transaction
198-
199-
Some addresses in the local testnet are seeded with testnet ETH, allowing users to carry out transactions. To send a transaction, we first add the address to a wallet, such as [Metamask](https://metamask.io/). The private keys for the addresses are listed [here](https://github.com/sigp/lighthouse/blob/441fc1691b69f9edc4bbdc6665f3efab16265c9b/testing/execution_engine_integration/src/execution_engine.rs#L13-L14).
200-
201-
Next, we add the local testnet to Metamask, a brief guide can be found [here](https://support.metamask.io/hc/en-us/articles/360043227612-How-to-add-a-custom-network-RPC). If you start the local testnet with default settings, the network RPC is: http://localhost:6001 and the `Chain ID` is `4242`, as defined in [`vars.env`](https://github.com/sigp/lighthouse/blob/441fc1691b69f9edc4bbdc6665f3efab16265c9b/scripts/local_testnet/vars.env#L42). Once the network and account are added, you should see that the account contains testnet ETH which allow us to carry out transactions.
84+
./start_local_testnet.sh -b false
85+
```

0 commit comments

Comments
 (0)