Skip to content

Commit

Permalink
Move V1 API to src/api/v1/README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@aterentic-ethernal
aterentic-ethernal committed May 29, 2024
1 parent 4e24e84 commit ff146b5
Show file tree
Hide file tree
Showing 2 changed files with 154 additions and 269 deletions.
275 changes: 6 additions & 269 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -248,280 +248,17 @@ max_kad_provided_keys = 1024
- In order to use network analyzer, the light client has to be compiled with `--features 'network-analysis'` flag; when running the LC with network analyzer, sufficient capabilities have to be given to the client in order for it to have the permissions needed to listen on socket: `sudo setcap cap_net_raw,cap_net_admin=eip /path/to/light/client/binary`
- To use RocksDB as persistent Kademlia store, compile `avail-light` binary with `--features "kademlia-rocksdb` on.

## Usage and examples
## API

### Fetching the number of the latest block processed by light client
API usage and examples can be found on the [Avail Docs](https://docs.availproject.org/docs/operate-a-node/run-a-light-client/light-client-api-reference).

To fetch the number of the latest block processed by light client, we can perform `GET` request on `/v1/latest_block` endpoint.
### API Version 2

```sh
curl "http://localhost:7007/v1/latest_block"
```

Response:

```json
{
"latest_block": 10
}
```

### Fetching the confidence for given block

To fetch the confidence for specific block, which is already processed by application client, we can perform `GET` request on `/v1/confidece/{block_number}` endpoint.

```sh
curl "http://localhost:7007/v1/confidence/1"
```

Response:

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

> `serialisedConfidence` is calculated as:
> `blockNumber << 32 | int32(confidence * 10 ** 7)`, where confidence is represented out of 10 ** 9.
### Fetching decoded application data for given block

After data is verified, it can be fetched with `GET` request on `/v1/appdata/{block_number}` endpoint, by specifying `decode=true` query parameter. In case `decode` is omitted or `false`, scale encoded extrinsics will be returned.

#### JSON response

```sh
curl "http://localhost:7007/v1/appdata/1?decode=true"
```

Response:

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

#### Decoded extrinsic

```sh
curl -s "http://127.0.0.1:7007/v1/appdata/1?decode=true" | jq -r '.extrinsics[-1]' | base64 -d
```

Response:

```json
"example"
```

### Get the running mode of the Light Client

```sh
curl "localhost:7007/v1/mode"
```

Response:

```json
{
"AppClient": 1
}
```

### Get the status of a latest block

```sh
curl "localhost:7007/v1/status"
```

Response:

```json
{
"block_num": 10,
"confidence": 93.75,
"app_id": 1
}
```

### Get the latest block

```sh
curl "localhost:7007/v1/latest_block"
```
API V2 reference can be found in the [V2 README file](src/api/v2/README.md).

Response:
### API Version 1 (deprecated)

```json
{
"latest_block": 255
}
```

### Health check

To perform health check of the light client, run:

```sh
curl -I "localhost:7007/health"
```

200 OK is expected response.

## API reference

In case of error, endpoints will return response with `500 Internal Server Error` status code, and descriptive error message.

### **GET** `/v1/mode`

Retrieves the operating mode of the light client. Light client can operate in two different modes, `LightClient` or `AppClient`, depending on configuration of application ID.

#### Responses

If operating mode is `LightClient` response is:

> Status code: `200 OK`
```json
"LightClient"
```

In case of `AppClient` mode, response is:

> Status code: `200 OK`
```json
{"AppClient": {app_id}}
```

### **GET** `/v1/latest_block`

Retrieves the latest block processed by the light client.

#### Responses

> Status code: `200 OK`
```json
{"latest_block":{block_number}}
```

### **GET** `/v1/confidence/{block_number}`

Given a block number, it returns the confidence computed by the light client for that specific block.

> Path parameters:
- `block_number` - block number (required)

#### Responses

In case when confidence is computed:

> Status code: `200 OK`
```json
{ "block": 1, "confidence": 93.75, "serialised_confidence": "5232467296" }
```

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

> Status code: `400 Bad Request`
```json
"Not synced"
```

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

> Status code: `404 Not Found`
```json
"Not found"
```

### **GET** `/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.

> Path parameters:
- `block_number` - block number (required)

> Query parameters:
- `decode` - `true` if decoded extrinsics are requested (boolean, optional, default is `false`)

#### Responses

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

> Status code: `200 OK`
```json
{
"block": 1,
"extrinsics": [
"0xc5018400d43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d01308e88ca257b65514b7b44fc1913a6a9af6abc34c3d22761b0e425674d68df7de26be1c8533a7bbd01fdb3a8daa5af77df6d3fb0a67cde8241f461f4fe16f188000000041d011c6578616d706c65"
]
}
```

If application data is available, and decode is `true`:

> Status code: `200 OK`
```json
{ "block": 1, "extrinsics": ["ZXhhbXBsZQ=="] }
```

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

> Status code: `401 Unauthorized`
```json
"Processing block"
```

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

> Status code: `404 Not Found`
```json
"Not found"
```

### **GET** `/v1/status`

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

> Path parameters:
- `block_number` - block number (required)

#### Responses

If latest processed block exists, and `app_id` is configured (otherwise, `app_id` is not set):

> Status code: `200 OK`
```json
{ "block_num": 89, "confidence": 93.75, "app_id": 1 }
```

If there are no processed blocks:

> Status code: `404 Not Found`
```json
"Not found"
```
API V1 reference can be found in the [V1 README file](src/api/v1/README.md).

## Test Code Coverage Report

Expand Down
Loading

0 comments on commit ff146b5

Please sign in to comment.