sui-local-net-demo

sui-local-net-demo demonstrates how to:

1. start a local Sui network using sui-test-validator and sui start, and
2. generate a genesis file using sui genesis-ceremony and run a Sui validator node using sui-node on a local machine.

Important

This repo is intended to serve for informational purposes only.

Note

This demo was tested using:

• Rust: rustc 1.76.0 (07dca489a 2024-02-04)
• Sui: sui 1.21.0-473e4e256

Preliminary steps

Preliminary steps include installing dependencies and generating configs.

1. Update Rust and update/install Sui as described in Sui Docs:

rustup update stable
cargo install --locked --git https://github.com/MystenLabs/sui.git --branch main sui

2. If you would like to run a local Sui network with a persisted state, generate a config to store db and genesis configs:

SUI_LOCAL_CONFIG_DIR=<some-directory>
mkdir $SUI_LOCAL_CONFIG_DIR
sui genesis -f --with-faucet --working-dir=$SUI_LOCAL_CONFIG_DIR

3. Clone the Sui repo:

git clone https://github.com/MystenLabs/sui.git && cd sui

4. In the root folder of the sui repo, install a local Sui Explorer:

sudo npm install -g pnpm
pnpm install
pnpm turbo build

• If the EHOSTUNREACH error appears, disable IPv6, and then repeat the installation:

  sudo sudo sysctl -w net.ipv6.conf.all.disable_ipv6=1

5. Start the Sui Explorer dev server by running the following command in the root folder of the sui repo:

pnpm explorer dev

• If you open the local Sui Explorer at http://localhost:3000/ and it redirects to the following you will need to modify the following line in apps/explorer/src/components/Layout/PageLayout.tsx in the root folder of the sui repo:

  const enableExplorerRedirect = useFeatureIsOn('explorer-redirect');

  to

  const enableExplorerRedirect = false; //useFeatureIsOn('explorer-redirect');

  (there is no need to repeat steps 4-5 of this section after the modification is made). The local Sui Explorer at http://localhost:3000/ should then look as follows:

---

Closing steps

Closing steps are meant to be taken after the local Sui network is started, to verify that it is running.

1. Once the local network is started using one of the methods provided below, it can be verified that it is running using a simple request:

curl --location --request POST 'http://127.0.0.1:9000' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "sui_getTotalTransactionBlocks",
    "params": []
  }'

2. Keeping the explorer dev server running (step 5 in Preliminary steps), open the local Sui Explorer at the following URL: http://localhost:3000/.

---

Method 1: Use sui-test-validator

Sui-provides the sui-test-validator binary that starts a local network that includes a Sui Full node, a Sui validator, a Sui faucet and (optionally) an indexer. This method is the simplest one and it is recommended in the official Sui tutorial Connect to a Local Network.

1. Navigate to the root folder of the sui repo (cloned in step 3 of Preliminary steps) and build sui-test-validator:

cd sui && cargo build --bin sui-test-validator

2. Start the local network using the following command:

RUST_LOG="off,sui_node=info" ./target/debug/sui-test-validator

3. To start the local Sui network with a persisted state (make sure you completed step 2 of Preliminary steps), use the following command:

RUST_LOG="off,sui_node=info" \
  ./target/debug/sui-test-validator --config-dir $SUI_LOCAL_CONFIG_DIR

4. In another terminal window, verify that the local network is running as described in step 1 of Closing steps.

5. On the local Sui explorer, observe that the local network is running es described in step 2 of Closing steps.

---

Method 2: Use sui start

sui start starts a local Sui network by running pre-generated genesis configs.

1. Make sure you completed step 2 of Preliminary steps as it is required to generate genesis configs in this method.

2. Start the local Sui network using the following command:

RUST_LOG="off,sui_node=info" \
  sui start --network.config=$SUI_LOCAL_CONFIG_DIR/network.yaml

3. In another terminal window, verify that the local network is running as described in step 1 of Closing steps.

4. On the local Sui explorer, observe that the local network is running es described in step 2 of Closing steps.

---

Run a Sui validator node using sui genesis-ceremony and sui-node

Generate genesis.blob

sui genesis-ceremony orchestrates a Sui Genesis Ceremony.

Important

Steps 1-3, 10 should be performed only by the master of ceremony.

Steps 2, 4-9, 11 should be performed by each participating validator.

1. Create a new empty GitHub repo. Assume it is named sui-genesis-demo.

2. Clone the repo on a local machine and navigate to its root folder:

git clone https://github.com/<owner>/sui-genesis-demo.git && cd sui-genesis-demo

3. Initialize a Sui genesis ceremony and push the changes to the repo:

sui genesis-ceremony init
git add .
git commit -S -m "init genesis"
git push -u origin main

4. Generate a protocol key (see Sui Node Key Management for detail):

k=$(sui keytool generate bls12381 | grep suiAddress | awk '{print $4}'); \
  mv bls-$k.key val_0.key

5. Generate a worker key:

k=$(sui keytool generate ed25519 | grep suiAddress | awk '{print $4}'); \
  mv $k.key val_0_worker.key

6. Generate an account key:

