Set Up Flare Entity

This guide provides a sample deployment configuration for infrastructure providers looking to a Flare Entity, consisting of a validator node and a data provider system (FSP) for the Flare network. The FSP consists of Flare Time Series Oracle (FTSO) and Flare Data Connector (FDC).

A Flare Entity consists of the following six components:

1. Flare System Client: Manages interactions with FTSO smart contracts, including data collection, submission, voter registration, and system tasks.
2. C-chain Indexer: Tracks FSP-related blockchain transactions and events, enabling data calculations and action triggers.
3. FTSO Client: Provides anchor feed submissions and median data to the System Client.
4. Fast Updates Client: Submits block-latency feeds to Fast Updates contracts.
5. Feed Value Provider: Retrieves data from exchanges and supplies current feed values (prices).
6. FDC Client: Provides FDC protocol voting round data to the System Client.

Prerequisites

• A machine meeting the minimum hardware requirements.
• A registered validator node.
• Docker Engine, ensure the Docker data root directory has sufficient disk space. If necessary, configure Docker to use a specific storage location or mount point (refer to Docker's storage documentation).
• jq
• envsubst
• yarn (optional, for performing automated registration on testnets)

tip

To avoid using sudo each time you run the docker command, add your user to the Docker group after installation:

sudo usermod -a -G docker $USER

Log out and log back in or restart your system for the changes to take effect.

Rewards

Minimal conditions

After the introduction of minimal conditions in FIP.10, a Flare Entity needs to be both available and performant across all Flare protocols in order to be eligible for rewards.

• FSP rewards information is available at flare-foundation/fsp-rewards and on the Discourse Forum (see XLSX file for historical reward data). Updated every reward epoch (3.5 days), with epochs starting on Monday and Thursday.
• Validator staking rewards information is available at flare-foundation/reward-scripts. Updated every reward epoch (3.5 days), with epochs starting on Monday and Thursday.

Learn how to check your Flare Entity rewards in the FAQs section.

Registration

Before deploying the Flare Entity components, several one-time registration steps must be completed on-chain. This involves registering operational addresses for the Flare System Provider (FSP), funding them, registering a sortition key for Fast Updates, and linking your validator node ID to your entity's identity.

Register and fund FSP addresses

You need five specific addresses for FSP operations. You can register them using an automated script (Testnets only) or manually via contract calls (Mainnet).

Method 1: Automated Registration (Testnets only).

danger

This automated method requires placing private keys in a JSON file. This significantly increases security risk and is NOT recommended for mainnet. Use this method only where key security is less critical. For mainnet, always use Method 2: Manual process.

On testnets, you can automate the registration of your five FSP addresses and your sortition public key using scripts from the flare-smart-contracts-v2 repository.

1. Clone and build flare-smart-contracts-v2:

   git clone https://github.com/flare-foundation/flare-smart-contracts-v2/
   cd flare-smart-contracts-v2
   yarn
   yarn c

2. Create an entities.json file with the following account addresses and private keys. Generate a sortition private key by following step 1 in Register sortition key. :

   [
     {
       "identity": {
         "address": "<address>",
         "privateKey": "<private key hex>"
       },
       "submit": {
         "address": "<address>",
         "privateKey": "<private key hex>"
       },
       "submitSignatures": {
         "address": "<address>",
         "privateKey": "<private key hex>"
       },
       "signingPolicy": {
         "address": "<address>",
         "privateKey": "<private key hex>"
       },
       "delegation": {
         "address": "<address>",
         "privateKey": "<private key hex>"
       },
       "sortitionPrivateKey": "<private key hex>"
     }
   ]

3. Rename .env.template to .env and add the path to your entities.json file:

   .env

   ENTITIES_FILE_PATH=entities.json # <-- REPLACE WITH PATH TO YOUR entities.json

4. Run the registration tasks (register-entities.ts and register-public-keys.ts):

   Flare Testnet Coston2

   yarn run register_entities_network_coston2
   yarn run register_public_keys_network_coston2

   Songbird Testnet Coston

   yarn run register_entities_network_coston
   yarn run register_public_keys_network_coston

If these scripts complete successfully, you have registered both the FSP addresses and the sortition key. You can proceed directly to Fund FSP addresses.

Method 2: Manual registration

On mainnet, or if you prefer not to use the automated script on testnets, you must manually register the required FSP addresses by interacting directly with the EntityManager smart contract.

1. Ensure you have generated the following five addresses and securely stored their private keys. Understand their roles:

   • Identity: The central identity address. Crucially, keep the private key secure (e.g., cold storage on mainnet). This address initiates proposals and signs registrations.
   • Submit: Used for sending FTSO commit/reveal transactions.
   • SubmitSignatures: Used for sending FTSO result signatures (often separate from Submit to manage transaction nonces).
   • SigningPolicy: Used for signing FTSO data during voting and for reward epoch configurations.
   • Delegation: Public address for receiving WNat delegations to increase vote power and collect rewards.

2. For each address role (Submit, SubmitSignatures, SigningPolicy, Delegation), perform the two-step propose-confirm process using the EntityManager contract (see FSP Solidity Reference):

   • Step A (Propose): Call the relevant propose<Role>Address method from your Identity address. Provide the address you want to register for that role as the argument.
   • Step B (Confirm): Call the corresponding confirm<Role>AddressRegistration method from the address you are actually registering (e.g., call confirmSubmitAddressRegistration using the Submit address's private key).

   Role to Register	Step A: Method Called by Identity Address	Step B: Method Called by Proposed Address
   Submit	proposeSubmitAddress	confirmSubmitAddressRegistration
   SubmitSignatures	proposeSubmitSignaturesAddress	confirmSubmitSignaturesAddressRegistration
   SigningPolicy	proposeSigningPolicyAddress	confirmSigningPolicyAddressRegistration
   Delegation	proposeDelegationAddress	confirmDelegationAddressRegistration

Fund FSP addresses

All registered FSP addresses (Identity, Submit, SubmitSignatures, SigningPolicy, Delegation) require funding with the network's native token (FLR, SGB, etc.) to cover transaction gas fees.

Additionally, the Delegation address needs sufficient Wrapped Native Token (WNat) balance to achieve voting power in the FTSO protocols. You can wrap native tokens directly to this address or receive delegations from the community.

• Wrapping Portals:
  • Development Portal (Flare Testnet Coston2, Songbird Testnet Coston)
  • Flare Portal (Flare Mainnet, Songbird Canary-Network)
• The Delegation address needs at least 150 WNat (e.g., WFLR, WC2FLR) for its vote weight to be recognized by the protocols (due to weight normalization).

Register sortition key

This key pair is used for the FTSOv2 Fast Updates protocol.

1. Generate a sortition key pair using the fast-updates/go-client image:

   docker run --rm ghcr.io/flare-foundation/fast-updates/go-client:latest keygen

   This will generate an output of the form:

   {
     "PublicKeyX": "0x14ce9f57394f6dcdba82816808deb5f9c0fd9e5621edeeef35ff1e55346c4ccf",
     "PublicKeyY": "0x131b26a181c5a1f1281f7bd8c745dabb44c5986bb408f88052b336390fcaec51",
     "PrivateKey": "0x0f795088442f405031f54fb6e2f19ea05dc7769755cc28a947df99f6c4b5af22"
   }

2. Register public key:

   • If you used the Automated Registration script on a testnet (Method 1 above), this step is already completed, skip to Register validator node.

   • If you used Manual Registration (Method 2) or need to register manually:

     1. Create a signature proving your Identity address owns the generated sortition private key. Use the keygen command again, providing the PrivateKey (from Step 1) and your Identity address.

        # Replace placeholders with your actual values
        docker run --rm ghcr.io/flare-foundation/fast-updates/go-client:latest keygen \
          --key <YOUR_GENERATED_SORTITION_PrivateKey> \
          --address <YOUR_IDENTITY_ADDRESS>

        This will generate a signature of the form:

        Signature generated: 0x10b0f6b68acf899944ce9406c807f38e904401dcf962d7fdd9943b0dee0222321f6863ed9f46d048695942793f1c16158b9a886b6ff2120390f5ddcbbdb0d3b02d8fff2c8f0583c8269650f97a169f5c5ea04ce3bdd91ca959188ac2cf2ff517

     2. Call the registerPublicKey method from your Identity address. Provide the PublicKeyX, PublicKeyY (from Step 1), and the Signature (from Step 2a) as arguments.

        registerPublicKey(
          bytes32 _part1, // <-- REPLACE WITH YOUR GENERATED PublicKeyX
          bytes32 _part2, // <-- REPLACE WITH YOUR GENERATED PublicKeyY
          bytes _verificationData  // <-- REPLACE WITH YOUR GENERATED Signature
        )

Register validator node

Link your registered validator node's ID to your Flare Entity Identity address via the EntityManager contract.

1. Find your active validator node's staker.key and staker.crt files (Default paths: ~/.avalanchego/staking/).

2. Prepare shell variables for the file paths and your Identity address (without the 0x prefix).

   PATH_TO_CRT=~/.avalanchego/staking/staker.crt
   ZERO_PREFIX=0000000000000000000000000000000000000000000000000000000000000000
   PATH_TO_KEY=~/.avalanchego/staking/staker.key
   IDENTITY_ADDRESS=ab...123 # <-- REPLACE WITH YOUR IDENTITY ADDRESS WITHOUT 0x prefix

3. Generate hex values, use the following commands to generate the required contract arguments from your validator files and identity address.

   _nodeId (NodeID derived from certificate):

   cat $PATH_TO_CRT | tail -n +2 | head -n -1 | base64 -d | openssl dgst -sha256 -binary | openssl rmd160 -provider legacy -binary | xxd -p | sed -e 's/^/0x/;'

   _certificateRaw (Raw certificate bytes):

   cat $PATH_TO_CRT | tail -n +2 | head -n -1 | base64 -d | xxd -p | tr -d '\n' | sed -e 's/^/0x/;' && echo

   _signature (Signature proving Identity owns the validator key):

   echo -n $ZERO_PREFIX$IDENTITY_ADDRESS | xxd -r -p | openssl dgst -sha256 -sign $PATH_TO_KEY | xxd -p | tr -d '\n' | sed -e 's/^/0x/;' && echo

4. Call the registerNodeId method on EntityManager using your Identity address. Provide the hex values generated in Step 3 as arguments.

   registerNodeId(
    bytes20 _nodeId, // <-- REPLACE WITH YOUR GENERATED _nodeId
    bytes _certificateRaw, // <-- REPLACE WITH YOUR GENERATED _certificateRaw
    bytes _signature  // <-- REPLACE WITH YOUR GENERATED _signature
   )

Setup FDC

With the necessary registrations complete, this section guides you through setting up the Flare Data Connector (FDC) components. The goal is to run the underlying blockchain nodes (or connect to existing ones) and the associated FDC indexers and verifiers. These components securely retrieve and verify data from various blockchains for the Flare network.

The FDC handles data differently depending on the source chain type:

• UTXO-Based Chains (e.g., Bitcoin, Dogecoin, Ripple): An indexer service syncs with the blockchain, storing relevant data locally. A Verifier API server then exposes this indexed data.
• EVM Chains (e.g., Ethereum, Flare, Songbird): The Verifier API server queries an RPC node directly for necessary data.

Resource Intensive

Deploying the full FDC suite, including multiple blockchain full nodes (BTC, DOGE, XRP, ETH, plus Flare/Songbird for EVM verification) and indexers, demands significant hardware resources. Ensure your system meets these combined requirements (see main System Requirements and factor in this additional load).

Required components

The fdc-suite-deployment repository provides configurations for deploying the following components:

Blockchain node images

Network	Blockchain node image
Bitcoin	flarefoundation/bitcoin
Dogecoin	flarefoundation/dogecoin
Ripple	flarefoundation/rippled
Ethereum	ethereum/client-go & prysm

Indexers and verifiers

Network	Indexer	Verifier
BTC	flare-foundation/verifier-utxo-indexer	flare-foundation/verifier-indexer-api
DOGE	flare-foundation/verifier-utxo-indexer	flare-foundation/verifier-indexer-api
XRP	flare-foundation/verifier-xrp-indexer	flare-foundation/verifier-indexer-api
EVM	-	flare-foundation/evm-verifier

Flexibility and Dependencies

• EVM Verification: Note that Flare Mainnet and Songbird Canary-Network nodes (see Run Node guides) are also implicitly required for EVM verification tasks run by the FDC Client later, but are typically run as part of your core Flare Entity / Validator setup, not within the fdc-suite-deployment.
• Using Existing Nodes: You are not required to deploy all listed blockchain node images using this repository. If you operate your own compatible RPC nodes (e.g., for Bitcoin), you can configure the corresponding Verifier/Indexer .env file (detailed below) with your node's RPC URL and credentials instead of starting the node image provided here.
• Splitting Deployment: While possible to run components across multiple servers, this guide focuses on the single-machine setup provided by the repository, which may be simpler to manage.
• Dependencies: Indexers and Verifiers require access to a synced and operational blockchain node for their respective chain. Ensure node availability before starting dependent services.

Configuring blockchain nodes

1. Start by cloning the flare-foundation/fdc-suite-deployment repo:

   git clone https://github.com/flare-foundation/fdc-suite-deployment.git
   cd fdc-suite-deployment

2. (optional) Build Docker images. Images are typically pulled automatically from GHCR. If manual building is needed:

   # Clone the specific component repo first, then build
   # docker build -t <image-tag> . # replace image tag with tag used in docker-compose.yaml

3. To configure node authentication, navigate into the specific node's directory (e.g., nodes-mainnet/btc) within the cloned repo and generate credentials where required. Keep generated credentials secure as they will be needed for the Verifier configuration.

   • Bitcoin (BTC) / Dogecoin (DOGE):

     # Example for BTC
     cd nodes-mainnet/btc
     ./generate-password.sh # Follow prompts or use ./rpcauth.py <USER> <PASS>
     # Note the generated username/password/rpcauth string for later use
     cd ../.. # Return to fdc-suite-deployment root

     (Repeat for nodes-mainnet/doge if needed)

   • Ripple (XRP): No specific authentication setup needed via this repo's config.

   • Ethereum (ETH): Generate JWT secret for communication between Execution (Geth) and Consensus (Prysm) clients:

     # Ensure you are in the fdc-suite-deployment root directory
     openssl rand -hex 32 > nodes-mainnet/eth/jwt.hex

Default Port Exposure

The default docker-compose.yaml files provided in fdc-suite-deployment for blockchain nodes might expose standard RPC ports. Review the ports section in the relevant docker-compose.yaml files and adjust firewall rules on your host machine accordingly to restrict access based on your security policy.

Configuring indexers and verifiers

Configuration for the indexer and verifier services is managed centrally via the .env file in the root of the fdc-suite-deployment repository.

1. Create and Edit .env:

   cp .env.example .env

   Now, carefully edit the .env file, providing correct values for all variables relevant to the FDC components you are deploying. Pay close attention to:

   • RPC Node Connection Details (*_URL, *_RPC_USERNAME, *_RPC_PASSWORD / *_RPC_AUTH): Provide the full URL and credentials for connecting to each required blockchain node.

     • If using nodes deployed via fdc-suite-deployment on the same host, you can often use 172.17.0.1 (Docker's default bridge IP) as the hostname in the URL (e.g., http://admin:<PASSWORD>@172.17.0.1:8332/ for BTC, using the password generated earlier).
     • If using external nodes (your own or third-party), use their publicly accessible RPC endpoint URL and associated credentials.

   • Start Block Number (*_START_BLOCK_NUMBER): Crucial for the first run only. Set this for each UTXO indexer (BTC, DOGE, XRP) to a block number finalized approximately 14 days prior to the current date. (Tip: Use a blockchain explorer for the respective chain to find a block number from around that time). This limits initial indexing duration. Do not change this value on subsequent restarts unless intentionally resetting the indexer database; the indexer will automatically resume.

   • Testnet Mode (TESTNET): Set to true if deploying for Coston/Coston2, otherwise false (or omit).

   • Verifier API Keys (VERIFIER_API_KEYS): Set one or more comma-separated secret keys. These keys grant access to your verifier API servers and will be needed by the FDC Client (in the main Flare Entity deployment). Generate strong, unique keys.

   • Database Passwords (*_DB_PASSWORD): Set secure, random passwords for the internal indexer databases.

2. After saving your .env file, run the provided script. This injects your .env values into the configuration templates used by the individual services.

   ./generate-config.sh

   (This populates files in verifiers/, evm-verifier/, etc.)

Start FDC Services

Important Order: Start the required blockchain nodes before starting their corresponding indexers and verifiers. Ensure nodes are running and ideally synced (or making good progress) first.

Start blockchain nodes

1. Go to the directory for the specific blockchain node, e.g., nodes-mainnet/btc.

2. Start the node:

   docker compose up -d

Repeat for each blockchain node image you are deploying.

Start indexers and verifiers

1. Go to the appropriate verifier directory, e.g., verifiers/btc.

2. Start the verifier:

   docker compose up -d

Repeat for all verifiers corresponding to the chains you need.

Verify FDC Services & Initial Indexing

After starting the FDC nodes, indexers, and verifiers, check their status using docker ps.

Review initial logs via docker compose logs <service_name> (e.g., docker compose logs btc-indexer in the verifiers/btc directory) to confirm startup without immediate errors.

Setup FTSO

To participate in the Flare Time Series Oracle (FTSO), your Flare Entity needs access to real-time price data for various assets. This is provided by a Feed Value Provider service that you must run. It fetches price data from your chosen external sources (e.g., multiple exchanges) and serves it via a specific API endpoint to your Flare Entity's FTSO clients (Fast Updates Client and FTSO Client).

Implement Your Own Production Provider

The example implementation referenced below (flare-foundation/ftso-v2-example-value-provider) retrieves data from public sources but is intended ONLY for testing, demonstration, or initial integration purposes.

For reliable mainnet operation and reward eligibility, you MUST implement, deploy, and maintain your own robust Feed Value Provider. This involves:

• Sourcing data from diverse, reliable, low-latency upstream providers (exchanges, APIs).
• Implementing logic for data cleaning, validation, and aggregation.
• Ensuring high availability and performance of your service. Failure to provide accurate, timely, and robust data through your provider will negatively impact your FTSO performance and rewards.

Running a custom provider

• Develop your service adhering strictly to the Required Endpoints Specification below.
• Deploy your custom provider service using production-grade practices (e.g., as a container with restart policies, behind a load balancer if needed, with monitoring).
• The provider's API endpoint must be network-accessible from the environment where your main Flare Entity services run (i.e., where the flare-systems-deployment Docker containers will run). It typically does not need public internet exposure. Note down its internal network URL (e.g., http://<provider-internal-ip>:<port>) for the VALUE_PROVIDER_URL variable in the final deployment configuration.

Required endpoints specification

Your custom Feed Value Provider must implement the following HTTP POST endpoints. Both endpoints expect and return JSON payloads (Content-Type: application/json).

• POST /feed-values

  • Description: Returns the feed values without specifying the voting round, used by FTSOv2 Fast Updates client.
  • Example request:

    curl -X 'POST' 'http://localhost:3101/feed-values/' \
      -H 'accept: application/json' \
      -H 'Content-Type: application/json' \
      -d '{"feeds": [{ "category": 1, "name" : "BTC/USD" }]}'
  • Example response:

    {
      "data": [
        {
          "feed": { "category": 1, "name": "BTC/USD" },
          "value": 71285.74004472858
        }
      ]
    }

• POST /feed-values/:votingRoundId

  • Description: Returns the feed values for the specified voting round, used by FTSOv2 Scaling client.
  • Example request:

    curl -X 'POST' 'http://localhost:3101/feed-values/0' \
      -H 'accept: application/json' \
      -H 'Content-Type: application/json' \
      -d '{"feeds": [{ "category": 1, "name" : "BTC/USD" }]}'
  • Example response:

    {
      "votingRoundId": 0,
      "data": [
        {
          "feed": { "category": 1, "name": "BTC/USD" },
          "value": 71287.34508311428
        }
      ]
    }

Using the example provider

For testing and development, you can run the flare-foundation/ftso-v2-example-value-provider:

# Exposes the example provider API on port 3101 of the host machine
docker run --rm -it --publish "0.0.0.0:3101:3101" ghcr.io/flare-foundation/ftso-v2-example-value-provider

If running Docker locally, the API documentation is typically available at http://localhost:3101/api-doc.

Fixed Value Troubleshooting

To test integration without live data, run the example provider in fixed mode:

docker run --rm -it --env VALUE_PROVIDER_IMPL=fixed --publish "0.0.0.0:3101:3101" ghcr.io/flare-foundation/ftso-v2-example-value-provider

Check container logs for WARN [FixedFeed] Initializing FixedFeed....

Remove specific exchanges from the example value provider.

If you want to remove specific exchanges from the example value provider, you can do so by modifying src/config/feeds.json:

Example removing Binance and Bybit exchanges with jq:

curl -fs -o feeds.json https://raw.githubusercontent.com/flare-foundation/ftso-v2-example-value-provider/refs/heads/main/src/config/feeds.json && \
  cp feeds.json feeds.json.bak && \
  jq 'map(.sources |= map(select(.exchange | ascii_downcase != "binance" and ascii_downcase != "bybit")))' feeds.json > feeds.clean && \
  mv feeds.clean feeds.json

Create Fast Updates accounts

The FTSOv2 Fast Updates protocol uses dedicated accounts for submitting frequent price updates, separate from the main FSP addresses to manage transaction nonces effectively.

• Generate at least three (3) new, unique blockchain accounts. These accounts must not be any of the five main FSP addresses (Identity, Submit, etc.).
• Securely store the private keys for these newly created accounts. You will need them later for the FAST_UPDATES_ACCOUNTS variable in the final deployment .env file.
• Ensure each of these new Fast Updates accounts is funded with a sufficient amount of the network's native token (e.g., FLR, SGB) to cover the gas costs of frequent transaction submissions. Monitor balances periodically.

Run Flare Entity

With prerequisites met, registrations complete, and FDC/FTSO components configured, you can now deploy and run the main Flare Entity system using the flare-systems-deployment Docker Compose setup.

1. Clone flare-systems-deployment repository:

   git clone https://github.com/flare-foundation/flare-systems-deployment.git
   cd flare-systems-deployment

2. Copy the example environment file:

   cp .env.example .env

3. Carefully edit the .env file, providing the correct values gathered during the previous setup stages. While reviewing env.example for all possible settings is recommended (defaults may not suit all environments), ensure these key variables are correctly set based on your Registration, FDC, and FTSO setup:

   • NODE_RPC_URL, NODE_API_KEY (optional): Your RPC Node or a private RPC provider.
   • IDENTITY: Public Identity address from FSP addresses.
   • SUBMIT_PK, SIGNATURES_PK, SIGNING_PK: Private keys from FSP addresses.
   • VALUE_PROVIDER_URL: URL of the feed value provider in Setup FTSO.
   • FAST_UPDATES_ACCOUNTS: Private keys of the Fast Updates accounts.
   • FAST_UPDATES_SORTITION_PRIVATE_KEY: Private key of the sortition key.
   • FDC Verifier URLs (<NETWORK>_<ATTESTATION_TYPE>_URL): URLs for each FDC verifier services you deployed (e.g., BTC_PAYMENT_URL=http://<verifier-ip>:port).
   • FDC Verifier API Keys (<NETWORK>_<ATTESTATION_TYPE>_API_KEY, Optional): API keys configured for your FDC verifiers, if any.
   
   
   Secure Your .env File

   This .env file contains highly sensitive private keys and API keys. Protect this file rigorously:

   • Set strict file permissions (e.g., chmod 600 .env) so only the owner can read/write.
   • Ensure it's never committed to Git or any version control system.
   • Limit access to the server and user account running the deployment. Compromise of these keys can lead to loss of funds, unauthorized actions, and compromised entity.

4. Run the provided script. This uses your .env file to populate the specific configuration files used internally by each Docker service.

   ./populate_config.sh

   Remember to re-run this script every time you make changes to your .env file.

5. Use Docker Compose to start all Flare Entity services defined in docker-compose.yaml in detached mode (-d).

   docker compose up -d

   Note: The first run will download all necessary Docker images, which may take several minutes depending on image sizes and network speed.

If your Flare Entity is working correctly, congratulations!

Verify deployment success

After starting, confirm the containers are running (docker ps). Crucially, monitor the initial logs of key components to ensure they start correctly, connect to necessary services (RPC node, database, verifiers, Feed Value Provider), and enter their operational loops. Use docker compose logs -f <service_name> to tail logs in real-time.

Key services to check include: system-client, c-chain-indexer, fast-updates-client, ftso-client, fdc-client.

Look for successful connections, registration messages (if applicable for the current reward epoch timing), and absence of repeating critical errors.

Refer to the Troubleshooting and FAQs sections for common issues and ongoing checks.

Update Flare Entity

Keep your Flare Entity software up-to-date with the latest official releases provided through the Docker images.

1. (Optional) For a potentially cleaner update, especially if major changes occurred, you can stop the running containers:

   docker compose down

2. Fetch the newest images specified in the project's docker-compose.yaml file:

   docker compose pull

3. (If Required) If the new software version requires changes to configuration, carefully modify your .env file according to the release notes, and then re-run the configuration generation script:

   # Modify .env if necessary
   ./populate_config.sh

4. Start the services using the updated images (and configuration, if changed). docker compose up -d will typically recreate containers whose images have changed.

   docker compose up -d

5. After restarting, re-check container status (docker ps) and monitor logs as described in the Verify deployment success above to ensure all services start correctly with the new versions.

Troubleshooting

Get listed on explorers

To get your validator logo and name listed on the explorers, open a PR on TowoLabs/ftso-signal-providers.

system-client is not doing anything

Likely, your entity is not registered as a voter for the current reward epoch. There is a time window for voter registration on every reward epoch, and if you leave things running you should eventually see RegisterVoter success in the logs. It should then start submitting data successfully in the following reward epoch.

system-client fails to fetch sub-protocol data

The c-chain-indexer may still be indexing data, once it's finished you should see Indexer at block x in the logs. If it's still processing blocks you will see various errors across all services.

fast-updates client is not doing anything

If you have low weight it may take some time until you are selected to submit an update.

Icon and logo don't show up on Flare explorers

To get your validator logo and name listed on the explorers, open a PR on TowoLabs/ftso-signal-providers.

FAQs

How do I check if my Flare Entity meets Minimal Conditions?

Meeting minimal conditions for availability and performance in each reward epoch is necessary for FSP reward eligibility. You can check your entity's status using two primary methods:

Method 1: Flare Systems Explorer (Web Interface)

This is the easiest and most reliable way to check your status.

1. Navigate to the Minimal Conditions tab on the Flare Systems Explorer.
2. Find your entity by searching for your Identity address.
3. Review the status column for the relevant reward epoch(s). A YES indicates conditions were met for that epoch.

Method 2: Explorer Backend API (Command Line)

You can query the API that powers the explorer for programmatic access.

1. You'll need your entity's registered Identity address, without the 0x prefix.

   IDENTITY_ADDRESS="563...1a8" # <-- REPLACE WITH YOUR Identity ADDRESS WITHOUT 0x

2. Query the API and extract the minimal conditions status:

   curl "https://flare-systems-explorer-backend.flare.network/api/v0/entity?query=${IDENTITY_ADDRESS}" \
     -H "Accept: application/json" | jq -r '.results[0].entityminimalconditions'

3. An example output might look like:

   {
     "id": 184955,
     "reward_epoch": 289, // Epoch the status applies to
     "ftso_scaling": true,
     "ftso_fast_updates": true,
     "staking": true,
     "fdc": true,
     "passes_held": 3,
     "strikes": 0,
     "new_number_of_passes": 3,
     "eligible_for_reward": true, // Indicates minimal conditions met
     "entity": 42
   }

Where can I find calculated rewards data and my specific rewards?

Reward amounts for both staking and FSP participation are calculated and published periodically. Always refer to official Flare sources for the latest data locations.

Validator Staking Rewards:

Calculated per reward epoch (every 3.5 days, starting Mon/Thu) and claimable every 4 reward epochs (approx. every 14 days). Check the validator-rewards directory within the flare-foundation/reward-scripts repository on GitHub. To inspect your entity's validator rewards for a specific epoch via CLI:

1. Get your NODE_ID and the EPOCH_ID from the Flare Systems Explorer.

   NODE_ID="NodeID-CoN...RS" # <-- REPLACE WITH YOUR Node ID
   EPOCH_ID="288" # <-- REPLACE WITH THE REWARD EPOCH YOU WANT TO CHECK

2. Use the following command to fetch and display your validator rewards:

   curl -s "https://raw.githubusercontent.com/flare-foundation/reward-scripts/refs/heads/main/generated-files/reward-epoch-${EPOCH_ID}/nodes-data.json" | \
     jq --arg node_id "${NODE_ID}" \
     '.[] |
     select(.nodeId == $node_id) |
     (.validatorRewardAmount | tonumber / 1000000000000000000) |
     "Validator Rewards: \((. * 100 | floor) / 100) FLR"'

FSP (FTSO & FDC) Rewards:

Calculated per reward epoch (every 3.5 days, starting Mon/Thu). Requires meeting minimal conditions requirements. Published data is usually available shortly after epoch finalization at:

• GitHub: flare-foundation/fsp-rewards repository (look for files named by epoch).
• Forum: The FSP Rewards Data thread on the Flare Discourse Forum often has summary files (like XLSX) and related discussions.

To inspect your entity's FSP rewards for a specific epoch via CLI:

1. Get your IDENTITY_ADDRESS and the EPOCH_ID from the Flare Systems Explorer.

   IDENTITY_ADDRESS="0x5...1A8" # <-- REPLACE WITH YOUR Identity ADDRESS
   EPOCH_ID="288" # <-- REPLACE WITH THE REWARD EPOCH YOU WANT TO CHECK

2. Use the following command to fetch and display your FSP rewards:

   curl -s "https://raw.githubusercontent.com/flare-foundation/fsp-rewards/refs/heads/main/flare/${EPOCH_ID}/reward-distribution-data.json" | \
     jq --arg identity_address "${IDENTITY_ADDRESS}" \
     '.rewardClaims[] |
     select(.body.beneficiary == ($identity_address | ascii_downcase)) |
     (.body.amount | tonumber / 1000000000000000000) |
     "FSP Rewards: \((. * 100 | floor) / 100) FLR"'

How does the pass system work with minimal conditions?

Successfully meeting minimal conditions in an epoch typically earns your entity a "pass" (you can hold up to 3 passes). These act as a buffer - if your entity occasionally fails to meet conditions (e.g., due to minor submission issues or downtime), a pass is automatically consumed to maintain reward eligibility for that epoch. If conditions are not met and you have zero passes remaining, FSP rewards for that epoch are forfeited. Learn more.

How can I monitor the health of my Flare Entity?

Consistent monitoring is key to maintaining performance and reward eligibility. Here are primary areas and methods:

1. Validator node health:

• Monitor the /ext/health endpoint for validator status
• Check validator connectivity using this API endpoint to verify uptime/connected values
• For advanced monitoring, use Avalanche's Grafana dashboards which are compatible with Flare

2. FDC health monitoring:

• Query the health endpoint exposed by each FDC verifier service you run: GET http://{verifier-host}:{verifier-port}/verifier/{chain}/health (Replace placeholders with your verifier's host, port, and the relevant chain like btc, doge, xrp, eth). Look for a success status/response.

3. FTSO health monitoring:

• Check minimal conditions status via the Flare Systems Explorer or the backend API detailed previously in the FAQ.

• Monitor the logs of your running Docker containers (docker compose logs <service_name>) for errors and key operational messages:

  • Registration: Look for RegisterVoter success messages in the system-client logs around the start of reward epochs.

    # Example Registration Log Entry (Timestamp/Address vary)
    INFO epoch/registry_utils.go:187 Voter 0x... registered for epoch ...

  • Submissions: Look for Submitter ... successfully sent tx messages in system-client logs during voting periods. Absence for >10 mins may indicate issues.

    # Example Submission Log Entries (Timestamp/Type vary)
    INFO protocol/submitter.go:76 Submitter submitSignatures successfully sent tx
    INFO protocol/submitter.go:76 Submitter submit1 successfully sent tx

    Alerting Tip: Set alerts if no successful submission messages appear for 5-10 minutes during active voting periods.

  • Finalization: Look for Relaying finished for protocol ... with success messages in system-client logs after voting periods. Non-fatal errors may occur but should be investigated if persistent. (Protocol 100 = FTSOv2, Protocol 200 = FDC).

    # Example Finalization Log Entries (Timestamp/Status vary)
    INFO finalizer/relay_client.go:168 Relaying finished for protocol 100 with success
    INFO finalizer/relay_client.go:168 Relaying finished for protocol 200 with success

    Alerting Tip: Set alerts if no successful finalization messages appear for protocols 100/200 within 5-10 minutes after a voting round should have completed.