Read Ethereum block metadata as an ordered stream, the starting point for a block monitor or a pipeline that processes each block. This guide streams a short finite range so you can inspect the output, then shows how to keep following the chain.
Prerequisites
- A Substreams API key.
- The Substreams CLI, or a standard Substreams client library for Go, Rust, or TypeScript.
Stream a block range
Run map_block_meta from the pinned ethereum-explorer package against the Ethereum mainnet
endpoint. The CLI tab is a complete command. The Go, Rust, and TypeScript tabs show the values a
standard Substreams client library needs; generate the package's Protobuf types before you decode
messages.
export SUBSTREAMS_API_KEY="<GRAPHOPS_API_KEY>"
substreams run \
-e "https://1.evm.substreams.graphops.xyz" \
"https://github.com/streamingfast/substreams-explorers/releases/download/v1.0.1/ethereum-explorer-v0.1.2.spkg" \
"map_block_meta" \
--start-block 18000000 \
--stop-block +5 \
-o jsonconst endpoint = "https://1.evm.substreams.graphops.xyz"
const packageRef = "https://github.com/streamingfast/substreams-explorers/releases/download/v1.0.1/ethereum-explorer-v0.1.2.spkg"
const moduleName = "map_block_meta"
const startBlock = 18000000
const stopBlock = "+5"
func main() {
headers := map[string]string{
"x-api-key": "<GRAPHOPS_API_KEY>",
}
// Use a standard Substreams Go client or sinker with these values.
// Commit each block output, then persist the returned cursor.
_ = headers
}const ENDPOINT: &str = "https://1.evm.substreams.graphops.xyz";
const PACKAGE_REF: &str = "https://github.com/streamingfast/substreams-explorers/releases/download/v1.0.1/ethereum-explorer-v0.1.2.spkg";
const MODULE_NAME: &str = "map_block_meta";
const START_BLOCK: i64 = 18_000_000;
const STOP_BLOCK: &str = "+5";
const X_API_KEY: &str = "<GRAPHOPS_API_KEY>";
// Use a standard Substreams Rust client with these values.
// Persist the cursor only after the block output is durably committed.const streamConfig = {
endpoint: "https://1.evm.substreams.graphops.xyz",
packageRef: "https://github.com/streamingfast/substreams-explorers/releases/download/v1.0.1/ethereum-explorer-v0.1.2.spkg",
moduleName: "map_block_meta",
startBlock: 18_000_000,
stopBlock: "+5",
headers: {
"x-api-key": "<GRAPHOPS_API_KEY>",
},
};
// Use a standard Substreams TypeScript client with this config.
// Persist the cursor only after the block output is durably committed.
console.log(streamConfig);Read the output
The CLI prints one message per block. This illustrative excerpt shows the JSON envelope, with the
module's fields inside @data:
{
"@module": "map_block_meta",
"@block": 18000000,
"@type": "eth.block_meta.v1.BlockMeta",
"@data": {
"number": "18000000",
"hash": "…"
}
}@blockis the block the message covers. Messages arrive in block order.@typenames the Protobuf message to decode in a client library.@dataholds the module output; this module returns block metadata such as number and hash.
Follow the chain
To keep streaming as new blocks arrive, omit --stop-block. Start from the block your application
needs, and save each block's cursor after you commit its output so you can resume after a
disconnect.
Before you write to durable state, pin the package version and read Cursors and reorgs: blocks near the chain head can be replaced.