DataAvailApi Runtime API

The DataAvailApi runtime API provides methods to query block-level data availability parameters, primarily the block matrix dimensions that determine how transaction data is arranged for erasure coding and Kate commitments.

Overview

Runtime APIs are different from RPC endpoints:

Runtime APIs vs RPC Endpoints

Runtime APIs execute inside the runtime (WebAssembly) and have direct access to the blockchain state. They are:

Compiled into the runtime binary
Execute deterministically on-chain
Access runtime storage directly
Called by the node client or RPC layer
Versioned with the runtime

RPC Endpoints run in the node client (native code) and provide:

Network communication interfaces
State queries and transaction submission
May call runtime APIs internally
Not part of consensus

API Definition

Defined in runtime/src/apis.rs:43-47:

#[api_version(2)]
pub trait DataAvailApi {
    fn block_length() -> BlockLength;
}

Methods

block_length

Returns the current block matrix dimensions and constraints.

fn block_length() -> BlockLength;

return

BlockLength

Block length configuration containing matrix dimensions and dispatch ratios.

Return Type: BlockLength

The BlockLength structure contains:

max

object

Maximum block length per dispatch class.

Show properties

normal

u32

Maximum bytes for normal (non-DA) transactions. Typically set to 100% of matrix capacity.

operational

u32

Maximum bytes for operational transactions (governance, staking).

mandatory

u32

Maximum bytes for mandatory transactions (inherents).

rows

BlockLengthRows

Number of rows in the data matrix. Must be a power of 2 between 32 and 1024.Default: 256 rows

cols

BlockLengthColumns

Number of columns in the data matrix. Must be a power of 2 between 32 and 1024.Default: 256 columns

chunk_size

u32

Size of each matrix cell in bytes.Always: 32 bytes (31 bytes usable for data to fit in scalar field)

Implementation

The implementation delegates to the frame system (runtime/src/apis.rs:392-396):

impl crate::apis::DataAvailApi<Block> for Runtime {
    fn block_length() -> frame_system::limits::BlockLength {
        frame_system::Pallet::<Runtime>::block_length()
    }
}

Usage Context

When to Use

Call block_length() when you need to:

Calculate Matrix Space: Determine how much data fits in a block
Validate Data Submissions: Check if data exceeds block capacity
Generate Kate Proofs: Build the erasure-coded matrix
Query Block Dimensions: Display current block configuration

Matrix Dimensions

The block matrix dimensions determine the data availability capacity:

Block Capacity (bytes) = rows × cols × 31 bytes × 90%
                         └──┬──┘  └─┬─┘  └──┬──┘   └─┬─┘
                          matrix  usable  chunk   DA ratio
                           size   data    size

DA Dispatch Ratio: Only 90% of matrix space is allocated for data availability transactions (submit_data). The remaining 10% is reserved for normal transactions to prevent DA transactions from blocking critical operations.

Example Calculations

Default (256×256)
Maximum (1024×1024)
Minimum (32×32)

Rows: 256
Cols: 256
Cells: 256 × 256 = 65,536

Total capacity: 65,536 × 31 bytes = 2,031,616 bytes (~2 MB)
DA capacity: 2,031,616 × 0.9 = 1,828,454 bytes (~1.8 MB)
Normal capacity: 2,031,616 × 1.0 = 2,031,616 bytes (~2 MB)

Rows: 1024
Cols: 1024
Cells: 1024 × 1024 = 1,048,576

Total capacity: 1,048,576 × 31 bytes = 32,505,856 bytes (~32 MB)
DA capacity: 32,505,856 × 0.9 = 29,255,270 bytes (~29 MB)
Normal capacity: 32,505,856 × 1.0 = 32,505,856 bytes (~32 MB)

Rows: 32
Cols: 32
Cells: 32 × 32 = 1,024

Total capacity: 1,024 × 31 bytes = 31,744 bytes (~31 KB)
DA capacity: 31,744 × 0.9 = 28,570 bytes (~28 KB)
Normal capacity: 31,744 × 1.0 = 31,744 bytes (~31 KB)

Dynamic Block Length

Block dimensions can be adjusted via governance using the da_control::submit_block_length_proposal dispatchable function.

Adjustment Process

Submit Proposal

Root origin (governance) calls submit_block_length_proposal(rows, cols)

pub fn submit_block_length_proposal(
    origin: OriginFor<T>,
    rows: u32,
    cols: u32,
) -> DispatchResultWithPostInfo

Validate Dimensions

Ensures dimensions are:

Powers of 2
Within bounds (32-1024 for both rows and cols)
Supported by the Kate commitment system

Update Configuration

Updates DynamicBlockLength storage, which takes effect for subsequent blocks.

Constraints

Dimensions must be powers of 2 for efficient FFT (Fast Fourier Transform) operations during polynomial interpolation for Kate commitments.

// Defined in runtime/src/constants.rs
pub const MinBlockRows: BlockLengthRows = BlockLengthRows(32);
pub const MaxBlockRows: BlockLengthRows = BlockLengthRows(1024);
pub const MinBlockCols: BlockLengthColumns = BlockLengthColumns(32);
pub const MaxBlockCols: BlockLengthColumns = BlockLengthColumns(1024);

Code Example

Calling the runtime API from Rust client code:

use sp_api::ProvideRuntimeApi;
use avail_runtime::DataAvailApi;

let api = client.runtime_api();
let block_hash = client.info().best_hash;

// Query block length
let block_length = api.block_length(block_hash)?;

println!("Block dimensions: {}×{}", 
    block_length.rows.0, 
    block_length.cols.0
);

let total_cells = block_length.rows.0 * block_length.cols.0;
let capacity_bytes = total_cells * 31; // 31 usable bytes per cell

println!("Block capacity: {} bytes", capacity_bytes);
println!("DA capacity: {} bytes", 
    capacity_bytes * 90 / 100
);

KateApi

Generate Kate commitments and data availability proofs using block dimensions.

Kate RPC

RPC endpoints for querying Kate proofs and data availability information.

Data Availability

Learn how the matrix dimensions relate to erasure coding and Kate commitments.

Runtime Architecture

Understanding the da_control pallet and block length configuration.

API Version History

Version 2 (Current)

Current version: 2

No changes from version 1
Marked with #[api_version(2)] in source

The API version is incremented when the runtime API signature changes. Clients should check the API version to ensure compatibility.

Kate RPC

Runtime APIs

CLI Reference

DataAvailApi Runtime API

Overview

API Definition

Methods

block_length

Return Type: BlockLength

Implementation

Usage Context

When to Use

Matrix Dimensions

Example Calculations

Dynamic Block Length

Adjustment Process

Constraints

Code Example

KateApi

Kate RPC

Data Availability

Runtime Architecture

API Version History

Build docs developers (and LLMs) love

Kate RPC

Runtime APIs

CLI Reference

​Overview

​API Definition

​Methods

​block_length

​Return Type: BlockLength

​Implementation

​Usage Context

​When to Use

​Matrix Dimensions

​Example Calculations

​Dynamic Block Length

​Adjustment Process

​Constraints

​Code Example

​Related APIs

KateApi

Kate RPC

Data Availability

Runtime Architecture

​API Version History

Build docs developers (and LLMs) love

Overview

API Definition

Methods

block_length

Return Type: BlockLength

Implementation

Usage Context

When to Use

Matrix Dimensions

Example Calculations

Dynamic Block Length

Adjustment Process

Constraints

Code Example

Related APIs

API Version History