Skip to main content

Sui Full Node Configuration

info

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): 4 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 \
libpq-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. For Testnet or Mainnet: Edit the fullnode.yaml file to include peer nodes for state synchronization. Append the following to the end of the current configuration:

    p2p-config:
      seed-peers:
        - address: /dns/mel-00.mainnet.sui.io/udp/8084
          peer-id: d32b55bdf1737ec415df8c88b3bf91e194b59ee3127e3f38ea46fd88ba2e7849
        - 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/lhr-00.mainnet.sui.io/udp/8084
          peer-id: c619a5e0f8f36eac45118c1f8bda28f0f508e2839042781f1d4a9818043f732c
        - address: /dns/sui-mainnet-ssfn-1.nodeinfra.com/udp/8084
          peer-id: 0c52ca8d2b9f51be4a50eb44ace863c05aadc940a7bd15d4d3f498deb81d7fc6
        - address: /dns/sui-mainnet-ssfn-2.nodeinfra.com/udp/8084
          peer-id: 1dbc28c105aa7eb9d1d3ac07ae663ea638d91f2b99c076a52bbded296bd3ed5c
        - address: /dns/sui-mainnet-ssfn-ashburn-na.overclock.run/udp/8084
          peer-id: 5ff8461ab527a8f241767b268c7aaf24d0312c7b923913dd3c11ee67ef181e45
        - address: /dns/sui-mainnet-ssfn-dallas-na.overclock.run/udp/8084
          peer-id: e1a4f40d66f1c89559a195352ba9ff84aec28abab1d3aa1c491901a252acefa6
        - address: /dns/ssn01.mainnet.sui.rpcpool.com/udp/8084
          peer-id: fadb7ccb0b7fc99223419176e707f5122fef4ea686eb8e80d1778588bf5a0bcd
        - address: /dns/ssn02.mainnet.sui.rpcpool.com/udp/8084
          peer-id: 13783584a90025b87d4604f1991252221e5fd88cab40001642f4b00111ae9b7e

  5. Optional: Skip this step to accept the default paths to resources. Edit the fullnode.yaml file to use custom paths.

  6. Update the db-path field with the path to the Full node database. db-path: "/db-files/sui-fullnode"

  7. Update the genesis-file-location with the path to genesis.blob.

    genesis:
        genesis-file-location: "/sui-fullnode/genesis.blob"

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"

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:
      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.

Object pruning​

Sui adds new object versions to the database as part of transaction execution. This makes previous versions ready for garbage collection. However, without pruning, this can result in database performance degradation and requires large amounts of storage space. Sui identifies the objects that are eligible for pruning in each checkpoint, and then performs the pruning in the background.

You can enable pruning for a Sui node by adding the authority-store-pruning-config config to fullnode.yaml file:

authority-store-pruning-config:
  # Number of epoch dbs to keep 
  # Not relevant for object pruning
  num-latest-epoch-dbs-to-retain: 3
  # The amount of time, in seconds, between running the object pruning task.
  # Not relevant for object pruning
  epoch-db-pruning-period-secs: 3600
  # Number of epochs to wait before performing object pruning.
  # When set to 0, Sui prunes old object versions as soon
  # as possible. This is also called *aggressive pruning*, and results in the most effective
  # garbage collection method with the lowest disk usage possible. 
  # This is the recommended setting for Sui Validator nodes since older object versions aren't
  # necessary to execute transactions.
  # When set to 1, Sui prunes only object versions from transaction checkpoints
  # previous to the current epoch. In general, when set to N (where N >= 1), Sui prunes  
  # only object versions from checkpoints up to `current - N` epoch. 
  # It is therefore possible to have multiple versions of an object present 
  # in the database. This setting is recommended for Sui Full nodes as they might need to serve 
  # RPC requests that require looking up objects by ID and Version (rather than just latest
  # version). However, if your Full node does not serve RPC requests you should then also enable  
  # aggressive pruning.
  num-epochs-to-retain: 0
  # Advanced setting: Maximum number of checkpoints to prune in a batch. The default
  # settings are appropriate for most use cases.
  max-checkpoints-in-batch: 10
  # Advanced setting: Maximum number of transactions in one batch of pruning run. The default
  # settings are appropriate for most use cases.
  max-transactions-in-batch: 1000

Transaction pruning​

Transaction pruning removes previous transactions and effects from the database. Sui periodically creates checkpoints. Each checkpoint contains the transactions that occurred during the checkpoint and their associated effects.

Sui performs transaction pruning in the background after checkpoints complete.

You can enable transaction pruning for your Full node or Validator node by adding num-epochs-to-retain-for-checkpoints to the authority-store-pruning-config config for the node:

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
  # Number of epochs to wait before performing transaction pruning.
  # When this is N (where N >= 2), Sui prunes transactions and effects from 
  # checkpoints up to the `current - N` epoch. Sui never prunes transactions and effects from the current and
  # immediately prior epoch. N = 2 is a recommended setting for Sui Validator nodes and Sui Full nodes that don't 
  # serve RPC requests.
  num-epochs-to-retain-for-checkpoints: 2
  # Ensures that individual database files periodically go through the compaction process.
  # This helps reclaim disk space and avoid fragmentation issues
  periodic-compaction-threshold-days: 1
info

If you prune transactions, Archival nodes can help ensure lagging peer nodes don't lose any information. For more information, see Sui Archives.