# Set Up Flare Entity

> Provide data for Flare's enshrined FTSO and FDC protocols.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

Source: https://dev.flare.network/run-node/flare-entity

This guide will walk you through setting up a Flare Entity, consisting of a validator node and a data provider system (FSP) for the Flare network. The [FSP](/network/fsp) consists of [Flare Time Series Oracle (FTSO)](https://dev.flare.network/ftso/overview) and [Flare Data Connector (FDC)](https://dev.flare.network/fdc/overview) sub-protocols.

![Data Provider System for FSP](/img/docs/run-node/fsp-node.light.svg)![Data Provider System for FSP](/img/docs/run-node/fsp-node.dark.svg)

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.

Rewards and Minimal conditions

After the introduction of [minimal conditions](/network/fsp/rewarding#minimal-conditions) in [FIP.10](https://proposals.flare.network/FIP/FIP_10.html), a Flare Entity needs to be both **available** and **performant** across all Flare protocols in order to be eligible for rewards. Learn how to check if your Flare Entity meets minimal conditions and the rewards it accrued in the [FAQs](#faqs) section (see **FAQ F1** and **FAQ F2**).

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

-   A machine meeting the [minimum hardware requirements](/run-node/system-requirements).
-   A registered [validator node](/run-node/register-validator).
-   [Docker Engine](https://docs.docker.com/engine/install/), 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](https://docs.docker.com/engine/storage/)).
-   [jq](https://jqlang.org)
-   [envsubst](https://www.gnu.org/software/gettext/manual/html_node/envsubst-Invocation.html)
-   [yarn](https://yarnpkg.com) (optional, for performing [automated registration](#register-and-fund-fsp-addresses) 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.

## Registration[​](#registration "Direct link to Registration")

Before deploying the Flare Entity components, several one-time registration steps must be completed onchain. This involves registering FSP operational addresses, 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[​](#register-and-fund-fsp-addresses "Direct link to 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).

<details>
<summary>Method 1: Automated Registration (Testnets only).</summary>

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](https://github.com/flare-foundation/flare-smart-contracts-v2/):
    
    ```
    git clone https://github.com/flare-foundation/flare-smart-contracts-v2/cd flare-smart-contracts-v2yarnyarn 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](#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`](https://github.com/flare-foundation/flare-smart-contracts-v2/blob/main/deployment/tasks/register-entities.ts) and [`register-public-keys.ts`](https://github.com/flare-foundation/flare-smart-contracts-v2/blob/main/deployment/tasks/register-public-keys.ts)):
    
    ```
    yarn run register_entities_network_coston2yarn run register_public_keys_network_coston2
    ```
    
    ```
    yarn run register_entities_network_costonyarn 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](#fund-fsp-addresses).

</details>

#### Method 2: Manual registration[​](#method-2-manual-registration "Direct link to 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`](/network/fsp/solidity-reference/IEntityManager) 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 (e.g., WFLR, WC2FLR) 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 Reference](/network/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`](/network/fsp/solidity-reference/IEntityManager#proposesubmitaddress)
    
    [`confirmSubmitAddressRegistration`](/network/fsp/solidity-reference/IEntityManager#confirmsubmitaddressregistration)
    
    `SubmitSignatures`
    
    [`proposeSubmitSignaturesAddress`](/network/fsp/solidity-reference/IEntityManager#proposesubmitsignaturesaddress)
    
    [`confirmSubmitSignaturesAddressRegistration`](/network/fsp/solidity-reference/IEntityManager#confirmsubmitsignaturesaddressregistration)
    
    `SigningPolicy`
    
    [`proposeSigningPolicyAddress`](/network/fsp/solidity-reference/IEntityManager#proposesigningpolicyaddress)
    
    [`confirmSigningPolicyAddressRegistration`](/network/fsp/solidity-reference/IEntityManager#confirmsigningpolicyaddressregistration)
    
    `Delegation`
    
    [`proposeDelegationAddress`](/network/fsp/solidity-reference/IEntityManager#proposedelegationaddress)
    
    [`confirmDelegationAddressRegistration`](/network/fsp/solidity-reference/IEntityManager#confirmdelegationaddressregistration)
    

#### Fund FSP addresses[​](#fund-fsp-addresses "Direct link to 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 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](https://portal.flare.rocks) (Flare Testnet Coston2, Songbird Testnet Coston)
    -   [Flare Portal](https://portal.flare.network) (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[​](#register-sortition-key "Direct link to 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](https://github.com/flare-foundation/fast-updates/pkgs/container/fast-updates%2Fgo-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](#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 valuesdocker run --rm ghcr.io/flare-foundation/fast-updates/go-client:latest keygen \  --key PrivateKey \ # <-- REPLACE WITH YOUR GENERATED PrivateKey  --address Identity  # <-- REPLACE WITH YOUR Identity ADDRESS
            ```
            
            This will generate a signature of the form:
            
            ```
            Signature generated: 0x10b0f6b68acf899944ce9406c807f38e904401dcf962d7fdd9943b0dee0222321f6863ed9f46d048695942793f1c16158b9a886b6ff2120390f5ddcbbdb0d3b02d8fff2c8f0583c8269650f97a169f5c5ea04ce3bdd91ca959188ac2cf2ff517
            ```
            
            2.  Call the [`registerPublicKey`](/network/fsp/solidity-reference/IEntityManager#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[​](#register-validator-node "Direct link to Register validator node")

Link your registered validator node's ID to your Flare Entity `Identity` address via the [`EntityManager`](/network/fsp/solidity-reference/IEntityManager) 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.crtZERO_PREFIX=0000000000000000000000000000000000000000000000000000000000000000PATH_TO_KEY=~/.avalanchego/staking/staker.keyIDENTITY_ADDRESS=ab...123 # <-- REPLACE WITH YOUR Identity ADDRESS WITHOUT 0x prefix
    ```
    
3.  Use the following commands to generate the required contract arguments:
    
    `_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`](/network/fsp/solidity-reference/IEntityManager#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[​](#setup-fdc "Direct link to 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): 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](/run-node/system-requirements) and factor in this additional load).

### Required components[​](#required-components "Direct link to Required components")

The [fdc-suite-deployment](https://github.com/flare-foundation/fdc-suite-deployment) repository provides configurations for deploying the following components:

#### Blockchain node images[​](#blockchain-node-images "Direct link to Blockchain node images")

Network

Blockchain node image

Bitcoin

[flarefoundation/bitcoin](https://hub.docker.com/r/flarefoundation/bitcoin)

Dogecoin

[flarefoundation/dogecoin](https://hub.docker.com/r/flarefoundation/dogecoin)

Ripple

[flarefoundation/rippled](https://hub.docker.com/r/flarefoundation/rippled)

Ethereum

[ethereum/client-go](https://hub.docker.com/r/ethereum/client-go) & [prysm](https://prysm.offchainlabs.com/docs/install-prysm/install-with-docker/)

#### Indexers and verifiers[​](#indexers-and-verifiers "Direct link to Indexers and verifiers")

Network

Indexer

Verifier

BTC

[flare-foundation/verifier-utxo-indexer](https://github.com/flare-foundation/verifier-utxo-indexer)

[flare-foundation/verifier-indexer-api](https://github.com/flare-foundation/verifier-indexer-api)

DOGE

[flare-foundation/verifier-utxo-indexer](https://github.com/flare-foundation/verifier-utxo-indexer)

[flare-foundation/verifier-indexer-api](https://github.com/flare-foundation/verifier-indexer-api)

XRP

[flare-foundation/verifier-xrp-indexer](https://github.com/flare-foundation/verifier-xrp-indexer)

[flare-foundation/verifier-indexer-api](https://github.com/flare-foundation/verifier-indexer-api)

EVM

\-

[flare-foundation/evm-verifier](https://github.com/flare-foundation/evm-verifier)

<details>
<summary>EVM verification, using existing nodes and dependencies.</summary>

EVM verification, using existing nodes and dependencies.

-   **EVM Verification:** Note that Flare Mainnet and Songbird Canary-Network nodes (see [Run Node guides](/run-node)) 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.

</details>

### Configure blockchain nodes[​](#configure-blockchain-nodes "Direct link to Configure blockchain nodes")

1.  Start by cloning the [flare-foundation/fdc-suite-deployment](https://github.com/flare-foundation/fdc-suite-deployment) repo:
    
    ```
    git clone https://github.com/flare-foundation/fdc-suite-deployment.gitcd fdc-suite-deployment
    ```
    
2.  (optional) Images are typically pulled automatically from the GitHub Container Registry. 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 BTCcd nodes-mainnet/btc./generate-password.sh # Follow prompts or use ./rpcauth.py <USER> <PASS># Note down the generated username/password/rpcauth string for later usecd ../.. # 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 directoryopenssl rand -hex 32 > nodes-mainnet/eth/jwt.hex
        ```
        

Exposing ports

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.

### Configure indexers and verifiers[​](#configure-indexers-and-verifiers "Direct link to Configure 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` repo.

1.  Create and Edit `.env`:
    
    ```
    cp .env.example .env
    ```
    
    Now, carefully edit the `.env` file, providing 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.
    -   **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. Remember to **re-run this script** every time you make changes to your `.env` file.*
    

### Start FDC Services[​](#start-fdc-services "Direct link to Start FDC Services")

Order of starting services

The order of starting the services is crucial. Ensure that the blockchain nodes are fully operational and ideally synced before starting their corresponding indexers and verifiers.

#### Start blockchain nodes[​](#start-blockchain-nodes "Direct link to 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[​](#start-indexers-and-verifiers "Direct link to 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[​](#setup-ftso "Direct link to 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`](https://github.com/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[​](#running-a-custom-provider "Direct link to Running a custom provider")

-   Develop your service adhering strictly to the [Required Endpoints Specification](#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](#run-flare-entity) (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[​](#required-endpoints-specification "Direct link to Required endpoints specification")

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

<details>
<summary>POST /feed-values</summary>

**`POST /feed-values`**

-   **Description**: Returns the feed values without specifying the voting round, used by FTSOv2 Fast Updates client. For category and name values, refer to [FTSOv2 block-latency feeds](/ftso/feeds).
-   **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    }  ]}
    ```

</details>
<details>
<summary>POST /feed-values/:votingRoundId</summary>

**`POST /feed-values/:votingRoundId`**

-   **Description**: Returns the feed values for the specified voting round, used by FTSOv2 Scaling client. For category and name values, refer to [FTSOv2 anchor feeds](/ftso/scaling/anchor-feeds).
-   **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    }  ]}
    ```

</details>

### Using the example provider[​](#using-the-example-provider "Direct link to Using the example provider")

For testing and development, you can run the [flare-foundation/ftso-v2-example-value-provider](https://github.com/flare-foundation/ftso-v2-example-value-provider):

```
# Exposes the example provider API on port 3101 of the host machinedocker 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`](http://localhost:3101/api-doc).

<details>
<summary>Troubleshooting without live data.</summary>

Troubleshooting without live data.

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

</details>
<details>
<summary>Remove specific exchanges from the example value provider.</summary>

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
```

</details>

### Create Fast Updates accounts[​](#create-fast-updates-accounts "Direct link to 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](#register-and-fund-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[​](#run-flare-entity "Direct link to Run Flare Entity")

With prerequisites met, registrations complete, and FDC/FTSO components configured, you can now deploy and run the main Flare Entity system:

1.  Clone [flare-systems-deployment](https://github.com/flare-foundation/flare-systems-deployment) repository:
    
    ```
    git clone https://github.com/flare-foundation/flare-systems-deployment.gitcd 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:
    
    -   **RPC**
        -   `NODE_RPC_URL`: Your RPC Node or a [private RPC provider](/network/developer-tools#rpcs).
        -   `NODE_API_KEY` (optional): If your RPC provider requires it.
    -   **Identity & Keys:**
        -   `IDENTITY`: Public `Identity` address from [FSP addresses](#register-and-fund-fsp-addresses).
        -   `SUBMIT_PK`, `SIGNATURES_PK`, `SIGNING_PK`: Private keys from [FSP addresses](#register-and-fund-fsp-addresses).
    -   **FTSO:**
        -   `VALUE_PROVIDER_URL`: URL of the feed value provider in [Setup FTSO](#setup-ftso).
        -   `FAST_UPDATES_ACCOUNTS`: Private keys of the [Fast Updates accounts](#create-fast-updates-accounts).
        -   `FAST_UPDATES_SORTITION_PRIVATE_KEY`: Private key of the [sortition key](#register-sortition-key).
    -   **FDC:**
        -   `<NETWORK>_<ATTESTATION_TYPE>_URL`: URLs for each FDC [verifier services](#start-indexers-and-verifiers) you deployed, e.g. `BTC_PAYMENT_URL=http://<verifier-ip>:port`
        -   `<NETWORK>_<ATTESTATION_TYPE>_API_KEY` (optional): API keys configured for your FDC verifiers, if any.
    
      
    
    Secure Your `.env` File
    
    This file contains **highly sensitive** private keys and API keys. Compromise of these keys can lead to loss of funds, unauthorized actions, and a compromised entity.
    
    -   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.
    
4.  Update your `.env` to include all services:
    
    ```
    COMPOSE_PROFILES=fsp,fast-updates
    ```
    
5.  (Optional) By default, the `c-chain-indexer` requires 10 million blocks (≈20 days) of node history.
    
    -   To shorten this window, edit [`template-configs/c-chain-indexer.template.toml`](https://github.com/flare-foundation/flare-systems-deployment/blob/main/template-configs/c-chain-indexer.template.toml) to a value closer to the head of your node.
    -   **Do not** go below 350,000 blocks (≈7 days / 2 reward epochs), or the FTSO client may fail.
6.  Run the helper script to apply your `.env` settings to each Docker service:
    
    ```
    ./populate_config.sh
    ```
    
    *Remember to **re-run this script** every time you make changes to your `.env` file.*
    
7.  Launch the Flare Entity stack in detached mode:
    
    ```
    docker compose up -d
    ```
    
    *Note: The first startup will pull all required images. This may take several minutes depending on your network speed.*
    

### Verify deployment success[​](#verify-deployment-success "Direct link to Verify deployment success")

Once your services are up, follow these steps to confirm everything is running smoothly:

1.  Check running containers:
    
    ```
    docker ps
    ```
    
    Ensure these key containers appear in the list and have `Up` status:
    
    -   `system-client`
    -   `c-chain-indexer`
    -   `fast-updates-client` (if enabled)
    -   `ftso-client`
    -   `fdc-client`
2.  For each critical service, open a live log stream in a separate terminal:
    
    ```
    docker compose logs -f <service_name>
    ```
    
    Replace `<service_name>` with the actual service name (e.g., `system-client`, `c-chain-indexer`, etc.).
    

If your Flare Entity is working correctly, congratulations! Refer to the [Troubleshooting](#troubleshooting) and [FAQs](#faqs) sections for common issues and ongoing checks.

## Update Flare Entity[​](#update-flare-entity "Direct link to 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](#verify-deployment-success) above to ensure all services start correctly with the new versions.
    

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

Get listed on explorers

Submit a PR to [TowoLabs/ftso-signal-providers](https://github.com/TowoLabs/ftso-signal-providers) adding your validator name, description, delegation address, and logo (per repo guidelines). Once merged, explorers should update on their next sync.

<details>
<summary>Details</summary>

Details

T1. `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.

</details>
<details>
<summary>Details</summary>

Details

T2. `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.

</details>
<details>
<summary>Details</summary>

Details

T3. `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.

</details>
<details>
<summary>Details</summary>

Details

T4. Insufficient funds errors on `fast-updates` client

If your Fast Updates client is showing the following error, it means that the account you are using to submit transactions does not have enough funds to cover the gas fees.

```
[04-28|09:49:30.890]  ERROR  client/transaction_queue.go:139  Error executing transaction: insufficient funds for gas * price + value: address 0x57...7B6d have (0) want (187500000000000000)
```

You need to fund [all Fast Updates accounts](#create-fast-updates-accounts) account with enough native tokens to cover the gas fees.

</details>
<details>
<summary>Details</summary>

Details

T5. Icon and logo don't show up on Flare explorers

Submit a PR to [TowoLabs/ftso-signal-providers](https://github.com/TowoLabs/ftso-signal-providers) adding your validator name, description, delegation address, and logo (per repo guidelines). Once merged, explorers should update on their next sync.

</details>

## FAQs[​](#faqs "Direct link to FAQs")

<details>
<summary>Details</summary>

Details

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

Meeting [minimal conditions](/network/fsp/rewarding#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](https://flare-systems-explorer.flare.network/providers?tab=minimalConditions).
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 (CLI)**

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, // Meets minimal condition for FTSO Scaling  "ftso_fast_updates": true, // Meets minimal condition for FTSO Fast Updates  "staking": true, // Meets minimal condition for staking  "fdc": true, // Meets minimal condition for FDC  "passes_held": 3,  "strikes": 0,  "new_number_of_passes": 3,  "eligible_for_reward": true, // All minimal conditions met => eligible for rewards  "entity": 42}
    ```

</details>
<details>
<summary>Details</summary>

Details

F2. 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 every 4 reward epochs (every 14 days, starting Mon/Thu). Check the `validator-rewards` directory within the **[flare-foundation/reward-scripts](https://github.com/flare-foundation/reward-scripts/tree/main/generated-files/validator-rewards)** 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](https://flare-systems-explorer.flare.network/providers).
    
    ```
    NODE_ID="NodeID-CoN...RS" # <-- REPLACE WITH YOUR Node IDEPOCH_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](https://github.com/flare-foundation/fsp-rewards/tree/main/flare)** repository (look for files named by epoch).
-   **Forum:** The **[FSP Rewards Data thread](https://forum.flare.network/t/fsp-rewards-data)** 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](https://flare-systems-explorer.flare.network/providers).
    
    ```
    IDENTITY_ADDRESS="0x5...1A8" # <-- REPLACE WITH YOUR Identity ADDRESSEPOCH_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"'
    ```

</details>
<details>
<summary>Details</summary>

Details

F3. How does the pass system work with minimal conditions?

The pass system is an incentive mechanism for Flare Entities. Each entity has a number of passes, which can be gained or lost based on their performance in meeting the minimum participation requirements for each protocol within a reward epoch.

Here's how it works:

-   **Starting Passes:** Newly registered entities begin with zero passes.
-   **Gaining Passes:** When an entity successfully meets all the [minimum conditions](/network/fsp/rewarding#minimal-conditions) in a reward epoch, they gain one pass.
-   **Maximum Passes:** An entity can hold a maximum of three passes.
-   **Losing Passes:** If an entity fails to meet the minimum condition for a protocol in a reward epoch, they will lose one pass. It's important to note that entities can lose multiple passes for failing across multiple protocols within that reward epoch.
-   **Consequences of Losing Passes:**
    -   If an entity has one pass and fails to meet one minimal condition, they will be reduced to zero passes but will still receive FSP rewards for that epoch.
    -   However, if an entity has zero passes and fails to meet a minimal condition, they will forfeit all FSP rewards for that epoch. For information on where to find reward data, see **FAQ F2**.

Refer to **FAQ F1** to check how many passes your Flare Entity has.

Missing registration

If you are fail to register for a reward epoch your Flare Entity will lose all passes, as well as all FSP rewards for that reward epoch.

</details>
<details>
<summary>Details</summary>

Details

F4. 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](https://build.avax.network/docs/rpcs/p-chain#platformgetcurrentvalidators) to verify uptime/connected values
-   For advanced monitoring, use Avalanche's [Grafana dashboards](https://support.avax.network/en/articles/6159074-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](https://flare-systems-explorer.flare.network/providers?tab=minimalConditions) 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 txINFO 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 successINFO 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.

</details>
<details>
<summary>Details</summary>

Details

F5. How can I opt-out of receiving FlareDrops?

FlareDrops have ended

FlareDrops concluded on January 30, 2026, completing the 36-month distribution schedule defined under [FIP.01](https://proposals.flare.network/FIP/FIP_1.html).

WFLR, rFLR, and staked FLR no longer accrue the FlareDrop reward component. However, **protocol-level rewards remain unchanged**: you continue to earn rewards for FTSO delegation, FLR staking, and FAssets agent participation.

Learn more about [FLR's operational utility era](https://flare.network/news/beyond-flaredrops-flr-enters-operational-utility-era).

To opt-out of receiving all future FlareDrops, you need to call the [`optOutOfAirdrop`](/network/solidity-reference/IDistributionToDelegators#optoutofairdrop) method on the [`DistributionToDelegators`](/network/solidity-reference) contract with your `Identity` address.

</details>
<details>
<summary>Details</summary>

Details

F6. How do I get real-time Slack/Discord/Telegram alerts for issues with my Flare Entity?

To receive instant notifications about critical validator or data provider issues - such as FTSO or FDC reveal offenses, registration failures, and more - use the [flare-foundation/fsp-observer](https://github.com/flare-foundation/fsp-observer) monitoring service.

1.  Create a env file (e.g., `.env.fsp-observer`) with your configuration:
    
    .env.fsp-observer
    
    ```
    # RequiredRPC_BASE_URL="https://flare-api.flare.network"                # Flare RPC endpointIDENTITY_ADDRESS="0x0000000000000000000000000000000000000000" # your identity address# Optional notification channelsNOTIFICATION_DISCORD_WEBHOOK="https://discord.com/api/webhooks/..."NOTIFICATION_TELEGRAM_BOT_TOKEN="your-telegram-bot-token"NOTIFICATION_TELEGRAM_CHAT_ID="your-telegram-chat-id"NOTIFICATION_SLACK_WEBHOOK="https://hooks.slack.com/services/..."NOTIFICATION_GENERIC_WEBHOOK="http://host:port/path"          # generic POST webhook
    ```
    
    warning
    
    Make sure this env file is **not committed** to version control (add it to `.gitignore` if needed).
    
2.  Run the observer using Docker:
    
    ```
    docker run --env-file .env.fsp-observer ghcr.io/flare-foundation/fsp-observer:main
    ```
    

The container will watch your identity and send notifications to any configured channels when issues are detected. If you encounter problems or have feature requests, open an issue on the [GitHub issues page](https://github.com/flare-foundation/fsp-observer/issues).

</details>