nuthatch

Nests · hosted

Ethereum address history partitions

nestsss / address-history/v1/1/ · ethereum

A nest that serves an account's history to portfolio apps such as rotki needs every block header and every withdrawal on the chain, whichever accounts it watches. That part is the same for everyone and says nothing about anyone, so we build it once and publish it. Your nest reads it, checks it against your own RPC, and keeps the accounts to itself.

statusavailable
coverageEthereum mainnet from the Shanghai upgrade (block 17,034,870) to the newest finalized 10,000-block span, extended hourly
partitions10,000 blocks per file, listed in manifest.json
public urlhttps://nestsss.nestsss-worker.workers.dev

What it is

Verified block partitions for Ethereum mainnet: full headers and withdrawals, 10,000 blocks to a file. A nest that tracks an account’s history reads them instead of fetching every header from its own RPC. Each partition holds the full headers and the withdrawals of its blocks, and manifest.json beside them lists every partition the mirror holds. It is published under nestsss / address-history/v1/1/.

https://nestsss.nestsss-worker.workers.dev

How a nest uses it

Add the mirror to the nest's nuthatch.toml, beside its [address_history] table. The nest derives each partition's name from its block range and fetches only those, never the manifest, and keeps what it has fetched within the cache budget.

nuthatch.toml
[address_history.mirror]
url = "https://nestsss.nestsss-worker.workers.dev"   # the mirror root; the nest adds address-history/v1/<chain>/
chain_id = 1
from_block = 17030000   # read from here, as far as the mirror has published
cache_mb = 2048         # local disk the fetched partitions may use

How it is verified

You do not have to trust us. Your nest checks every partition against your own RPC before it answers a single query from it:

  • Every header in a partition is hashed locally and must equal the hash the next header names as its parent, so a partition is one unbroken chain.
  • Each block’s withdrawals are checked against the withdrawalsRoot its header commits to.
  • The chain of headers is anchored to a finalized block your own RPC reports. A partition that does not link to it is refused, never served.

The mirror sees what any file server sees: your IP address and which block ranges you asked for. It never sees an address. The accounts you watch stay in your nest, on your machine.

What it answers

These are the Etherscan-shaped actions a nest serves at GET /api from the partitions:

  • block/getblocknobytime: the block closest before or after a timestamp, from the headers.
  • account/txsBeaconWithdrawal: validator withdrawals to an address, from the block bodies (EIP-4895).
  • account/getminedblocks: the blocks an address produced as fee recipient, from the headers.

Tell your agent this

Paste it into Claude Code, Cursor or any coding agent setting up the nest.

prompt
Ethereum address history partitions is a hosted, address-free dataset from nuthatch:
Ethereum mainnet from the Shanghai upgrade (block 17,034,870) to the newest finalized 10,000-block span, extended hourly, 10,000 blocks per file, listed in manifest.json.
It is published at https://nestsss.nestsss-worker.workers.dev

To use it, add this table to the address-history nest's nuthatch.toml:

[address_history.mirror]
url = "https://nestsss.nestsss-worker.workers.dev"   # the mirror root; the nest adds address-history/v1/<chain>/
chain_id = 1
from_block = 17030000   # read from here, as far as the mirror has published
cache_mb = 2048         # local disk the fetched partitions may use

The nest verifies every partition against its own RPC before using it: header hashes and parent
links, each block's withdrawalsRoot, and a link to a finalized block. The mirror never sees an address.
It feeds these Etherscan-shaped actions on the nest's GET /api: block/getblocknobytime, account/txsBeaconWithdrawal, account/getminedblocks.

Limits

  • Ethereum mainnet only, and only from the Shanghai upgrade: blocks before it carry no withdrawals.
  • No uptime promise, no account and no key. A partition is only ever an input your nest checks; nothing in it is served unverified.
  • It holds headers and withdrawals only. An account’s transactions, transfers and traces are found by your nest, against your RPC, and are never hosted.

The design and the record are in nuthatch-org/nuthatch/blob/main/docs/rfcs/0063-address-history.md.