k=$(sui keytool generate ed25519 | grep suiAddress | awk '{print $4}'); \
  mv $k.key val_0_account.key

7. Generate a network key:

k=$(sui keytool generate ed25519 | grep suiAddress | awk '{print $4}'); \
  mv $k.key val_0_network.key

8. Add validator information:

sui genesis-ceremony add-validator \
  --name validator-0 \
  --validator-key-file val_0.key \
  --worker-key-file val_0_worker.key \
  --account-key-file val_0_account.key \
  --network-key-file val_0_network.key \
  --network-address /ip4/0.0.0.0/tcp/8080/http \
  --narwhal-primary-address /ip4/0.0.0.0/udp/8081/http \
  --narwhal-worker-address /ip4/0.0.0.0/udp/8082/http \
  --p2p-address /ip4/0.0.0.0/udp/8084/http \
  --description "Local Sui validator 0" \
  --image-url https://github.com/MystenLabs/sui/blob/main/docs/site/static/img/logo.svg \
  --project-url https://github.com/roman1e2f5p8s/sui-local-net-demo

Information about addresses can be found in Connectivity ports. Values for arguments image-url and project-url can be specified as empty strings.

9. Push the changes to the repo:

git add .
git commit -S -m "add validator-0 information"
git push -u origin main

10. Once all validators have been added, the master of ceremony needs to build the genesis object and push the changes to the repo:

sui genesis-ceremony build-unsigned-checkpoint
git add .
git commit -S -m "build genesis"
git push -u origin main

11. Each validator will then need to verify and sign genesis and push the changes to the repo:

sui genesis-ceremony verify-and-sign --key-file val_0.key
git add .
git commit -S -m "verify and sign genesis"
git push -u origin main

12. Once all validators have successfully verified and signed genesis, the master of ceremony needs to finalize the ceremony and then the genesis state can be distributed:

sui genesis-ceremony finalize
git add .
git commit -S -m "finalize genesis"
git push -u origin main

For this demonstration, we used the sui-genesis-demo repo, where you can find all files generated during the ceremony.

Run a Sui node using systemd

Follow these steps to setup a Sui node as a systemd service. See Run a Sui Node using Systemd | MystenLabs/Sui for detail.

1. Add a sui user and setup the /opt/sui directory as follows:

sudo useradd sui
sudo mkdir -p /opt/sui/bin
sudo mkdir -p /opt/sui/config
sudo mkdir -p /opt/sui/db
sudo mkdir -p /opt/sui/key-pairs
sudo chown -R sui:sui /opt/sui

2. Navigate to the root folder of the sui repo (cloned in step 3 of Preliminary steps), build sui-node, and copy the built binary into /opt/sui/bin/:

cd sui && git checkout $SUI_SHA
cargo build --release --bin sui-node
sudo cp ./target/release/sui-node /opt/sui/bin/

3. Navigate to the sui-genesis-demo repo (see step 2 of Generate genesis.blob) and copy key-pairs generated in steps 4-7 of Generate genesis.blob into /opt/sui/key-pairs/ as follows:

cd sui-genesis-demo
sudo cp val_0.key /opt/sui/key-pairs/protocol.key
sudo cp val_0_worker.key /opt/sui/key-pairs/worker.key
sudo cp val_0_network.key /opt/sui/key-pairs/network.key
sudo cp val_0_account.key /opt/sui/key-pairs/account.key

4. Download the node configuration file provided by Sui from here and place it into the /opt/sui/config/ directory:

sudo mv validator.yaml /opt/sui/config/

5. Open /opt/sui/config/validator.yaml and modify the following line:

  external-address: /dns/$HOSTNAME/udp/8084 # UPDATE THIS

to

  external-address: /ip4/0.0.0.0/udp/8084/http

and save the file.

6. Navigate to the sui-genesis-demo repo (see step 2 of Generate genesis.blob) and copy genesis.blob into /opt/sui/config/:

cd sui-genesis-demo && sudo cp genesis.blob /opt/sui/config/

7. After copying and creating files in /opt/sui, make sure they retain sui user permissions by re-running

sudo chown -R sui:sui /opt/sui

8. Download the sui-node systemd service unit file provided by Sui from here and place it into the /etc/systemd/system/ directory:

sudo mv sui-node.service /etc/systemd/system/

9. Reload systemd and enable this new service unit file:

sudo systemctl daemon-reload
sudo systemctl enable sui-node.service

10. Start the validator node:

sudo systemctl start sui-node

• Check that the node is up and running:

  sudo systemctl status sui-node

  
• The logs can be shown by running:

  journalctl -u sui-node -f

• To stop sui-node systemd service, run:

  sudo systemctl stop sui-node

• To delete the local Sui node databases, run:

  sudo rm -rf /opt/sui/db/*

---

Sources

• sui-test-validator | MystenLabs/Sui
• Connect to a Local Network | Sui Docs
• Start sui-test-validator (local network) inside docker container | Issues
• Genesis Ceremony | MystenLabs/Sui
• Sui for Node Operators | MystenLabs/Sui
• Run a Sui Node using Systemd | MystenLabs/Sui