(LEE-nee)
≡

Inside leani

What processors make of each block, what a node keeps on disk, and exactly which Ethereum RPC methods it answers.

# Processors do the work

A processor is a deterministic map/reduce over blocks, transactions, receipts, and logs. Configure a built-in, or write your own in Rust or Wasm. Each example shows a configuration, the data it extracts, and the change stream your app reads.

[[processors]]id = "blobs-money"instance = "blobs-production"version = "1.7.0"history_mode = "on_demand"start_block = 19426589 # Dencun[processors.state]mode = "checkpointed"[processors.artifacts]mode = "none"[processors.output]mode = "full"[processors.delivery]mode = "window"[processors.checkpoint]mode = "automatic"keep = 3[processors.undo]mode = "unfinalized"safety_blocks = 256
block: { … };
blobBaseFee: string;blobCount: number;blobEthBurnedWei: string;blobGasUsed: string;blockHash: Hex;blockNumber: number;excessBlobGas: string;executionBaseFee: string;executionEthBurnedWei: string;finality: "unattested" | "attested" | "finalized";gasLimit: string;gasUsed: string;maxBlobsPerBlock: number;network: string;parentHash: Hex;reserveFeeWei: string;size: string;targetBlobsPerBlock: number;timestamp: number;transactionCount: number;transformVersion: number;
transactions: { … }[];
blobBurnedWei: string;blobCount: number;blobVersionedHashes: Hex[];blockHash: Hex;blockNumber: number;executionBurnedWei: string;network: string;senderAddress: Hex;tipWei: string;toAddress: Hex;totalBurnedWei: string;transactionIndex: number;txHash: Hex;
GET /v1/processors/blobs-production/streamevent: hello
{ … }
apiVersion"1"
chainId1
coverage{ … }
available[ 1 ]
0{ … }
finality"finalized"
fromBlock19430000
toBlock19430000
chainId1
completefalse
configuredStartBlock19426589
finalizedThrough19430000
processedThrough19430000
requestednull
state"backfilling"
processor{ … }
artifactRetention"none"
changeSchema"blobs.block-bundle.v1"
codeHash"0xa73d707082575446ce0e135f10b76a72ed4ccf0db3ac12c1de4a88e342383399"
configHash"0x8ea21cedc162b4fa3edf143b115e0d3a87c8c958be74e0b1a61ebf8fb53bfa9f"
deliveryOrdering"block_versioned_idempotent"
genericApi"processor-v1"
id"blobs-money"
instance"blobs-production"
queryExtensions[ 1 ]
0{ … }
aliasPath"/v1/q/blobs"
basePath"/v1/processors/blobs-production/query"
id"blobs-v1"
subscriptionstrue
version"1.7.0"
id: 02000000000000000000000000000000000110626c6f62732d70726f64756374696f6e05312e372e3001acb2343419b7c2ee3d141864e0327680event: apply
data{ … }
apiVersion"1"
block{ … }
hash"0x460f4c111c4a3634fa3c26d429e51fe9a9326e12a138788e5226038ce5334f47"
number19430000
parentHash"0x40a4b2e74ae938e20245ac697051f964b2308191ff0e1d65fb8f40803a084ab0"
timestamp1710500000
chainId1
cursor"02000000000000000000000000000000000110626c6f62732d70726f64756374696f6e05312e372e3001acb2343419b7c2ee3d141864e0327680"
data{ … }
block{ … }
blobBaseFee"1"
blobCount3
blobEthBurnedWei"393216"
blobGasUsed"393216"
blockHash"0x460f4c111c4a3634fa3c26d429e51fe9a9326e12a138788e5226038ce5334f47"
blockNumber19430000
excessBlobGas"0"
executionBaseFee"10000000000"
executionEthBurnedWei"210000000000000"
finality"finalized"
gasLimit"30000000"
gasUsed"21000"
maxBlobsPerBlock6
network"mainnet"
parentHash"0x40a4b2e74ae938e20245ac697051f964b2308191ff0e1d65fb8f40803a084ab0"
reserveFeeWeinull
size"1024"
targetBlobsPerBlock3
timestamp1710500000
transactionCount1
transformVersion5
transactions[ 1 ]
0{ … }
blobBurnedWei"393216"
blobCount3
blobVersionedHashes[ 3 ]
0"0xa89b09021100e6907075c37e14644d808b64e574b20380c31478533d616640d3"
1"0x7467efe5108e92e2b5965492adb8ca767497c2db4ee1ca6d7f68fbfe29bd17da"
2"0x75c3af1ba7c574c1fd68fb4a020f8752ab8b65c819bb830dc8a5d32fc257feb3"
blockHash"0x460f4c111c4a3634fa3c26d429e51fe9a9326e12a138788e5226038ce5334f47"
blockNumber19430000
executionBurnedWei"210000000000000"
network"mainnet"
senderAddress"0x1111111111111111111111111111111111111111"
tipWei"42000000000000"
toAddress"0x2222222222222222222222222222222222222222"
totalBurnedWei"210000000393216"
transactionIndex0
txHash"0x3bbf7db04ef26a674e8e95b3186b58905153f80b22fbd9ed92eaeda6012e7369"
emittedAt"2024-03-15T10:53:20.000Z"
finality"finalized"
key"0x0000000001287a70"
kind"blobs.block.put"
operation"apply"
originId"illustrative-fixture"
originKind"historical_backfill"
publicationRevision"0"
schema"blobs.block-bundle.v1"
sequence"1"

