Crate alloy_flashblocks

Expand description

§Alloy Flashblocks

Stream Base L2 flashblocks and query preconfirmation state using Alloy.

Flashblocks are ~200ms preconfirmations on Base. Instead of waiting ~2 seconds for block finalization, you get transaction feedback in ~200ms.

§Installation

[dependencies]
alloy-flashblocks = "0.1.0"

§Features

This crate provides the FlashblocksProviderExt extension trait with:

Streaming: watch_flashblocks() - stream pending block updates
State queries: Query balances, nonces, simulate calls against flashblock state
Preconfirmation helpers: Wait for transaction preconfirmation (~200ms feedback)

§Usage

§Stream Flashblocks

use alloy::providers::ProviderBuilder;
use alloy_flashblocks::FlashblocksProviderExt;
use futures_util::StreamExt;

let provider = ProviderBuilder::new()
    .connect_http("https://mainnet-preconf.base.org".parse()?);

let mut stream = provider.watch_flashblocks().into_stream();

while let Some(block) = stream.next().await {
    println!("Block {} | {} txs", block.header.number, block.transactions.len());
}

§Query Flashblock State

Query balances, nonces, and simulate calls against the current flashblock state (including preconfirmed transactions):

use alloy::providers::ProviderBuilder;
use alloy_flashblocks::FlashblocksProviderExt;

let provider = ProviderBuilder::new()
    .connect_http("https://mainnet-preconf.base.org".parse()?);

// Get current flashblock
let block = provider.flashblock().await?;

// Query balance including preconfirmed txs
let balance = provider.flashblock_balance(address).await?;

// Query nonce for next tx (accounts for pending txs)
let nonce = provider.flashblock_nonce(address).await?;

// Simulate a call against flashblock state
let result = provider.flashblock_call(&tx).await?;

// Estimate gas against flashblock state
let gas = provider.flashblock_estimate_gas(&tx).await?;

// Get logs up to flashblock
let logs = provider.flashblock_logs(filter).await?;

§Wait for Preconfirmation

Get ~200ms feedback on transaction inclusion instead of waiting ~2s for block finalization:

use alloy::providers::ProviderBuilder;
use alloy_flashblocks::FlashblocksProviderExt;

let provider = ProviderBuilder::new()
    .wallet(wallet)
    .connect_http("https://sepolia-preconf.base.org".parse()?);

// Send transaction
let pending = provider.send_transaction(tx).await?;
let tx_hash = *pending.tx_hash();

// Wait for preconfirmation (~200ms)
let receipt = provider.wait_for_preconfirmation(tx_hash).await?;
println!("Preconfirmed! Status: {:?}", receipt.status());

// Or just check if preconfirmed
let is_preconf = provider.is_preconfirmed(tx_hash).await?;

§RPC Endpoints

Network	Endpoint
Base Mainnet	`https://mainnet-preconf.base.org`
Base Sepolia	`https://sepolia-preconf.base.org`

§API Reference

§Streaming

Method	Description
`watch_flashblocks()`	Stream pending block updates (polls every 120ms)

§State Queries

All methods query against pending/flashblock state:

Method	Description
`flashblock()`	Get current flashblock
`flashblock_balance(addr)`	Balance including preconfirmed txs
`flashblock_nonce(addr)`	Nonce for sending next tx
`flashblock_call(&tx)`	Simulate call against flashblock state
`flashblock_estimate_gas(&tx)`	Gas estimate against flashblock
`flashblock_logs(filter)`	Logs up to flashblock
`flashblock_simulate(&payload)`	Multi-call simulation

§Preconfirmation Helpers

Method	Description
`wait_for_preconfirmation(tx_hash)`	Poll until tx is preconfirmed
`is_preconfirmed(tx_hash)`	Check if tx has receipt

§How It Works

The poller calls eth_getBlockByNumber("pending") every 120ms against a flashblocks-enabled RPC endpoint and yields new blocks when the block hash changes.

Base’s sequencer emits flashblocks every ~200ms, providing near-instant preconfirmation of transaction inclusion.

§License

MIT

§Credits

Structs§

Filter: Filter for logs.
FlashblockPoller: Polls for pending block updates via JSON-RPC.
Log: Ethereum Log emitted by a transaction

Constants§

FLASHBLOCK_INTERVAL: Flashblock emission interval (~200ms on Base).
POLL_INTERVAL: Poll interval (0.6 × flashblock interval, following Alloy convention).
PRECONF_POLL_INTERVAL: Preconfirmation polling interval (50ms for responsive feedback).

Traits§

FlashblocksProviderExt: Extension trait for streaming Base flashblocks and querying flashblock state.