How to Run the Avail Light Client
The guide outlines how to set up an Avail light client to connect with the Avail Network. You can either:
- Use Availup (opens in a new tab) to run the light client.
- Download and run a pre-built binary.
- Build your Light client from source
Latest release
You can find the latest release binary in the avail-light
(opens in a new tab) repository.
RECOMMENDED VERSION
You can find the latest release of the Avail LC from our Github repo (opens in a new tab). For now though we recommend most users to
run v1.11.1
(opens in a new tab) of the Avail light client for maximal network support.
We will keep this recommendation updated.
Light client modes
The Avail light client has two main modes of operation:
- Light-client mode: The basic mode of operation and is always active no matter the mode selected.
If an
app_id
is not provided (or is = 0), this mode will commence. On each header received the client does random sampling using two mechanisms:
- DHT - client first tries to retrieve cells via Kademlia.
- RPC - if DHT retrieve fails, the client uses RPC calls to Avail nodes to retrieve the needed cells. The cells not already found in the DHT will be uploaded.
Once the data is received, light client verifies individual cells and calculates the confidence, which is then stored locally.
- App-client mode: If an
app_id > 0
is given in the config file, the application client (part of the light client) downloads all the relevant app data, reconstructs it and persists it locally. Reconstructed data is then available to accessed via an HTTP endpoint.
Please note that each app/rollup running on Avail DA will have a unique app_id
, which will be an integer > 0
.
When running in the App-client mode, the Avail LC will only download and verify data relevant to that specific app_id
.
The idea here was to give rollup developers the ability to verify data specifically for their rollup, with minimal overhead.
Running the light client (Linux, MacOS)
availup
(opens in a new tab) is the recommended way of running the Avail light client for most users.
availup
is a shell wrapper that allows you to spin up your own instance of the Avail light client
with a simple curl
command.
To run the Avail LC using availup
, make sure you have curl
(opens in a new tab) installed on your system. To check, quickly:
curl --version
- To spin up an Avail light client on the Turing testnet, just run this one command in your terminal:
curl -sL1 avail.sh | bash
- If everything goes well, the client output will look like this:
Sample output
2024-03-20T10:50:25.528628Z INFO avail_light::light_client: Processing finalized block block_number=562690 block_delay=20
2024-03-20T10:50:25.528706Z INFO avail_light::light_client: Random cells generated: 10 block_number=562690 cells_requested=10
2024-03-20T10:50:26.069497Z INFO avail_light::network: Cells fetched from DHT block_number=562690 cells_total=10 cells_fetched=0 cells_verified=0 fetch_elapsed=540.755792ms proof_verification_elapsed=2.208µs
2024-03-20T10:50:28.322706Z INFO avail_light::network: Cells fetched from RPC block_number=562690 cells_total=10 cells_fetched=10 cells_verified=10 fetch_elapsed=2.232714917s proof_verification_elapsed=20.404208ms
2024-03-20T10:50:28.322987Z INFO avail_light::light_client: Confidence factor: 99.90234375 block_number=562690 confidence=99.90234375
2024-03-20T10:50:28.323134Z INFO avail_light::light_client: Sleeping for 14.61143875s seconds
2024-03-20T10:50:28.323154Z INFO avail_light::api::v2: Message published to clients topic=ConfidenceAchieved published=0 failed=0
2024-03-20T10:50:28.859369Z INFO avail_light::network::p2p::event_loop: Cell upload success rate for block 562690: 0/10. Duration: 0
2024-03-20T10:50:41.535425Z INFO avail_light::network::rpc::subscriptions: New justification at block no.: 562692, hash: 0x3b602253298ce9bec9b5b8f0c8767f14502ccaa17a003dfba77f9d90edeaf5da
2024-03-20T10:50:41.709011Z INFO avail_light::network::rpc::subscriptions: Header no.: 562692
2024-03-20T10:50:41.709557Z INFO avail_light::network::rpc::subscriptions: Number of matching signatures: 5/7 for block 562692, set_id 223
2024-03-20T10:50:41.709574Z INFO avail_light::network::rpc::subscriptions: Storing finality checkpoint at block 562692
2024-03-20T10:50:41.709908Z INFO avail_light::network::rpc::subscriptions: Sending finalized block 562692
2024-03-20T10:50:41.709966Z INFO avail_light::api::v2: Message published to clients topic=HeaderVerified published=0 failed=0
2024-03-20T10:50:42.936699Z INFO avail_light::light_client: Processing finalized block block_number=562691 block_delay=20
2024-03-20T10:50:42.936761Z INFO avail_light::light_client: Random cells generated: 10 block_number=562691 cells_requested=10
2024-03-20T10:50:43.472932Z INFO avail_light::network: Cells fetched from DHT block_number=562691 cells_total=10 cells_fetched=0 cells_verified=0 fetch_elapsed=536.136083ms proof_verification_elapsed=3.042µs
2024-03-20T10:50:46.513570Z INFO avail_light::network: Cells fetched from RPC block_number=562691 cells_total=10 cells_fetched=10 cells_verified=10 fetch_elapsed=3.022786041s proof_verification_elapsed=17.810542ms
2024-03-20T10:50:46.513706Z INFO avail_light::light_client: Confidence factor: 99.90234375 block_number=562691 confidence=99.90234375
2024-03-20T10:50:46.513785Z INFO avail_light::light_client: Sleeping for 15.195224667s seconds
2024-03-20T10:50:46.513795Z INFO avail_light::api::v2: Message published to clients topic=ConfidenceAchieved published=0 failed=0
2024-03-20T10:50:47.056255Z INFO avail_light::network::p2p::event_loop: Cell upload success rate for block 562691: 0/10. Duration: 0
- If you want to read about all the different flags you can use to run the Avail LC
using
availup
, you can always check out our Github repo (opens in a new tab).
Running the light client (Windows)
Windows Subsystem for Linux (WSL) (opens in a new tab) is a Windows feature that allows you to run a Linux distribution directly on Windows, without having to set up a separate virtual machine or a dual-boot system.
However, we realise that working with WSL might be inconvenient for some users. We have therefore also included instructions on how to run the Avail light client natively on Windows without having to go through any technical hassles.
-
Go to the releases page of the Avail light client repo (opens in a new tab), and download the
avail-light-windows-runner.zip
file. -
Right click the downloaded file and extract it to a convenient location.
-
Then run the
availup.bat
file by double clicking it. This will start the Avail light client. -
If everything goes well, the client output will look like this:
Sample output
2024-03-20T10:22:23.821042Z INFO avail_light::api::v2: Message published to clients topic=HeaderVerified published=0 failed=0
2024-03-20T10:22:23.854448Z INFO avail_light::network: Cells fetched from RPC block_number=562606 cells_total=10 cells_fetched=10 cells_verified=10 fetch_elapsed=466.901875ms proof_verification_elapsed=10.431583ms
2024-03-20T10:22:23.854573Z INFO avail_light::light_client: Confidence factor: 99.90234375 block_number=562606 confidence=99.90234375
2024-03-20T10:22:23.854635Z INFO avail_light::light_client: Sleeping for 19.965855416s seconds
2024-03-20T10:22:23.854643Z INFO avail_light::api::v2: Message published to clients topic=ConfidenceAchieved published=0 failed=0
2024-03-20T10:22:24.392198Z INFO avail_light::network::p2p::event_loop: Cell upload success rate for block 562606: 0/10. Duration: 0
2024-03-20T10:22:43.821867Z INFO avail_light::light_client: Processing finalized block block_number=562607 block_delay=20
2024-03-20T10:22:43.821955Z INFO avail_light::light_client: Random cells generated: 10 block_number=562607 cells_requested=10
2024-03-20T10:22:44.358772Z INFO avail_light::network: Cells fetched from DHT block_number=562607 cells_total=10 cells_fetched=0 cells_verified=0 fetch_elapsed=536.778958ms proof_verification_elapsed=2.292µs
2024-03-20T10:22:45.937348Z INFO avail_light::network: Cells fetched from RPC block_number=562607 cells_total=10 cells_fetched=10 cells_verified=10 fetch_elapsed=1.56179875s proof_verification_elapsed=16.692791ms
2024-03-20T10:22:45.938417Z INFO avail_light::light_client: Confidence factor: 99.90234375 block_number=562607 confidence=99.90234375
2024-03-20T10:22:45.938564Z INFO avail_light::api::v2: Message published to clients topic=ConfidenceAchieved published=0 failed=0
2024-03-20T10:22:46.473163Z INFO avail_light::network::p2p::event_loop: Cell upload success rate for block 562607: 0/10. Duration: 0
2024-03-20T10:22:46.527044Z INFO avail_light::network::rpc::subscriptions: New justification at block no.: 562608, hash: 0xbea2a4b136c271b72314e2349577136bf7cdc7c732bc3909e280eb602b8af643
2024-03-20T10:22:46.672163Z INFO avail_light::network::rpc::subscriptions: Header no.: 562608
2024-03-20T10:22:46.673730Z INFO avail_light::network::rpc::subscriptions: Number of matching signatures: 5/7 for block 562608, set_id 223
2024-03-20T10:22:46.673755Z INFO avail_light::network::rpc::subscriptions: Storing finality checkpoint at block 562608
2024-03-20T10:22:46.674002Z INFO avail_light::network::rpc::subscriptions: Sending finalized block 562608
2024-03-20T10:22:46.674087Z INFO avail_light::api::v2: Message published to clients topic=HeaderVerified published=0 failed=0
2024-03-20T10:22:46.674150Z INFO avail_light::light_client: Sleeping for 19.998042125s seconds
Please note that trying to download and run a precompiled binary via a .zip
file might result in
windows warning you about the file being potentially harmful. You will need to bypass this warning to run the light client.
Setting your identity using identity.toml
Whenever you run an Avail LC, you will notice a file named identity.toml
being created in the same
directory as the binary. This is a default file that contains a random seed phrase
that represents your
identity on the network.
You can also set your own seed phrase
by creating an identity.toml
file, and passing it as an argument using the
--identity
flag.
To do so:
- create an
identity.toml
file anywhere in your system. - Initialize a variable named
avail_secret_seed_phrase
like this:
avail_secret_seed_phrase = 'AvailDA rice is demon the pair best almond DA walnut solution walrus out tube there'
- Pass this file to the light client using the
--identity
flag like this. This could look something like this:
curl -sL1 avail.sh | bash -s -- --identity identity.toml
Please note this command worked for a system where the identity.toml
file was in the same directory as the terminal.
You will need to pass the full path to the identity.toml
file if it is located elsewhere.
Final notes
Please note that the Avail light client is heavily customisable. The instructions in this page were kept as simple as possible for initial convenience. You can customise the LC's behaviour by:
- Specifying a number of different flags (opens in a new tab).
- Setting up a
config.yaml
file. You can find a full reference for theconfig.yaml
file in this README file (opens in a new tab).