Skip to main content

IOTA 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 IOTA Network to create a local Full node, validators, and faucet.

IOTA 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​

IOTA Full nodes:

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

State synchronization​

IOTA 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. IOTA will improve the synchronization process with the introduction of checkpoints and the ability to synchronize with other Full nodes.

Architecture​

An IOTA 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, an IOTA 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 IOTA Full node.

Hardware requirements​

Suggested minimum hardware to run an IOTA Full node:

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

Software requirements​

IOTA recommends running IOTA Full nodes on Linux. IOTA supports the Ubuntu and Debian distributions. You can also run an IOTA 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 an IOTA Full node either using Docker or by building from source.

Using Docker Compose​

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

Setting up a local IOTA repository​

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

  1. Set up your fork of the IOTA repository:
    1. Go to the IOTA repository on GitHub and click the Fork button in the top right-hand corner of the screen.
    2. Clone your personal fork of the IOTA repository to your local machine (ensure that you insert your GitHub username into the URL): git clone https://github.com/<YOUR-GITHUB-USERNAME>/iota.git
  2. cd into your iota repository: cd iota
  3. Set up the IOTA repository as a git remote: git remote add upstream https://github.com/iotaledger/iota
  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 iota 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/iota-config/data/fullnode-template.yaml fullnode.yaml

  3. Download the genesis and migration blob for the network to use:

  4. For Testnet or Devnet: 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/access-0.r.testnet.iota.cafe/udp/8084
          peer-id: 46064108d0b689ed89d1f44153e532bb101ce8f8ca3a3d01ab991d4dea122cfc
        - address: /dns/access-1.r.testnet.iota.cafe/udp/8084
          peer-id: 8ffd25fa4e86c30c3f8da7092695e8a103462d7a213b815d77d6da7f0a2a52f5

  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/iota-fullnode"

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

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

  8. Update the migration-tx-data-path with the path to the migration.blob

    migration-tx-data-path: "/opt/iota/config/migration.blob"

Compiling the node​

Run the following command to compile the iota-node.

cargo run --release --bin iota-node

Starting services​

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

  1. Open a terminal or console to the iota directory.
  2. Start the IOTA Full node: ./target/release/iota-node --config-path fullnode.yaml
  3. Optional: Publish/subscribe to notifications using JSON-RPC via websocket.

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

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

Troubleshooting​

If, during the compilation step, 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 in the Node Monitoring and Metrics section.

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

Update your Full node​

Whenever IOTA 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 IOTA Testnet you should install the version of IOTA running on IOTA 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 IOTA repository: 
    cd iota
  3. Remove the database, 'genesis.blob' and 'migration.blob' file: 
    rm -r iotadb genesis.blob migration.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 and migration blob:
  7. Update your fullnode.yaml configuration file, if needed.
  8. Recompile your IOTA Full node with the same command as in Compiling the node:
  9. Restart your IOTA Full node: 
    ./target/release/iota-node --config-path fullnode.yaml

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

Object pruning​

IOTA 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. IOTA identifies the objects that are eligible for pruning in each checkpoint, and then performs the pruning in the background.

You can enable pruning for an IOTA 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, IOTA 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 IOTA Validator nodes since older object versions aren't
  # necessary to execute transactions.
  # When set to 1, IOTA prunes only object versions from transaction checkpoints
  # previous to the current epoch. In general, when set to N (where N >= 1), IOTA 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 IOTA Full nodes as they might need to serve
  # RPC requests that require looking up objects by ID and Version (rather than just the 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. IOTA periodically creates checkpoints. Each checkpoint contains the transactions that occurred during the checkpoint and their associated effects.

IOTA 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), IOTA prunes transactions and effects from
  # checkpoints up to the `current - N` epoch. IOTA never prunes transactions and effects from the current and
  # immediately prior epoch. N = 2 is a recommended setting for IOTA Validator nodes and IOTA 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 IOTA Archives.

Question 1/3

In the context of IOTA Full nodes, what is the significance of the 2f+1 validators during transaction processing?