Skip to main content

Flare Systems Provider

Migration

The separate FTSO and FDC deployments are being merged into a single deployment using the flare-systems-deployment repository, with FDC additionally requiring fdc-suite-deployment for verifiers and nodes.

To stay up to date on the latest information check out the Flare Discourse Forum.

This guide provides a sample deployment configuration for infrastructure providers participating in the Flare Systems Protocol (FSP). The FSP consists of Flare Time Series Oracle (FTSO) and Flare Data Connector (FDC).

Data Provider System for FSPData Provider System for FSP

An FSP provider system 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.
Minimal conditions

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

*Updated every reward epoch (3.5 days), with epochs starting on Monday and Thursday.

Currently, claiming rewards needs to be performed manually. Automated solutions are being worked upon to simplify this process.

Get listed on explorers

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

Hardware requirements​

To deploy all FSP components on a single HW instance:

Requirement
CPU16/32 cores
RAM64 GB
Disk space4 TB SSD
  • Disk speed: 1200 MB/s read and 600 MB/s write, or higher
  • Network speed: 40 Mbps, or higher
Deploying components on multiple instances

It is possible to split the FSP deployment across multiple instances, but this deviation from the recommended deployment configuration could introduce additional friction when updating.

Prerequisites​

Ensure you have the following tools installed:

Registration​

Registration only needs to be performed once.

Register addresses and key​

Automated registration on testnets.
danger

Automated registration can expose private keys. Only use on testnets.

On testnets, you can register your entity addresses with the register-entities.ts script and your sortition public key with the register-public-keys.ts scripts.

  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
  1. Create an entities.json file with the following account addresses and private keys:
[
  {
    "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>"
  }
]
  1. Setup the following variables in .env:
.env
ENTITIES_FILE_PATH="<path to entities.json>"
COSTON2_RPC=<non-public Coston2 RPC>
CHAIN_CONFIG="coston2"
  1. Run the registration tasks:
yarn hardhat --network coston2 register-entities
yarn hardhat --network coston2 register-public-keys

