Avail Light Client reference

BEFORE WE START

The indiviual behaviour of some methods may differ depending on which mode the light client is runnning in. This will be documented in the individual method descriptions.
It is recommended to use API-v2 over API-v1, although both are supported.
The methods documented here were tested on a locally running instance of the Avail light client. They will however work with remotely hosted instances as well.
You can check out or docs for instructions on running your own instance of the Avail light client

Setting up the dev environment

Set up your dev enviornment with curl and Rust:

To use the Avail light client API with curl, you just need to have curl installed on your system. You can check if it is installed by running:

curl --version

If this does not work, go to curl's website (opens in a new tab) to install it on your system.

API-v1

v1/latest_block

Allows us to fetch the latest block processed by light client.

Params:

None

Response:

Latest block number

curl "http://127.0.0.1:7000/v1/latest_block"

Sample Response:

{
  "latest_block": 10
}

v1/confidence/{block_number}

Allows us to fetch the confidence in % for a given block number.

Params:

block number

Response:

block number
confidence in %
serialised confidence

curl "http://127.0.0.1:7000/v1/confidence/1"

Sample Response:

{
  "block": 1,
  "confidence": 93.75,
  "serialised_confidence": "5232467296"
}

If confidence is not computed, and specified block is before the latest processed block:

"Not synced"

If confidence is not computed, and specified block is after the latest processed block:

"Not found"

v1/appdata/{block_number}

Given a block number, it retrieves the hex-encoded extrinsics for the specified block, if available. Alternatively, if specified by a query parameter, the retrieved extrinsic is decoded and returned as a base64-encoded string.

Params:

block_number - block number (required)
decode - true if decoded extrinsics are requested (boolean, optional, default is false)

curl "http://127.0.0.1:7000/v1/appdata/1?decode=true"

Sample Response:

{
  "block": 46,
  "extrinsics": ["ZXhhbXBsZQ=="]
}

If application data is available, and decode is false or unspecified:

{
  "block": 1,
  "extrinsics": [
    "0xc5018400d43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d01308e88ca257b65514b7b44fc1913a6a9af6abc34c3d22761b0e425674d68df7de26be1c8533a7bbd01fdb3a8daa5af77df6d3fb0a67cde8241f461f4fe16f188000000041d011c6578616d706c65"
  ]
}

If application data is available, and decode is true:

{ "block": 1, "extrinsics": ["ZXhhbXBsZQ=="] }

If application data is not available, and specified block is the latest block:

"Processing block"

If application data is not available, and specified block is not the latest block:

"Not found"

v1/mode

Retrieves the operating mode of the Avail light client. The Light client can operate in two different modes, LightClient or AppClient, depending on configuration of application ID(app-id) flag.

Params:

None

Response:

Operating mode

curl "http://127.0.0.1:7000/v1/mode"

If operating mode is LightClient response is:

"LightClient"

In case of AppClient mode, response is:

{"AppClient": {app_id}}

v1/status

Retrieves the status of the latest block processed by the light client.

Params:

None

Response:

Latest block number
Confidence in %
App ID

curl "http://127.0.0.1:7000/v1/status"

Sample Response:

{ 
  "block_num": 89,
  "confidence": 93.75,
  "app_id": 1 
}

If there are no processed blocks:

"Not found"

API-v2

v2/version

Gets the version of the light client binary, and the version of the compatible network.

Params:

None

Response:

Light Client version
Network version

curl "http://127.0.0.1:7000/v2/version"

Sample Response:

{
  "version":"v1.8.1",
  "network_version":"1.10"
}

v2/status

Gets current status and active modes of the light client.

Params:

None

Response:

modes - active modes
app_id - if app mode is active, this field contains configured application ID
genesis_hash - genesis hash of the network to which the light client is connected
network - network host, version and spec version light client is currently con
blocks - state of processed blocks
partition - if configured, displays partition which light client distributes to the peer to peer network

Modes

light - data availability sampling mode, the light client performs random sampling and calculates confidence
app - light client fetches, verifies, and stores application-related data
partition - light client fetches configured block partition and publishes it to the DHT

Blocks

latest - block number of the latest finalized (opens in a new tab) block received from the node
available - range of blocks with verified data availability (configured confidence has been achieved)
app_data - range of blocks with app data retrieved and verified
historical_sync - state for historical blocks syncing up to configured block (ommited if historical sync is not configured)

Historical sync

synced - true if there are no historical blocks left to sync
available - range of historical blocks with verified data availability (configured confidence has been achieved)
app_data - range of historical blocks with app data retrieved and verified

curl "http://127.0.0.1:7000/v2/status"

Sample Response:

{
  "modes":["light"],
  "genesis_hash":"0x6f09966420b2608d1947ccfb0f2a362450d1fc7fd902c29b67c906eaa965a7ae",
  "network":"wss://goldberg.avail.tools:443/ws/1.11.0-38304bb5126/data-avail/22",
  "blocks":{
    "latest":572269,
    "available":{
      "first":572068,
      "last":572268
    }
  }
}