One atomic block bundle—economics plus every blob transaction. Node commits are atomic; consumers receive at-least-once and commit their cursor before ACK.see it live →docs →

[[processors]]id = "erc20-balances"instance = "erc20-watchlist"version = "1.1.0"history_mode = "on_demand"start_block = 1234567[processors.state]mode = "durable"[processors.artifacts]mode = "none"[processors.output]mode = "latest"[processors.delivery]mode = "window"[processors.checkpoint]mode = "automatic"keep = 3[processors.undo]mode = "unfinalized"safety_blocks = 256[processors.settings]addresses = ["0x1111111111111111111111111111111111111111"]tokens = ["0x2222222222222222222222222222222222222222"]complete_from_start = true
token: Hex;address: Hex;balance: string;asOfBlock: number;blockHash: Hex;finality: "unattested" | "attested" | "finalized";coverageFrom: number;complete: boolean;incompleteFrom: number | null;method: "erc20_transfer_ledger";
GET /v1/processors/erc20-watchlist/streamevent: hello
{ … }
apiVersion"1"
chainId1
coverage{ … }
available[ 1 ]
0{ … }
finality"finalized"
fromBlock19430000
toBlock19430000
chainId1
completefalse
configuredStartBlock1234567
finalizedThrough19430000
processedThrough19430000
requestednull
state"live"
processor{ … }
artifactRetention"none"
changeSchema"erc20.balance.change.v2"
codeHash"0x95c5f9ba233dad3921f35b4b78a87b7ddfa4a4d1b46ef5c8c3ede33f7909df24"
configHash"0x286fc393037f30bc3360400281755f19a6741292e7585e781a4294c02facb8ac"
deliveryOrdering"canonical"
genericApi"processor-v1"
id"erc20-balances"
instance"erc20-watchlist"
queryExtensions[ 1 ]
0{ … }
aliasPath"/v1/q/erc20"
basePath"/v1/processors/erc20-watchlist/query"
id"erc20-v1"
subscriptionstrue
version"1.1.0"
id: 0200000000000000000000000000000000010f65726332302d77617463686c69737405312e312e300123f9aa31b9230edace91ab4139f4aa20event: apply
data{ … }
apiVersion"1"
block{ … }
hash"0x8a707419475207771c1004663d7510f330100ca73e206cc3c9bf51e0cef7c0b7"
number19430000
parentHash"0x5c68562e249e87eee7f656b04177dd585413adf9d3e1cb09f67420223e928e41"
timestamp1710500000
chainId1
cursor"0200000000000000000000000000000000010f65726332302d77617463686c69737405312e312e300123f9aa31b9230edace91ab4139f4aa20"
data{ … }
address"0x1111111111111111111111111111111111111111"
asOfBlock19430000
balance"42"
blockHash"0x8a707419475207771c1004663d7510f330100ca73e206cc3c9bf51e0cef7c0b7"
completetrue
coverageFrom1234567
finality"finalized"
incompleteFromnull
method"erc20_transfer_ledger"
token"0x2222222222222222222222222222222222222222"
emittedAt"2024-03-15T10:53:20.000Z"
finality"finalized"
key"0x22222222222222222222222222222222222222221111111111111111111111111111111111111111"
kind"erc20.balance.put"
operation"apply"
originId"illustrative-fixture"
originKind"historical_backfill"
publicationRevision"0"
schema"erc20.balance.change.v2"
sequence"1"

