Skip to content

Latest commit

 

History

History
290 lines (227 loc) · 12.4 KB

fullnode.md

File metadata and controls

290 lines (227 loc) · 12.4 KB
title
Run a Sui Full Node

Note: These instructions are for advanced users. If you just need a local development environment, you should instead follow the instructions in Create a Local Sui Network to create a local Full node, validators, and faucet.

Sui Full nodes validate blockchain activities, including transactions, checkpoints, and epoch changes. Each Full node stores and services the queries for the blockchain state and history.

This role enables validators to focus on servicing and processing transactions. When a validator commits a new set of transactions (or a block of transactions), the validator pushes that block to all connected Full nodes that then service the queries from clients.

Features

Sui Full nodes:

  • Track and verify the state of the blockchain, independently and locally.
  • Serve read requests from clients.

State synchronization

Sui Full nodes sync with validators to receive new transactions on the network.

A transaction requires a few round trips to 2f+1 validators to form a transaction certificate (TxCert).

This synchronization process includes:

  1. Following 2f+1 validators and listening for newly committed transactions.
  2. Making sure that 2f+1 validators recognize the transaction and that it reaches finality.
  3. Executing the transaction locally and updating the local DB.

This synchronization process requires listening to at a minimum 2f+1 validators to ensure that a Full node has properly processed all new transactions. Sui will improve the synchronization process with the introduction of checkpoints and the ability to synchronize with other Full nodes.

Architecture

A Sui Full node is essentially a read-only view of the network state. Unlike validator nodes, Full nodes cannot sign transactions, although they can validate the integrity of the chain by re-executing transactions that a quorum of validators previously committed.

Today, a Sui Full node maintains the full history of the chain.

Validator nodes store only the latest transactions on the frontier of the object graph (for example, transactions with >0 unspent output objects).

Full node setup

Follow the instructions here to run your own Sui Full.

Hardware requirements

Suggested minimum hardware to run a Sui Full node:

  • CPUs: 8 physical cores / 16 vCPUs
  • RAM: 128 GB
  • Storage (SSD): 2 TB NVMe drive

Software requirements

Sui recommends running Sui Full nodes on Linux. Sui supports the Ubuntu and Debian distributions. You can also run a Sui Full node on macOS.

Make sure to update Rust.

Use the following command to install additional Linux dependencies.

sudo apt-get update \
&& sudo apt-get install -y --no-install-recommends \
tzdata \
libprotobuf-dev \
ca-certificates \
build-essential \
libssl-dev \
libclang-dev \
pkg-config \
openssl \
protobuf-compiler \
git \
clang \
cmake

Configure a Full node

You can configure a Sui Full node either using Docker or by building from source.

Using Docker Compose

Follow the instructions in the Full node Docker Readme to run a Sui Full node using Docker, including resetting the environment.

Setting up a local Sui repository

You must get the latest source files from the Sui GitHub repository.

  1. Set up your fork of the Sui repository:
    1. Go to the Sui repository on GitHub and click the Fork button in the top right-hand corner of the screen.
    2. Clone your personal fork of the Sui repository to your local machine (ensure that you insert your GitHub username into the URL): 
      git clone https://github.com/<YOUR-GITHUB-USERNAME>/sui.git
  2. cd into your sui repository: 
    cd sui
  3. Set up the Sui repository as a git remote: 
    git remote add upstream https://github.com/MystenLabs/sui
  4. Sync your fork: 
    git fetch upstream
  5. Check out the branch associated with the network version you want to run (for example, devnet to run a Devnet Full node): 
    git checkout --track upstream/<BRANCH-NAME>

Setting up a Full node from source

