Enum Sub 

pub enum Sub {
    UnInit(UnInitSub),
    BestBlock(BestBlockSub),
    FinalizedBlock(FinalizedBlockSub),
}

The Sub subscription behaves as follows by default:

Defaults

• Tracks finalized blocks.
  → To track best (non-finalized) blocks instead, call: sub.use_best_block(true)
• Starts from the latest finalized (or best) block.
  → To start from a specific height, call: sub.set_block_height(height)
• Retries failed RPC calls automatically.
  → To disable retries, call: sub.set_retry_on_error(false)
• Polls for new block information every 3 seconds.
  → To change the interval, call: sub.set_pool_rate(Duration)

Fetching methods

• sub.next() → Returns the next block reference (hash, height).
  • If you’ve already fetched a block, this moves forward.
  • If you set a starting height, it begins from there.
  • Otherwise, it starts at the latest finalized (or best) block.
• sub.prev() → Returns the previous block reference (hash, height).
  • If you set a starting height, it begins from (height - 1).
  • Otherwise, it starts from (latest finalized/best height - 1).

State

• The initial state is UnInit.
• After the first call to next() or prev(), the state changes to either:
  • FinalizedBlock (default), or
  • BestBlock (if sub.use_best_block(true) was called).
• Once initialized, calling use_best_block(...) has no effect.

Example

use avail_rust_client::prelude::*;

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), Error> {
	let client = Client::new(TURING_ENDPOINT).await?;

	// Fetching latest finalized block (hash, height)
	let mut sub = Sub::new(client.clone());
	let finalized_height = client.finalized().block_height().await?;
	let next = sub.next().await?;
	assert_eq!(next.height, finalized_height);

	// Fetching block (hash, height) for a specific height
	sub.set_block_height(190010);
	let next = sub.next().await?;
	assert_eq!(next.height, 190010);

	// Fetching previous one
	sub.set_block_height(190010);
	let previous = sub.prev().await?;
	assert_eq!(previous.height, 190009);

	Ok(())
}

Variants

UnInit(UnInitSub)

BestBlock(BestBlockSub)

FinalizedBlock(FinalizedBlockSub)

Implementations

impl Sub

pub fn new(client: Client) -> Self

Creates a new lazy subscription using the provided client.

pub async fn next(&mut self) -> Result<BlockInfo, RpcError>

Returns the next block reference (hash, height).

• If you’ve already called Sub::next or Sub::prev once, this moves forward.
• If you set a starting height via Sub::set_block_height, it begins from there.
• Otherwise, it starts at the latest finalized (or best) block depending on Sub::use_best_block.

Errors

Returns Err(RpcError) when the underlying RPC requests fail; the internal cursor remains unchanged so the next call can retry.

pub async fn prev(&mut self) -> Result<BlockInfo, RpcError>

Returns the previous block reference (hash, height).

• If you’ve already called Sub::next or Sub::prev once, this moves backwards.
• If you set a starting height via Sub::set_block_height, it begins from (height - 1).
• Otherwise, it starts from (latest finalized/best height - 1).

Errors

Returns Err(RpcError) when the underlying RPC interaction fails; the cursor is left at the same position so the call can be retried.

pub fn should_retry_on_error(&self) -> bool

Returns true when RPC calls should be retried after failures.

The decision honors any explicit override configured via Sub::set_retry_on_error and falls back to the client’s default retry policy when no override is provided.

pub fn use_best_block(&mut self, value: bool)

Switches the subscription mode based on value.

• true → Track best (non-finalized) blocks instead of finalized ones.
• false → Stick with the default of finalized blocks.

This configuration must be applied before the subscription is initialized by a call to Sub::next or Sub::prev; later calls have no effect.

pub fn set_block_height(&mut self, value: u32)

Sets the starting block height according to value.

Subsequent calls to Sub::next and Sub::prev honour this height, rewinding or fast-forwarding the internal cursor so iteration resumes relative to value.

pub fn set_pool_rate(&mut self, value: Duration)

Updates the polling interval using the provided value.

The change takes effect immediately and drives how often the subscription waits before attempting to fetch fresh block data.

pub fn set_retry_on_error(&mut self, value: Option<bool>)

Controls retry behaviour for this subscription based on value.

• Some(true) → Always retry failed RPC calls.
• Some(false) → Never retry failed RPC calls.
• None → Defer to the Client’s global retry setting.

Trait Implementations

impl Clone for Sub

fn clone(&self) -> Sub

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.