Event-derived watchlist balances with declared coverage. Exact for conventional Transfer semantics when indexing begins before the relevant initial mint; rebasing, reflection, and non-standard tokens need a different model.docs →

[[processors]]id = "evm-events"instance = "weth-transfers"version = "1.1.0"history_mode = "on_demand"start_block = 12965000publish = "finalized"[processors.state]mode = "durable"[processors.artifacts]mode = "none"[processors.output]mode = "window"[processors.output.window]max_blocks = 216000[processors.delivery]mode = "window"[processors.checkpoint]mode = "automatic"keep = 3[processors.undo]mode = "none"safety_blocks = 0[processors.settings]addresses = ["0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"][[processors.settings.events]]abi = "event Transfer(address indexed from, address indexed to, uint256 value)"[processors.settings.events.output]collection = "weth.transfers"kind = "weth.transfer"key_fields = []
schemaVersion: number;contract: Hex;event: string;signature: string;blockNumber: number;blockHash: Hex;blockTimestamp: number;bucketStartTimestamp?: number;transactionHash: Hex;transactionIndex: number;logIndex: number;finality: "unattested" | "attested" | "finalized";values: Record<string, string>;
GET /v1/processors/weth-transfers/streamevent: hello
{ … }
apiVersion"1"
chainId1
coverage{ … }
available[ 1 ]
0{ … }
finality"finalized"
fromBlock19430000
toBlock19430000
chainId1
completefalse
configuredStartBlock12965000
finalizedThrough19430000
processedThrough19430000
requestednull
state"live"
processor{ … }
artifactRetention"none"
changeSchema"evm.event.change.v1"
codeHash"0x199e2ddc101664d483c7dd6c993e0d18264a86a4ee6d9a2f9ad384f8828307cf"
configHash"0x38b6203c8ca408c1a00aa1fb528d2bc33ae3c59559d6259007a4aa75c06eedbd"
deliveryOrdering"block_versioned_idempotent"
genericApi"processor-v1"
id"evm-events"
instance"weth-transfers"
queryExtensions[ 0 ]
subscriptionstrue
version"1.1.0"
id: 0200000000000000000000000000000000010e776574682d7472616e736665727305312e312e3001c7ee528dcf5d34debea541858c10c414event: apply
data{ … }
apiVersion"1"
block{ … }
hash"0x8a707419475207771c1004663d7510f330100ca73e206cc3c9bf51e0cef7c0b7"
number19430000
parentHash"0x5c68562e249e87eee7f656b04177dd585413adf9d3e1cb09f67420223e928e41"
timestamp1710500000
chainId1
cursor"0200000000000000000000000000000000010e776574682d7472616e736665727305312e312e3001c7ee528dcf5d34debea541858c10c414"
data{ … }
blockHash"0x8a707419475207771c1004663d7510f330100ca73e206cc3c9bf51e0cef7c0b7"
blockNumber19430000
blockTimestamp1710500000
contract"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
event"Transfer"
finality"finalized"
logIndex0
schemaVersion1
signature"Transfer(address,address,uint256)"
transactionHash"0x3333333333333333333333333333333333333333333333333333333333333333"
transactionIndex0
values{ … }
from"0x0000000000000000000000000000000000000000"
to"0x1111111111111111111111111111111111111111"
value"42"
emittedAt"2024-03-15T10:53:20.000Z"
finality"finalized"
key"0x333333333333333333333333333333333333333333333333333333333333333300000000"
kind"weth.transfer.put"
operation"apply"
originId"illustrative-fixture"
originKind"historical_backfill"
publicationRevision"0"
schema"evm.event.change.v1"
sequence"1"