Open a Terminal or Console to the sui directory you downloaded in the previous steps to complete the following:

  1. Install the required Prerequisites.
  2. Make a copy of the Full node YAML template: 
    cp crates/sui-config/data/fullnode-template.yaml fullnode.yaml
  3. Download the genesis blob for the network to use:
    • Devnet genesis blob: 
      curl -fLJO https://github.com/MystenLabs/sui-genesis/raw/main/devnet/genesis.blob
    • Testnet genesis blob: 
      curl -fLJO https://github.com/MystenLabs/sui-genesis/raw/main/testnet/genesis.blob
    • Mainnet genesis blob 
      curl -fLJO https://github.com/MystenLabs/sui-genesis/raw/main/mainnet/genesis.blob
  4. Testnet and Mainnet Full nodes only: Edit the fullnode.yaml file to include peer nodes for state synchronization. Append the following to the end of the current configuration:
    • Testnet 
      p2p-config:
  seed-peers:
    - address: /dns/ewr-tnt-ssfn-00.testnet.sui.io/udp/8084
      peer-id: df8a8d128051c249e224f95fcc463f518a0ebed8986bbdcc11ed751181fecd38
    - address: /dns/lax-tnt-ssfn-00.testnet.sui.io/udp/8084
      peer-id: f9a72a0a6c17eed09c27898eab389add704777c03e135846da2428f516a0c11d
    - address: /dns/lhr-tnt-ssfn-00.testnet.sui.io/udp/8084
      peer-id: 9393d6056bb9c9d8475a3cf3525c747257f17c6a698a7062cbbd1875bc6ef71e
    - address: /dns/mel-tnt-ssfn-00.testnet.sui.io/udp/8084
      peer-id: c88742f46e66a11cb8c84aca488065661401ef66f726cb9afeb8a5786d83456e
    • Mainnet 
      p2p-config:
  seed-peers:
    - address: /dns/icn-00.mainnet.sui.io/udp/8084
      peer-id: 303f1f35afc9a6f82f8d21724f44e1245f4d8eca0806713a07c525dadda95a66
    - address: /dns/icn-01.mainnet.sui.io/udp/8084
      peer-id: cb7ce193cf7a41e9cc2f99e65dd1487b6314a57c74be42cc8c9225b203301812
    - address: /dns/mel-00.mainnet.sui.io/udp/8084
      peer-id: d32b55bdf1737ec415df8c88b3bf91e194b59ee3127e3f38ea46fd88ba2e7849
    - address: /dns/mel-01.mainnet.sui.io/udp/8084
      peer-id: bbf3be337fc16614a1953da83db729abfdc40596e197f36fe408574f7c9b780e
    - address: /dns/ewr-00.mainnet.sui.io/udp/8084
      peer-id: c7bf6cb93ca8fdda655c47ebb85ace28e6931464564332bf63e27e90199c50ee
    - address: /dns/ewr-01.mainnet.sui.io/udp/8084
      peer-id: 3227f8a05f0faa1a197c075d31135a366a1c6f3d4872cb8af66c14dea3e0eb66
    - address: /dns/sjc-00.mainnet.sui.io/udp/8084
      peer-id: 6f0b25087cd6b2fd2e4329bcf308ac95a37c49277dd7286b72470c124809db5b
    - address: /dns/sjc-01.mainnet.sui.io/udp/8084
      peer-id: af1d5d8468b3612ac2b6ff3ca91e99a71390dbe5b83dea9f6ae2da708d689227
    - address: /dns/lhr-00.mainnet.sui.io/udp/8084
      peer-id: c619a5e0f8f36eac45118c1f8bda28f0f508e2839042781f1d4a9818043f732c
    - address: /dns/lhr-01.mainnet.sui.io/udp/8084
      peer-id: 53dcedf250f73b1ec83250614498947db00d17c0181020fcdb7b6db12afbc175
  5. Optional: Skip this step to accept the default paths to resources. Edit the fullnode.yaml file to use custom paths.
    • Update the db-path field with the path to the Full node database. 
      db-path: "/db-files/sui-fullnode"
    • Update the genesis-file-location with the path to genesis.blob. 
      genesis:
  genesis-file-location: "/sui-fullnode/genesis.blob"
  6. Optional: To save disk space on your Full node, add the following settings to your fullnode.yaml file to enable aggressive pruning: 
    authority-store-pruning-config:
  num-latest-epoch-dbs-to-retain: 3
  epoch-db-pruning-period-secs: 3600
  num-epochs-to-retain: 0
  max-checkpoints-in-batch: 10
  max-transactions-in-batch: 1000

Starting services

At this point, your Sui Full node is ready to connect to the Sui network.

  1. Open a Terminal or Console to the sui directory.
  2. Start the Sui Full node: 
    cargo run --release --bin sui-node -- --config-path fullnode.yaml
  3. Optional: Publish/subscribe to notifications using JSON-RPC via websocket.

If your setup is successful, your Sui Full node is now connected to the appropriate network.

Your Full node serves the read endpoints of the Sui JSON-RPC API at: http://127.0.0.1:9000.

Troubleshooting

If you receive a cannot find -lpq error, you are missing the libpq library. Use sudo apt-get install libpq-dev to install on Linux, or brew install libpq on MacOS. After you install on MacOS, create a Homebrew link using brew link --force libpq. For further context, reference the issue on Stack Overflow.

If you receive the following error:

panicked at 'error binding to 0.0.0.0:9184: error creating server listener: Address already in use (os error 98)

Then update the metrics address in your fullnode.yaml file to use port 9180.

metrics-address: "0.0.0.0:9180"

Sui Explorer with your Full node

Sui Explorer supports connections to custom RPC URLS and local networks. You can point the Explorer to your local Full node and see the transactions it syncs from the network.

  1. Open a browser and go to: https://suiexplorer.com/
  2. Click Mainnet in the network drop-down at the top right-hand corner (or three bars on smaller screens) and select Local to connect to a local network, or select Custom RPC URL and then enter the URL.

Sui Explorer displays information about the selected network.

Monitoring

Monitor your Full node using the instructions at Logging, Tracing, Metrics, and Observability.

The default metrics port is 9184. To change the port, edit your fullnode.yaml file.

Update your Full node

Whenever Sui releases a new version, you must update your Full node with the release to ensure compatibility with the network it connects to. For example, if you use Sui Testnet you should install the version of Sui running on Sui Testnet.

Update with Docker Compose

Follow the instructions to reset the environment, namely by running the command:

docker-compose down --volumes

Update from source

If you followed the instructions for Building from Source, use the following steps to update your Full node:

  1. Shut down your running Full node.
  2. cd into your local Sui repository: 
    cd sui
  3. Remove the database and 'genesis.blob' file: 
    rm -r suidb genesis.blob
  4. Fetch the source from the latest release: 
    git fetch upstream
  5. Reset your branch: 
    git checkout -B <BRANCH-NAME> --track upstream/<BRANCH-NAME>
  6. Download the latest genesis blob:
    • Devnet genesis blob: 
      curl -fLJO https://github.com/MystenLabs/sui-genesis/raw/main/devnet/genesis.blob
    • Testnet genesis blob - supported only when there is an active public Testnet network 
      curl -fLJO https://github.com/MystenLabs/sui-genesis/raw/main/testnet/genesis.blob
  7. Update your fullnode.yaml configuration file if needed.
  8. Restart your Sui Full node: 
    cargo run --release --bin sui-node -- --config-path fullnode.yaml

Your Full node starts on: http://127.0.0.1:9000.