v2/blocks/{block_number}

Gets specified block status and confidence if applicable.

Use cases:

Polling the status of the block
Querying historical block statuses

Params:

block_number - block number (required)

Response:

status - block status
confidence - data availability confidence, available if block processing is finished.

Status

unavailable - block will not be processed if
latest_block - sync_depth > block_number
pending - block will be processed at some point in the future if
latest_block - sync_depth ≤ block_number ≤ latest_block
verifying-header - block processing is started, and the header finality is being checked
verifying-confidence - block header is verified and available, confidence is being checked
verifying-data - confidence is achieved, and data is being fetched and verified (if configured)
finished - block header is available, confidence is achieved, and data is available (if configured)

This status does not give information on what is available. In the case of web sockets messages are already pushed, similar to case of the frequent polling, so header and confidence will be available if verifying-header and verifying-confidence has been successful.

curl "http://127.0.0.1:7000/v2/blocks/672481"

Sample Response:

{
  "status":"verifying-data",
  "confidence":99.90234375
}

If block_number > latest_block, block status cannot yet be derived and the response on this and other endpoints with /v2/blocks/{block_number} prefix is:

Not Found

v2/blocks/{block_number}/header

Gets the header for a specifc block if available.

Params:

block_number - block number (required)

Response:

If block_status = "verifying-confidence|verifying-data|finished", the header is available, and the response is:

HTTP/1.1 200 OK
Content-Type: application/json
 
{
  "hash": "{hash}",
  "parent_hash": "{parent-hash}",
  "number": {number},
  "state_root": "{state-root}",
  "extrinsics_root": "{extrinsics-root}",
  "extension": {
    "rows": {rows},
    "cols": {cols},
    "data_root": "{data-root}", // Optional
    "commitments": [
      "{commitment}", ...
    ],
    "app_lookup": {
      "size": {size},
      "index": [
        {
          "app_id": {app-id},
          "start": {start}
        }
      ]
    }
  }
}

If block_status = "unavailable|pending|verifying-header", header is not available and response is:

HTTP/1.1 400 Bad Request

curl "http://127.0.0.1:7000/v2/blocks/592445/header"

v2/blocks/{block_number}/data?fields=data,extrinsic

Gets the block data if available. Query parameter fields specifies whether to return decoded data and encoded extrinsic (with signature). If fields parameter is omitted, response contains hash and data, while extrinsic is omitted.

curl "http://127.0.0.1:7000/v2/blocks/{block_number}/data?fields=data,extrinsic"

Sample Response:

If block_status = "finished", data is available and the response is:

{
  "data_transactions": [
    {
      "data": "{base-64-encoded-data}" // Optional
      "extrinsic": "{base-64-encoded-extrinsic}", // Optional
    }
  ]
}

If block_status is not “finished”, or app mode is not enabled, data is not available and the response is:

Bad Request

The next few methods are used to submit data to the Avail network. But to use them:

you need to configure an identity.toml file which will contain the seed phrase for an account that has some AVAIL tokens. You can learn how to do that here.
You will also need to run the Avail LC in app-client mode. The command to do all this will look something like this:

curl -sL1 avail.sh | bash -s -- --app_id 1 --identity identity.toml --network goldberg

v2/submit

Submits application data to the avail network.
In case of data transaction, data transaction is created, signed and submitted.
In case of extrinsic, externaly created and signed transaction is submitted.

Only one field is allowed per request.
Both data and extrinsic has to be encoded using base64 encoding.

Params:

base64 encoded data or extrinsic

Response:

block_number - block number where transaction is included
block_hash - block hash where transaction is included
hash - transaction hash
index - transaction index in the block

curl -XPOST 127.0.0.1:7000/v2/submit --header "Content-Type: application/json" --data '{"data":"dGVzdAo="}'

Sample Response:

{
  "block_number": {block-number},
  "block_hash": "{block-hash}",
  "hash": "{transaction-hash}",
  "index": {transaction-index}
}

If app mode is not active (or signing key is not configured and data is submitted) response is:

Not found

WebSocket API

The Avail Light Client WebSocket API allows real-time communication between a client and a server over a persistent connection. The Web socket API can be used on its own or in combination with HTTP API to enable different pull/push use cases.

HTTP and Websocket are twi different ways of communicating with a server. HTTP is a request-response protocol, where a connection persists for only so long as the request is being processed. In contrast, a websocket connection persists for as long as the client and server are connected. This allows for real-time communication between the two, and enables the client to fetch information from the server as soon as it is available, without having to poll the server for updates.

HOW TO CONNECT TO THE WEBSOCKET SERVER
You cannot use CURL to send websocket commands, since CURL cannot maintain a persistent connection. Although there are a variety of librariries we can use, the following examples are using wscat (opens in a new tab).