Declarative ABI decoding—no EVM or contract code, just logs. Tuples flatten to dotted keys, arrays arrive as JSON strings, and log0 stores topicless logs raw. Illustrative response; hashes, cursors, and values vary by run.docs →

[[processors]]id = "uniswap-latest"instance = "usdc-weth-latest"version = "2.0.0"history_mode = "on_demand"start_block = 12369621[processors.state]mode = "checkpointed"[processors.artifacts]mode = "none"[processors.output]mode = "latest"[processors.delivery]mode = "window"[processors.checkpoint]mode = "automatic"keep = 3[processors.undo]mode = "unfinalized"safety_blocks = 256[[processors.settings.pools]]address = "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640" # USDC/WETH 0.05%kind = "v3"
pool: Hex;kind: "v2" | "v3";reserve0: string | null;reserve1: string | null;amount0: string | null;amount1: string | null;sqrtPriceX96: string | null;blockNumber: number;blockHash: Hex;logIndex: number;finality: "unattested" | "attested" | "finalized";
GET /v1/processors/usdc-weth-latest/streamevent: hello
{ … }
apiVersion"1"
chainId1
coverage{ … }
available[ 1 ]
0{ … }
finality"finalized"
fromBlock19430000
toBlock19430000
chainId1
completefalse
configuredStartBlock12369621
finalizedThrough19430000
processedThrough19430000
requestednull
state"live"
processor{ … }
artifactRetention"none"
changeSchema"uniswap.price.change.v2"
codeHash"0x19adcbcc4e6750d9afce9dcd2065765351b78664115c96edd4cc11bfe64bb6cd"
configHash"0x7e2e584b40d5686f5dedfd8a75343d6e6da17984dd426d9bb5210be6c8ea027f"
deliveryOrdering"canonical"
genericApi"processor-v1"
id"uniswap-latest"
instance"usdc-weth-latest"
queryExtensions[ 1 ]
0{ … }
aliasPath"/v1/q/uniswap"
basePath"/v1/processors/usdc-weth-latest/query"
id"uniswap-v2"
subscriptionstrue
version"2.0.0"
id: 02000000000000000000000000000000000110757364632d776574682d6c617465737405322e302e3001d41d87c20935f657a418afd2d1dca5a4event: apply
data{ … }
apiVersion"1"
block{ … }
hash"0xc57158346aeb29a7d5777c0f61a9c51119d003e4c7eb9ab877096b19416bc0fe"
number19430000
parentHash"0xa46402fef3ac2bc0dc3c57c03810e91b9d77e63fa55a04f89509b11c255037b0"
timestamp1710500000
chainId1
cursor"02000000000000000000000000000000000110757364632d776574682d6c617465737405322e302e3001d41d87c20935f657a418afd2d1dca5a4"
data{ … }
amount0"0"
amount1"0"
blockHash"0xc57158346aeb29a7d5777c0f61a9c51119d003e4c7eb9ab877096b19416bc0fe"
blockNumber19430000
finality"finalized"
kind"v3"
logIndex0
pool"0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
reserve0null
reserve1null
sqrtPriceX96"83451394949906432"
emittedAt"2024-03-15T10:53:20.000Z"
finality"finalized"
key"0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
kind"uniswap.price.current.put"
operation"apply"
originId"illustrative-fixture"
originKind"historical_backfill"
publicationRevision"0"
schema"uniswap.price.change.v2"
sequence"1"

Latest exact reserves or sqrtPriceX96 per configured pool—never floating point, no EVM execution. Use uniswap-observations when you need immutable history.docs →

