Avail is now backed by prominent investors to accelerate the unification of web3 🎉🎉

Docs
Light Client API Reference

Avail Light Client reference

BEFORE WE START

  1. 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.
  2. It is recommended to use API-v2 over API-v1, although both are supported.
  3. 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.

How to run the Rust code snippets

  1. Create a new Rust project:
    cargo new <project-name>
  2. Add these dependencies to the Cargo.toml file:
    [dependencies]
    reqwest = { version = "0.12", features = ["json"] }
    serde = { version = "1.0", features = ["derive"] }
    serde_json = "1.0"
    tokio = { version = "1.36", features = ["full"] }
    base64 = "0.22"
  3. Paste the code snippets into the main.rs file, and run the project with cargo run.

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)

JSON response

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

JSON response

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

JSON response

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.7.10",
  "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:

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

  2. 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:

  1. Access to a running Light Client.
  2. A subscription ID generated using the v2/subscriptions method.
  3. 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:


Avail-fusion

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:

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