From d18a0e67c2ed01cf2664ec781ae92e5150be16e0 Mon Sep 17 00:00:00 2001 From: neriumpete Date: Sat, 10 Oct 2026 16:48:05 +0300 Subject: [PATCH 1/5] docs: describe using a Nuthatch nest as an indexer --- usage-guides/quick-start.md | 2 +- usage-guides/settings/blockchain.md | 18 ++++++++++++++++++ 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/usage-guides/quick-start.md b/usage-guides/quick-start.md index 88d8c377..cd2c235b 100644 --- a/usage-guides/quick-start.md +++ b/usage-guides/quick-start.md @@ -39,7 +39,7 @@ Before adding accounts, set up a few things to make account detection and balanc - **Etherscan API Key** — Free and significantly speeds up EVM queries (and is required for some chains like Binance Smart Chain). Go to **API Keys → External Services** and add your key. See [External Services](/usage-guides/integrations/external-services#etherscan). - **Custom RPC Nodes** — Add your own RPC endpoints (e.g., from Alchemy or Infura) for faster blockchain queries. Configure in **Settings → RPC Nodes**. See [RPC Node Settings](/usage-guides/settings/blockchain#rpc-node-setting). -- **Indexer Configuration** — Adjust the order of indexers (Etherscan, Blockscout, Routescan) per chain for optimal performance. See [Indexers](/usage-guides/settings/blockchain#indexers). +- **Indexer Configuration** — Adjust the order of indexers (Etherscan, Blockscout, Routescan, or a self-hosted Nuthatch nest) per chain for optimal performance. See [Indexers](/usage-guides/settings/blockchain#indexers). > [!TIP] > At minimum, we strongly recommend adding a free Etherscan API key **before** adding your blockchain accounts. Without it, EVM queries and token detection will be significantly slower. diff --git a/usage-guides/settings/blockchain.md b/usage-guides/settings/blockchain.md index aa5e09fb..6b445858 100644 --- a/usage-guides/settings/blockchain.md +++ b/usage-guides/settings/blockchain.md @@ -50,6 +50,7 @@ No indexer covers every chain, and each has its own key requirement: | **Etherscan** | Required, even on the free tier. One key covers every chain it serves | Most EVM chains, but **not** Scroll. Gnosis and Binance SC only on **paid** plans | | **Blockscout** | Required. The multichain endpoints reject keyless requests. One key covers every chain it serves. **Exception:** Hyperliquid is served through a free public instance and needs no key | Ethereum, Optimism, Polygon PoS, Arbitrum One, Base, Gnosis, Scroll, Hyperliquid | | **Routescan** | Not required | Ethereum and Optimism only | +| **Nuthatch** | Not required. A nest you run yourself, see [Using a Nuthatch nest](#using-a-nuthatch-nest) | The chain the nest indexes | rotki caps its own Blockscout traffic at 10 requests per second, so parallel chain refreshes do not overwhelm the endpoint. @@ -62,6 +63,19 @@ Which means, in practice: - **Scroll** needs a **Blockscout key**, since Etherscan no longer serves Scroll and Routescan does not cover it. - **Binance SC** needs a **paid Etherscan plan**, since it is the only indexer that serves the chain. +### Using a Nuthatch nest + +A [Nuthatch](https://nuthatch-indexer.com) nest is an indexer you run yourself, against your own RPC node, so your addresses never leave your machine. A nest in rotki mode serves your tracked accounts' transactions, internal transactions, token transfers, ETH withdrawals and produced blocks (with their MEV rewards) in the same format rotki reads from Etherscan. How to install and run one is covered in [Nuthatch's documentation](https://nuthatch-indexer.com). + +To use a nest: + +1. Set its address under **Settings → RPC Nodes → Nuthatch nest**. By default rotki expects it at `http://127.0.0.1:8288`, where a nest listens unless told otherwise. +2. Add **Nuthatch** to the indexer order of the chain the nest indexes, first if you want it asked before the others. + +Once Nuthatch is in a chain's order, rotki registers the addresses you track on that chain with the nest, and adds or removes them as you add or remove accounts. If the nest is not running, adding an account still works and rotki registers it the next time it can. + +A nest answers only what it has fully indexed. Anything else, such as a block range it has not reached yet, is refused rather than answered with an empty list, and rotki asks the next indexer in the order instead. For produced blocks, rotki still queries beaconcha.in after the nest when you have a beaconcha.in API key, so a block the nest could not attribute to a validator is still found. + ### Suppressing indexer notifications When a chain has no usable indexer, rotki raises a **"No indexers available"** notification for it. @@ -149,6 +163,10 @@ Set the RPC endpoint for a Polkadot node here. Set the RPC endpoint for the Ethereum consensus layer beacon node. If unreachable, beaconcha.in will be used. For DAppNode Ethereum validator users, find the RPC node setting in the DAppNode Package for the Execution Client. +#### Connecting to a Nuthatch nest + +Set the address of a [Nuthatch nest](#using-a-nuthatch-nest) you run, for example `http://127.0.0.1:8288`. It is only queried on chains whose indexer order includes Nuthatch. + #### Connecting to a Bitcoin Mempool instance A local Bitcoin node can be used to query balances and transactions via [Mempool](https://mempool.space)'s API. [Mempool](https://github.com/mempool/mempool) is an open source project that can be self-hosted on Bitcoin nodes. It is readily available to install on many full-node distros such as Umbrel or Raspiblitz. Mempool uses port 4080 by default. Please include this when setting the endpoint (e.g. `http://localhost:4080`). Other custom ports should also work. From 5e4b1f1377e8dcd19f176d2db915107a0087c03c Mon Sep 17 00:00:00 2001 From: neriumpete Date: Sun, 11 Oct 2026 05:33:31 +0300 Subject: [PATCH 2/5] docs: Ethereum-only nest, what sees your addresses, MEV without a relay record --- usage-guides/quick-start.md | 2 +- usage-guides/settings/blockchain.md | 27 +++++++++++++++++++-------- 2 files changed, 20 insertions(+), 9 deletions(-) diff --git a/usage-guides/quick-start.md b/usage-guides/quick-start.md index cd2c235b..119e6429 100644 --- a/usage-guides/quick-start.md +++ b/usage-guides/quick-start.md @@ -39,7 +39,7 @@ Before adding accounts, set up a few things to make account detection and balanc - **Etherscan API Key** — Free and significantly speeds up EVM queries (and is required for some chains like Binance Smart Chain). Go to **API Keys → External Services** and add your key. See [External Services](/usage-guides/integrations/external-services#etherscan). - **Custom RPC Nodes** — Add your own RPC endpoints (e.g., from Alchemy or Infura) for faster blockchain queries. Configure in **Settings → RPC Nodes**. See [RPC Node Settings](/usage-guides/settings/blockchain#rpc-node-setting). -- **Indexer Configuration** — Adjust the order of indexers (Etherscan, Blockscout, Routescan, or a self-hosted Nuthatch nest) per chain for optimal performance. See [Indexers](/usage-guides/settings/blockchain#indexers). +- **Indexer Configuration** — Adjust the order of indexers (Etherscan, Blockscout, Routescan, or, for Ethereum, a self-hosted Nuthatch nest) per chain for optimal performance. See [Indexers](/usage-guides/settings/blockchain#indexers). > [!TIP] > At minimum, we strongly recommend adding a free Etherscan API key **before** adding your blockchain accounts. Without it, EVM queries and token detection will be significantly slower. diff --git a/usage-guides/settings/blockchain.md b/usage-guides/settings/blockchain.md index 6b445858..4998d10d 100644 --- a/usage-guides/settings/blockchain.md +++ b/usage-guides/settings/blockchain.md @@ -50,7 +50,7 @@ No indexer covers every chain, and each has its own key requirement: | **Etherscan** | Required, even on the free tier. One key covers every chain it serves | Most EVM chains, but **not** Scroll. Gnosis and Binance SC only on **paid** plans | | **Blockscout** | Required. The multichain endpoints reject keyless requests. One key covers every chain it serves. **Exception:** Hyperliquid is served through a free public instance and needs no key | Ethereum, Optimism, Polygon PoS, Arbitrum One, Base, Gnosis, Scroll, Hyperliquid | | **Routescan** | Not required | Ethereum and Optimism only | -| **Nuthatch** | Not required. A nest you run yourself, see [Using a Nuthatch nest](#using-a-nuthatch-nest) | The chain the nest indexes | +| **Nuthatch** | Not required. A nest you run yourself, see [Using a Nuthatch nest](#using-a-nuthatch-nest) | Ethereum | rotki caps its own Blockscout traffic at 10 requests per second, so parallel chain refreshes do not overwhelm the endpoint. @@ -65,16 +65,27 @@ Which means, in practice: ### Using a Nuthatch nest -A [Nuthatch](https://nuthatch-indexer.com) nest is an indexer you run yourself, against your own RPC node, so your addresses never leave your machine. A nest in rotki mode serves your tracked accounts' transactions, internal transactions, token transfers, ETH withdrawals and produced blocks (with their MEV rewards) in the same format rotki reads from Etherscan. How to install and run one is covered in [Nuthatch's documentation](https://nuthatch-indexer.com). +A [Nuthatch](https://nuthatch-indexer.com) nest is an indexer you run yourself, against an RPC endpoint you choose. A nest in rotki mode serves your tracked accounts' transactions, internal transactions, token transfers, ETH withdrawals and produced blocks (with their MEV rewards) in the same format rotki reads from Etherscan. How to install and run one is covered in [Nuthatch's documentation](https://nuthatch-indexer.com/rotki). -To use a nest: +Your history is built and stored on your machine, and no indexer service learns your list of addresses. What does see them: -1. Set its address under **Settings → RPC Nodes → Nuthatch nest**. By default rotki expects it at `http://127.0.0.1:8288`, where a nest listens unless told otherwise. -2. Add **Nuthatch** to the indexer order of the chain the nest indexes, first if you want it asked before the others. +- **Your RPC endpoint.** The nest asks it for each address's traces and logs, so a remote RPC provider sees the addresses in those requests. A node you run yourself sees them only locally. +- **Any indexer after the nest in the order.** When the nest cannot answer and rotki falls back, that indexer sees the addresses it is asked about, as it always has. +- **The block partition mirror, if the nest uses one.** It sees your IP address and the block ranges downloaded, never an address. +- **The MEV-Boost relays, if the nest has them turned on.** They see your IP address and the numbers of the blocks asked about, which identify a validator. -Once Nuthatch is in a chain's order, rotki registers the addresses you track on that chain with the nest, and adds or removes them as you add or remove accounts. If the nest is not running, adding an account still works and rotki registers it the next time it can. +rotki uses one nest, for Ethereum. To use it: -A nest answers only what it has fully indexed. Anything else, such as a block range it has not reached yet, is refused rather than answered with an empty list, and rotki asks the next indexer in the order instead. For produced blocks, rotki still queries beaconcha.in after the nest when you have a beaconcha.in API key, so a block the nest could not attribute to a validator is still found. +1. Set its address under **Settings → RPC Nodes → ETH Nuthatch Nest**. By default rotki expects it at `http://127.0.0.1:8288`, where a nest listens unless told otherwise. +2. Add **Nuthatch** to Ethereum's indexer order. Put it first to have it asked before the others; rotki does not reorder it for you. + +Leave Nuthatch out of other chains' orders: a nest serves only its own chain, and rotki skips it anywhere else. + +When you set the nest's address, change an indexer order, add or remove an account, or log in, rotki registers the Ethereum addresses you track with the nest, and removes the ones you stopped tracking, once Nuthatch is in Ethereum's order. If the nest is not running, nothing else is held up and rotki registers them the next time one of those happens. + +A nest answers only what it has fully indexed. Anything else, such as a block range it has not reached yet, is refused rather than answered with an empty list, and rotki asks the next indexer in the order instead. A nest's history starts at the block it was configured to start from, so if that is later than your accounts' first activity, keep another indexer after Nuthatch in the order for the earlier history. + +For produced blocks, a block's MEV reward comes from what the MEV-Boost relays recorded. When no relay has a record of a block, the block's reward is still added and rotki keeps asking about its MEV for 30 days, since relays can publish late. With a beaconcha.in API key, rotki also queries beaconcha.in after the nest, so a block the nest could not attribute to a validator is still found. ### Suppressing indexer notifications @@ -165,7 +176,7 @@ Set the RPC endpoint for the Ethereum consensus layer beacon node. If unreachabl #### Connecting to a Nuthatch nest -Set the address of a [Nuthatch nest](#using-a-nuthatch-nest) you run, for example `http://127.0.0.1:8288`. It is only queried on chains whose indexer order includes Nuthatch. +Set the address of the [Nuthatch nest](#using-a-nuthatch-nest) you run for Ethereum, for example `http://127.0.0.1:8288`. It is only queried once Nuthatch is in Ethereum's indexer order. #### Connecting to a Bitcoin Mempool instance From a2dd15448325b83114dd1437022662cf91804ea7 Mon Sep 17 00:00:00 2001 From: neriumpete Date: Sun, 11 Oct 2026 11:53:38 +0300 Subject: [PATCH 3/5] Nuthatch: validators are registered with the nest, and their produced blocks are proven from Dencun on --- usage-guides/settings/blockchain.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/usage-guides/settings/blockchain.md b/usage-guides/settings/blockchain.md index 4998d10d..a445bb07 100644 --- a/usage-guides/settings/blockchain.md +++ b/usage-guides/settings/blockchain.md @@ -81,11 +81,13 @@ rotki uses one nest, for Ethereum. To use it: Leave Nuthatch out of other chains' orders: a nest serves only its own chain, and rotki skips it anywhere else. -When you set the nest's address, change an indexer order, add or remove an account, or log in, rotki registers the Ethereum addresses you track with the nest, and removes the ones you stopped tracking, once Nuthatch is in Ethereum's order. If the nest is not running, nothing else is held up and rotki registers them the next time one of those happens. +When you set the nest's address, change an indexer order, add or remove an account or a validator, or log in, rotki registers the Ethereum addresses and validators you track with the nest, and removes the ones you stopped tracking, once Nuthatch is in Ethereum's order. If the nest is not running, nothing else is held up and rotki registers them the next time one of those happens. A nest answers only what it has fully indexed. Anything else, such as a block range it has not reached yet, is refused rather than answered with an empty list, and rotki asks the next indexer in the order instead. A nest's history starts at the block it was configured to start from, so if that is later than your accounts' first activity, keep another indexer after Nuthatch in the order for the earlier history. -For produced blocks, a block's MEV reward comes from what the MEV-Boost relays recorded. When no relay has a record of a block, the block's reward is still added and rotki keeps asking about its MEV for 30 days, since relays can publish late. With a beaconcha.in API key, rotki also queries beaconcha.in after the nest, so a block the nest could not attribute to a validator is still found. +For produced blocks, the nest proves which validator proposed each block, from the beacon block header the next Ethereum block commits to, so every block your validators proposed is found, whichever address its rewards went to. The proof is only possible from the Dencun upgrade (block 19,426,587, March 2024) on, and from the first block the nest has proven. A validator's blocks before that are not covered by the nest: with a beaconcha.in API key rotki finds them there, and without one it tells you which validators are not fully covered. Blocks paid to an address you do not track are shown as information, not as your income. + +A block's MEV reward comes from what the MEV-Boost relays recorded. When no relay has a record of a block, the block's reward is still added and rotki keeps asking about its MEV for 30 days, since relays can publish late. A block whose reward the nest could not read yet is added once it can, never as zero. ### Suppressing indexer notifications From 1b531c7e8d20ccc9ff955836ad0e24abe7bafa9d Mon Sep 17 00:00:00 2001 From: neriumpete Date: Sun, 11 Oct 2026 11:55:37 +0300 Subject: [PATCH 4/5] Nuthatch: a nest may prove only the last year of a validator's blocks --- usage-guides/settings/blockchain.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/usage-guides/settings/blockchain.md b/usage-guides/settings/blockchain.md index a445bb07..8057878a 100644 --- a/usage-guides/settings/blockchain.md +++ b/usage-guides/settings/blockchain.md @@ -85,7 +85,7 @@ When you set the nest's address, change an indexer order, add or remove an accou A nest answers only what it has fully indexed. Anything else, such as a block range it has not reached yet, is refused rather than answered with an empty list, and rotki asks the next indexer in the order instead. A nest's history starts at the block it was configured to start from, so if that is later than your accounts' first activity, keep another indexer after Nuthatch in the order for the earlier history. -For produced blocks, the nest proves which validator proposed each block, from the beacon block header the next Ethereum block commits to, so every block your validators proposed is found, whichever address its rewards went to. The proof is only possible from the Dencun upgrade (block 19,426,587, March 2024) on, and from the first block the nest has proven. A validator's blocks before that are not covered by the nest: with a beaconcha.in API key rotki finds them there, and without one it tells you which validators are not fully covered. Blocks paid to an address you do not track are shown as information, not as your income. +For produced blocks, the nest proves which validator proposed each block, from the beacon block header the next Ethereum block commits to, so every block your validators proposed is found, whichever address its rewards went to. The proof is only possible from the Dencun upgrade (block 19,426,587, March 2024) on, and only from the first block the nest has proven, which can be later: a nest built from published partitions may cover only the last year. A validator's blocks before that are not covered by the nest: with a beaconcha.in API key rotki finds them there, and without one it tells you which validators are not fully covered. Blocks paid to an address you do not track are shown as information, not as your income. A block's MEV reward comes from what the MEV-Boost relays recorded. When no relay has a record of a block, the block's reward is still added and rotki keeps asking about its MEV for 30 days, since relays can publish late. A block whose reward the nest could not read yet is added once it can, never as zero. From 6974b5852dd648313fb096d526e1611d6313ad0f Mon Sep 17 00:00:00 2001 From: neriumpete Date: Sun, 11 Oct 2026 19:32:42 +0300 Subject: [PATCH 5/5] Clarify Nuthatch validator coverage and private indexer ordering --- usage-guides/settings/blockchain.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/usage-guides/settings/blockchain.md b/usage-guides/settings/blockchain.md index 8057878a..5104a879 100644 --- a/usage-guides/settings/blockchain.md +++ b/usage-guides/settings/blockchain.md @@ -65,7 +65,7 @@ Which means, in practice: ### Using a Nuthatch nest -A [Nuthatch](https://nuthatch-indexer.com) nest is an indexer you run yourself, against an RPC endpoint you choose. A nest in rotki mode serves your tracked accounts' transactions, internal transactions, token transfers, ETH withdrawals and produced blocks (with their MEV rewards) in the same format rotki reads from Etherscan. How to install and run one is covered in [Nuthatch's documentation](https://nuthatch-indexer.com/rotki). +The Nuthatch integration requires Nuthatch 5.3.0 or later. A [Nuthatch](https://nuthatch-indexer.com) nest is an indexer you run yourself, against an RPC endpoint you choose. A nest in rotki mode serves your tracked accounts' transactions, internal transactions, token transfers, ETH withdrawals and produced blocks (with their MEV rewards) in the same format rotki reads from Etherscan. How to install and run one is covered in [Nuthatch's documentation](https://nuthatch-indexer.com/rotki). Your history is built and stored on your machine, and no indexer service learns your list of addresses. What does see them: @@ -77,7 +77,7 @@ Your history is built and stored on your machine, and no indexer service learns rotki uses one nest, for Ethereum. To use it: 1. Set its address under **Settings → RPC Nodes → ETH Nuthatch Nest**. By default rotki expects it at `http://127.0.0.1:8288`, where a nest listens unless told otherwise. -2. Add **Nuthatch** to Ethereum's indexer order. Put it first to have it asked before the others; rotki does not reorder it for you. +2. Add **Nuthatch** to Ethereum's indexer order. Put it first to have it asked before the others; rotki does not reorder it for you. Select Nuthatch alone to keep account-history queries with the nest. Withdrawals then use only the indexers you selected, including when the nest is unavailable. Leave Nuthatch out of other chains' orders: a nest serves only its own chain, and rotki skips it anywhere else. @@ -85,7 +85,7 @@ When you set the nest's address, change an indexer order, add or remove an accou A nest answers only what it has fully indexed. Anything else, such as a block range it has not reached yet, is refused rather than answered with an empty list, and rotki asks the next indexer in the order instead. A nest's history starts at the block it was configured to start from, so if that is later than your accounts' first activity, keep another indexer after Nuthatch in the order for the earlier history. -For produced blocks, the nest proves which validator proposed each block, from the beacon block header the next Ethereum block commits to, so every block your validators proposed is found, whichever address its rewards went to. The proof is only possible from the Dencun upgrade (block 19,426,587, March 2024) on, and only from the first block the nest has proven, which can be later: a nest built from published partitions may cover only the last year. A validator's blocks before that are not covered by the nest: with a beaconcha.in API key rotki finds them there, and without one it tells you which validators are not fully covered. Blocks paid to an address you do not track are shown as information, not as your income. +For produced blocks, the nest proves which validator proposed each block, from the beacon block header the next Ethereum block commits to, so every block your validators proposed is found, whichever address its rewards went to. The supported catalogue starts at slot 12,777,208, execution block 23,551,570. Earlier proposals remain outside the nest's proven coverage. The published catalogue advances in complete 10,000-block spans. Set `beacon_url` in the nest configuration to your beacon node to prove blocks beyond the published catalogue; otherwise that tail remains incomplete until publication. A validator's blocks before that are not covered by the nest: with a beaconcha.in API key rotki finds them there, and without one it tells you which validators are not fully covered. Blocks paid to an address you do not track are shown as information, not as your income. A block's MEV reward comes from what the MEV-Boost relays recorded. When no relay has a record of a block, the block's reward is still added and rotki keeps asking about its MEV for 30 days, since relays can publish late. A block whose reward the nest could not read yet is added once it can, never as zero.