[[processors]]id = "transaction-stats"instance = "treasury-flow-total"version = "1.0.0"history_mode = "on_demand"start_block = 15537394publish = "finalized"[processors.state]mode = "checkpointed"[processors.artifacts]mode = "none"[processors.output]mode = "latest"[processors.delivery]mode = "window"[processors.checkpoint]mode = "automatic"keep = 3[processors.undo]mode = "none"safety_blocks = 0[processors.settings]from = "0x1111111111111111111111111111111111111111"to = "0x2222222222222222222222222222222222222222"complete_from_start = true
from: Hex;to: Hex;count: number;totalValueWei: string;asOfBlock: number;blockHash: Hex;finality: "unattested" | "attested" | "finalized";coverageFrom: number;complete: boolean;
GET /v1/processors/treasury-flow-total/streamevent: hello
{ … }
apiVersion"1"
chainId1
coverage{ … }
available[ 1 ]
0{ … }
finality"finalized"
fromBlock19430000
toBlock19430000
chainId1
completefalse
configuredStartBlock15537394
finalizedThrough19430000
processedThrough19430000
requestednull
state"live"
processor{ … }
artifactRetention"none"
changeSchema"transaction-stats.change.v1"
codeHash"0x514a31147ba3ab85d34a1b30901b4797c546e4d41a3dc6714cd9f9549bef4083"
configHash"0x133645b81b6609362c18c66ac3b8be9a85be2c95e9d9af7e47c16ed63383fe95"
deliveryOrdering"canonical"
genericApi"processor-v1"
id"transaction-stats"
instance"treasury-flow-total"
queryExtensions[ 0 ]
subscriptionstrue
version"1.0.0"
id: 0200000000000000000000000000000000011374726561737572792d666c6f772d746f74616c05312e302e3001e242149dc5da6a11c9bd7c714c44c5b2event: apply
data{ … }
apiVersion"1"
block{ … }
hash"0x8a707419475207771c1004663d7510f330100ca73e206cc3c9bf51e0cef7c0b7"
number19430000
parentHash"0x5c68562e249e87eee7f656b04177dd585413adf9d3e1cb09f67420223e928e41"
timestamp1710500000
chainId1
cursor"0200000000000000000000000000000000011374726561737572792d666c6f772d746f74616c05312e302e3001e242149dc5da6a11c9bd7c714c44c5b2"
data{ … }
asOfBlock19430000
blockHash"0x8a707419475207771c1004663d7510f330100ca73e206cc3c9bf51e0cef7c0b7"
completetrue
count32
coverageFrom15537394
finality"finalized"
from"0x1111111111111111111111111111111111111111"
to"0x2222222222222222222222222222222222222222"
totalValueWei"73"
emittedAt"2024-03-15T10:53:20.000Z"
finality"finalized"
key"0x746f74616c"
kind"transaction_stats.aggregate.put"
operation"apply"
originId"illustrative-fixture"
originKind"historical_backfill"
publicationRevision"0"
schema"transaction-stats.change.v1"
sequence"1"

Ordered aggregate with constant-sized state for top-level A-to-B transactions. Internal calls and traces are intentionally outside this processor. Illustrative response; hashes, cursors, and values vary by run.docs →

#[tokio::main]async fn main() -> std::process::ExitCode { let mut registry = ProcessorRegistry::new(); if let Err(error) = registry.register(BlockSummaryFactory) { eprintln!("error: {error}"); return Exit::Failure.into(); } match run_with_registry(registry).await { Ok(exit) => exit.into(), Err(error) => { eprintln!("error: {error:#}"); Exit::Failure.into() } }}
blockNumber: number;timestamp: number;
import { createLeaniClient } from "@smart-byte/leani-sdk";interface BlockSummary { blockNumber: number; timestamp: number;}const leani = createLeaniClient({ baseUrl: "http://127.0.0.1:9080" });const capabilities = await leani.capabilities();const extension = capabilities.queryExtensions.find( (candidate) => candidate.processor === "example-block-summary-local",);if (!extension) throw new Error("block summary query extension is unavailable");const summary = await leani.request<BlockSummary>( `${extension.basePath}/19426589`,);console.log(summary);
GET /v1/processors/example-block-summary-local/streamevent: hello
{ … }
apiVersion"1"
chainId1
processor{ … }
id"example-block-summary"
instance"example-block-summary-local"
version"1.0.0"
codeHash"0x6b30c95e17daf4820b96e5c3a1f07d48e92b56013fc7da8e045a1b7cd6390f82"
configHash"0xf05c37b1ae92d6084e1bc79f52a3d80167c04de935ab26f1780c4e3b9a51d627"
genericApi"processor-v1"
changeSchema"example.block-summary.change.v1"
queryExtensions[ 1 ]
0{ … }
id"block-summary-v1"
basePath"/v1/processors/example-block-summary-local/query"
aliasPath"/v1/q/block-summaries"
subscriptionstrue
artifactRetention"none"
deliveryOrdering"block_versioned_idempotent"
coverage{ … }
chainId1
requestednull
available[ 1 ]
0{ … }
fromBlock25650000
toBlock25696396
finality"attested"
configuredStartBlock25650000
processedThrough25696396
finalizedThrough25696313
completetrue
state"live"
id: opaque-resume-cursorevent: apply
data{ … }
apiVersion"1"
sequence"46397"
cursor"opaque-resume-cursor"
operation"apply"
originKind"historical_backfill"
originId"example-block-summary-local"
publicationRevision"0"
chainId1
block{ … }
hash"0xc86f87600c81fb635325cca051fef40b875ca405d1b2f57881437963321e88ff"
number25696396
parentHash"0x0141a01b6e38f75cd3606834c3780f581d5772460e440e7c5758b69589929168"
timestamp1786025147
finality"attested"
kind"example.block_summary.put"
schema"example.block-summary.change.v1"
key"0x000000000188188c"
data{ … }
blockNumber25696396
timestamp1786025147
emittedAt"2026-08-06T14:05:51.502Z"