Each entity in the FSP system must register the following five addresses:

  • Identity: Main identity account of the voter. On mainnet this should be held in cold storage. This account is required for initial data provider setup, but is not used during each voting round.

  • Submit: Used for sending commit and reveal transactions.

  • SubmitSignatures: Used for sending voting round result signature transactions. (To avoid nonce conflicts, Flare System Client uses multiple accounts for submitting transactions).

  • SigningPolicy: Used for signature generation during the voting round, and reward epoch signing policy signing (it's a system protocol ran once during reward epoch to establish reward epoch settings, including valid voters and their weights).

  • Delegation: Account to which community should delegate funds (using WNat contract) to increase the vote power of the voter (identity/entity) - and also to later get the rewards.

To register you can directly call the EntityManager contract. For the contract address, see the Solidity Reference. The relevant methods on the EntityManager contract are:

Proposal methodConfirmation method
proposeSubmitAddressconfirmSubmitAddressRegistration
proposeSubmitSignaturesAddressconfirmSubmitSignaturesAddressRegistration
proposeSigningPolicyAddressconfirmSigningPolicyAddressRegistration
proposeDelegationAddressconfirmDelegationAddressRegistration

First call the propose... from your Identity address and then the confirm... with the proposed address.

Fund addresses​

All addresses need to be funded for gas fees. The Delegation account is used for establishing voter power, which can be achieved by wrapping funds directly or by delegation from other accounts. Wrapping can be done via:

Ensure sufficient vote power

The protocol operation uses normalized weights, and the Delegation address should have at least 150 WNat to obtain a non-zero vote power.

NetworkNative TokenWrapped Native Token (WNat)
Flare MainnetFLRWFLR
Flare Testnet Coston2C2FLRWC2FLR
Songbird Canary-NetworkSGBWSGB
Songbird Testnet CostonCFLRWCFLR

The WNat contract addresses are in the Network Solidity Reference.

Register sortition key​

Generate a sortition key to use in Fast Updates. You can use the fast-updates/go-client docker image to generate a key:

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

Accounts for Fast Updates submission need to be generated and funded with gas fees. These can be any accounts not used for the five accounts in register addresses and key. You are recommended to use three separate accounts to avoid nonce conflicts.

When registering the sortition key using the explorer, you will need to manually create a signature:

docker run --rm ghcr.io/flare-foundation/fast-updates/go-client:latest keygen --key <sortitionKeyPrivateKey> --address <identityAddress>

Register the generated sortition key and signature via the EntityManager contract by calling registerPublicKey with your identity address, use the signature generated by the previous command as the input to _verificationData.

Register validator node​

To register your validator node, call the EntityManager contract's registerNodeId function by providing your identity address for each validator node.

Required Input Arguments​

  • _nodeId: 20-byte node ID in hexadecimal format.
  • _certificateRaw: Raw certificate bytes in hexadecimal format.
  • _signature: Signature bytes in hexadecimal format.

Registration Steps​

  1. Locate Certificate and Private Key Files

    Find the certificate (.crt) and private key (.key) files for your validator node. The default file paths are:

    • ~/.avalanchego/staking/staker.key
    • ~/.avalanchego/staking/staker.crt

  2. Set Environment Variables

    Define necessary environment variables by copying and pasting the following snippet into your terminal:

    PATH_TO_CRT=~/.avalanchego/staking/staker.crt
    ZERO_PREFIX=0000000000000000000000000000000000000000000000000000000000000000
    PATH_TO_KEY=~/.avalanchego/staking/staker.key
    IDENTITY_ADDRESS=<YourIdentityAddressWithout0xPrefix>

  3. Generate required hex values

    _nodeId: If you are using an older version of openssl, omit the -provider legacy flag.

    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:

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

    _signature:

    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

Setup FDC​

The FDC suite integrates blockchain data sources through a network of blockchain nodes, indexers, and API servers. This setup allows secure and efficient data verification. The blockchain data flow is of two types:

  • UTXO-Based Chains (Bitcoin, Dogecoin, Ripple): Use an indexer to create a local database from the blockchain, exposing data through a Verifier API server.

  • EVM Chains (Ethereum, Flare, Songbird): Directly query the RPC node using the Verifier API server.

Prerequisites​

  • Docker Engine
  • Deployment user in the docker group
  • Docker folder set to a mount point that has sufficient disk space for Docker volumes. The installation creates several Docker volumes.

Required components​

You can use the following components to run a full FDC suite.

Blockchain node images​

NetworkBlockchain node image
Bitcoinflarefoundation/bitcoin
Dogecoinflarefoundation/dogecoin
Rippleflarefoundation/rippled
Ethereumethereum/client-go & prysm

Indexers and verifiers​

NetworkIndexerVerifier
BTCflare-foundation/verifier-utxo-indexerflare-foundation/verifier-indexer-api
DOGEflare-foundation/verifier-utxo-indexerflare-foundation/verifier-indexer-api
XRPflare-foundation/verifier-xrp-indexerflare-foundation/verifier-indexer-api
EVM-flare-foundation/evm-verifier
info
  • Flare Mainnet and Songbird Canary-Network nodes are required for EVM verification but are not listed here.
  • You are not required to use exactly these components, e.g. if you already have a compatible Bitcoin RPC node, you can configure your deployment to run everything else except for Bitcoin node.
  • You can split the deployment across multiple servers.

Configuring blockchain nodes​

Start by cloning the fdc-suite-deployment repo:

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

Build Docker images (optional)​

Docker images are automatically built and published to GHCR. By default the deployment will download the images automatically. If you need to build them manually clone the required git repository listed in Indexers and verifiers, and run:

docker build -t <image-tag> . # replace image tag with tag used in docker-compose.zml

Bitcoin (BTC)​

Generate the authentication password:

cd nodes-mainnet/btc
./generate-password.sh

Sample output:

password: c021cae645db6d3371b26ced94c8d17a5d9f3accbf3591d8b4c0be19623e5662
String to be appended to bitcoin.conf:
rpcauth=admin:a0956d81a2344f1602d9ed7b82ef3118$2caf19c9cf27937f728f600fc14e8db97f80218d727e331a57c3cfc55b3e17fe
Your password:
c021cae645db6d3371b26ced94c8d17a5d9f3accbf3591d8b4c0be19623e5662

Alternatively you can configure the username and password manually:

./rpcauth.py <USERNAME> <PASSWORD>

Dogecoin (DOGE)​

Same configuration process as Bitcoin.

cd nodes-mainnet/doge
./generate-password.sh

Ripple (XRP)​

No additional configuration required.

Ethereum (ETH)​

Generate JWT for Authentication:

openssl rand -hex 32 > nodes-mainnet/eth/jwt.hex
warning

Blockchain nodes expose all ports by default.

Configuring indexers and verifiers​

  1. Copy .env.example into .env:

    cp .env.example .env

  2. Configure required keys

    • RPC Nodes Authentication: Use credentials generated earlier. If you run blockchain nodes and verifiers on the same server, you can use the ip 172.17.0.1 to reach the nodes.

    • Start Block Number: Set *_START_BLOCK_NUMBER to a block finalized 14 days ago. This needs to be set the first time when you start the indexers to avoid indexing too much data. FDC requires at least 14 days of history. On later restarts indexers will start indexing from the latest block in the database.

    • Testnet Mode: Set TESTNET=true if using testnets.

    • API Keys: Configure VERIFIER_API_KEYS with comma-separated API keys. One or more comma separated keys can be configured. You will likely need at least one key for FDC client that will call verifier api servers.

    • Database Passwords: Set *_DB_PASSWORD variables to random strings. These are used internally for the indexer database.

  3. Generate configuration files

    ./generate-config.sh

    This script populates config files from *.example templates in:

    • verifiers/btc/
    • verifiers/doge/
    • verifiers/xrp/
    • evm-verifier/

Start services​

Start blockchain nodes​

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

  2. Start the node:

    docker compose up -d

Repeat these steps for each blockchain node you intend to run.

Start indexers and verifiers​

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

  2. Start the verifier:

    docker compose up -d

Repeat these steps for all verifiers you intend to run.

Setup FTSO​

Feed value provider​

warning

The reference implementation of Feed Value Provider is only provided for testing purposes and should not be relied on. Data providers are expected to reimplement this with their own data sources, following the REST API specification.

Start your own feed value provider, or (for testing only) use the reference feed value provider:

docker run --rm -it --publish "0.0.0.0:3101:3101" --network "ftso-v2-deployment_default" ghcr.io/flare-foundation/ftso-v2-example-value-provider

Once the container is running, you can find the API spec at: http://localhost:3101/api-doc

Troubleshooting​

For initial testing a fixed value provider can be used that simply returns a constant instead of reading data from external data sources. It can be started by setting the variable VALUE_PROVIDER_IMPL=fixed:

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

You should see the following line in the logs:

WARN [FixedFeed] Initializing FixedFeed, will return 0.01 for all feeds.

Generate configuration and deploy​

  1. Clone flare-systems-deployment repository:

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

  2. Copy the sample configuration file:

    cp .env.example .env

  3. Fill out all the values using the information from Registration, Setup FDC and Setup FTSO.

  4. Generate the required configurations, you will need to rerun this command if you change your .env file:

    ./populate_config.sh

  5. Deploy the instance with the provided docker-compose.yaml

    docker compose up -d
    Stay up to date

    To pull the latest flare-systems-deployment image:

    docker compose pull

Troubleshooting​

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

Node maintenance​

  • Basic health checks:

    • 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

  • FDC health monitoring:

    • Query each FDC verifier with: GET http://{verifier-host}:{verifier-port}/verifier/{chain}/health

  • FTSO health monitoring:

    • Check minimal conditions status with:

      curl -s 'https://flare-systems-explorer.flare.network/backend-url/api/v0/entity?limit=100&offset=0&sort_ascending=true&sort_by=' | jq '.results[] | select(.identity_address == "YOUR_IDENTITY_ADDRESS") | .entityminimalconditions'

    • For registration, your log should contain:

      [01-03|23:02:03.175] INFO epoch/registry_utils.go:187 Voter 0x25f42DEf3fCc078DE8895Cd01de8AB6514020548 registered for epoch 3589
      [01-04|05:02:04.096] INFO epoch/registry_utils.go:187 Voter 0x25f42DEf3fCc078DE8895Cd01de8AB6514020548 registered for epoch 3590
      [01-04|11:02:07.113] INFO epoch/registry_utils.go:187 Voter 0x25f42DEf3fCc078DE8895Cd01de8AB6514020548 registered for epoch 3591
      [01-04|17:02:03.136] INFO epoch/registry_utils.go:187 Voter 0x25f42DEf3fCc078DE8895Cd01de8AB6514020548 registered for epoch 3592
      [01-04|23:02:03.217] INFO epoch/registry_utils.go:187 Voter 0x25f42DEf3fCc078DE8895Cd01de8AB6514020548 registered for epoch 3593

    • For submissions, your log should contain:

      [01-06|14:39:10.366] INFO protocol/submitter.go:76 Submitter submitSignatures successfully sent tx
      [01-06|14:39:31.273] INFO protocol/submitter.go:76 Submitter submit1 successfully sent tx
      [01-06|14:39:53.107] INFO protocol/submitter.go:76 Submitter submit2 successfully sent tx
      Set an alert

      Set an alert if there is no Submitter ... successfully sent tx message for 5-10 minutes

    • For finalization verification, your log should contain:

      [01-05|15:55:54.641] INFO finalizer/relay_client.go:168 Relaying finished for protocol 100 with success
      [01-05|15:55:55.686] INFO finalizer/relay_client.go:168 Relaying finished for protocol 200 with success
      [01-05|15:57:25.608] INFO finalizer/relay_client.go:168 Relaying finished for protocol 100 with non fatal error
      [01-05|15:57:28.937] INFO finalizer/relay_client.go:168 Relaying finished for protocol 200 with non fatal error
      Set an alert

      Set an alert if there is no Relaying finished for protocol ... for 5-10 minutes (protocol 100 is FTSOv2 and protocol 200 is FDC)