To install wscat, simply run:

npm install -g wscat

v2/subscriptions

The Avail LC Websocket API generates a unique subscription_id upon request. This ID is used to connect to the websocket server. The v2/subscriptions method creates subscriptions for given topics. In case of reconnects, the user needs to subscribe again.

😝

Ironically the only way to generate a subscription ID for a websocket connection is through an http method.

Topics

header-verified - header finality is verified and header is available
confidence-achieved - confidence is achieved
data-verified - block data is verified and available

Data fields

Filters data-verified message. Optional parameter used when encoded extrinsic is needed. If omitted, only decoded data is present in the message.

Request:

curl -X POST "http://127.0.0.1:7000/v2/subscriptions" \
     -H "Content-Type: application/json" \
     -d '{
           "topics": ["header-verified", "confidence-achieved", "data-verified"],
           "data_fields": ["data", "extrinsic"]
         }'

Sample Response:

{
  "subscription_id": "{subscription-id}"
}

v2/ws/{subscription-id}

You can use this method to actually connect to Avail Light Client web socket. Multiple connections are currently allowed.

To connect to the Avail LC websocket API, you need:

Access to a running Light Client.
A subscription ID generated using the v2/subscriptions method.
to run this wscat command in the terminal:

wscat -c ws://127.0.0.1:7000/v2/ws/{subscription-id}

Your terminal should look something like this:

Please note that you will regularly receive information related to the topics you chose to subscribe to for as long as the ws connection persists, even if you don't actually send any messages.

Every request should contain unique request_id field, used to correlate request with response.

Subscription IDs vs Request IDs

Each time you use the v2/subscriptions method, you will receive a unique subscription_id. This ID is used to connect to the websocket server.

Each of these IDs will be of the UUID4 format (opens in a new tab).

Coming to requests, every request you make to the websocket server should contain a request_id field, which will need to be a UUID4 value. You can choose to use a single, random UUID4 value to send all your requests, or you can use a unique UUID4 value for each request you send. The choice is yours.

Using a sngle UUID4 value is simple, but using a unique UUID4 value for each request can help you correlate each response with a unique request.

The Avail LC API was designed with dev experience in mind, and this way you can choose the way that suits you best.

v2/ws/version

Request Avail Light Client version data.

Sample Request:

{"type":"version","request_id":"4a482bb0-3c22-475d-a2b8-af1c27aa2636"}

Sample Response:

{"topic":"version","request_id":"4a482bb0-3c22-475d-a2b8-af1c27aa2636","message":{"version":"v1.7.10","network_version":"1.10"}}

v2/ws/status

Request current Avail Light Client status data.

Sample Request:

{"type":"status","request_id":"4a482bb0-3c22-475d-a2b8-af1c27aa2636"}

Sample Response:

{"topic":"status","request_id":"4a482bb0-3c22-475d-a2b8-af1c27aa2636","message":{"modes":["light","app"],"app_id":1,"genesis_hash":"0x6f09966420b2608d1947ccfb0f2a362450d1fc7fd902c29b67c906eaa965a7ae","network":"wss://goldberg.avail.tools:443/ws/1.11.0-38304bb5126/data-avail/22","blocks":{"latest":597705,"available":{"first":596467,"last":597704},"app_data":{"first":596467,"last":597704}}}}

v2/ws/submit

Submits data transaction to the Avail.

Sample Request:

{"type":"submit","request_id":"4a482bb0-3c22-475d-a2b8-af1c27aa2636","message":{"data":"dGVzdAo="}}

Sample Response:

 {"topic":"data-transaction-submitted","request_id":"4a482bb0-3c22-475d-a2b8-af1c27aa2636","message":{"block_number":597725,"block_hash":"0x84803b93bf96aea90fae8fcb21cae70d310783ae8e9c4f4e1d696cec2791c0e3","hash":"0x290efdc7856fd29ec406c610f79aaa3c8079c11f8338093efad739b454bef0ac","index":1}}

Please note that to submit any sort of data to Avail, you need to:

Run the Avail light client in appmode.
Configure an identity.toml file with the seed phrase of an account that has some AVAIL tokens.

Run an Avail Light Client Run an Avail node

Phase 1 of Avail's unification drop has ended. Phase 2 now begins, 👉👉 check out this page 👈👈 for more information.

Avail Light Client reference

Setting up the dev environment

API-v1

v1/latest_block

v1/confidence/{block_number}

v1/appdata/{block_number}

v1/mode

v1/status

API-v2

v2/version

v2/status

Modes

Blocks

Historical sync

v2/blocks/{block_number}

Status

v2/blocks/{block_number}/header

v2/blocks/{block_number}/data?fields=data,extrinsic

v2/submit

WebSocket API

v2/subscriptions

Topics

Data fields

v2/ws/{subscription-id}

v2/ws/version

v2/ws/status

v2/ws/submit