Native Rust processors register state transforms and typed read extensions through the public factory API — same durability, streams, coverage, and query controls as built-ins.build your own →docs →

# Storage is a policy, not a promise

State, query output, delivery, artifacts, checkpoints, undo, and raw history have independent lifecycle controls and hard budgets. Keep a current value, a rolling window, a reusable history, or only an acknowledged external copy.

PolicyRetained by leaniBoundBest fitExample
externalizedState, coverage, and delivery only until the required consumer ACKsByte/age budgets with pause-on-limit backpressurePostgreSQL, ClickHouse, object storage, or another application-owned sink1M real blocks: 9.5 MB blobs / 11.4 MB Uniswap peak node files
latest / aggregateCurrent entities or constant-sized ordered stateOutput cardinality plus checkpoints and configured undoBalances, pool state, counters, totals, dashboardsTransaction totals remain one current aggregate
windowOnly the selected block, age, row, or byte windowExplicit max_blocks / max_age / max_rows / max_bytesRecent APIs, rolling analytics, replay windows30-day event profile ships as a checked example
full outputEvery materialized processor entity and required indexesGrows with output cardinality and indexed historyReusable local historical query surfaces1M dev-native blobs blocks: 1.58 GiB compacted DB
  1. Measured figures are workload-specific evidence, not host-size or cost guarantees. The real-source runs used gzip HTTP delivery, immediate acknowledgement, four source workers, and did not include an application database.
  2. The 1.58 GiB full-output figure retained 2.55 million entities and 550,000 index rows. Externalized, latest, or windowed policy is the intended choice when that reusable query surface is unnecessary.
  3. Trusted Xatu input and commitment-checked EraE input have different trust and performance profiles; retention policy does not change source trust.

# An exact, capability-reported RPC subset

Existing Ethereum clients can use the block, transaction, receipt, log, chain-metadata, and subscription methods leani advertises. Availability still depends on configured sources, retained material, and hash locators.

implemented exactly, when available

  • eth_getBlockByNumber / ByHash
  • eth_getBlockTransactionCountByNumber / ByHash
  • eth_getTransactionByBlockNumberAndIndex / ByHashAndIndex
  • eth_getTransactionByHash / Receipt
  • eth_getBlockReceipts
  • eth_getLogs (recent, on-demand, or materialized)
  • eth_blockNumber · eth_chainId · eth_config · eth_syncing
  • web3_clientVersion · net_version
  • leani_getCapabilities
  • eth_subscribe: newHeads, logs (reorg-correct)

refused, explicitly

  • eth_call · eth_estimateGas
  • eth_getBalance · eth_getTransactionCount
  • eth_getCode · eth_getStorageAt
  • debug/trace methods

Number and range lookups can use historical sources; lookups by hash alone cover recent blocks unless a locator or retained index is enabled. With no EVM and no state trie, stateful methods fail explicitly instead of returning something almost right, so keep an execution provider for them. Every method’s behavior is in Ethereum JSON-RPC compatibility.

Next: the quickstart, or the docs.