eth, internal/ethapi: add eth_capabilities RPC method

Author: Владислав Поплавский

eth/api_backend.go

@@ -40,6 +40,7 @@ import (
 	"github.com/ethereum/go-ethereum/eth/tracers"
 	"github.com/ethereum/go-ethereum/ethdb"
 	"github.com/ethereum/go-ethereum/event"
+	"github.com/ethereum/go-ethereum/internal/ethapi"
 	"github.com/ethereum/go-ethereum/params"
 	"github.com/ethereum/go-ethereum/rpc"
 )
@@ -278,6 +279,17 @@ func (b *EthAPIBackend) HistoryPruningCutoff() uint64 {
 	return bn
 }
 
+func (b *EthAPIBackend) HistoryRetention() ethapi.HistoryRetention {
+	cfg := b.eth.config
+	return ethapi.HistoryRetention{
+		TxIndexHistory:   cfg.TransactionHistory,
+		LogIndexHistory:  cfg.LogHistory,
+		LogIndexDisabled: cfg.LogNoHistory,
+		StateHistory:     cfg.StateHistory,
+		StateScheme:      b.eth.blockchain.TrieDB().Scheme(),
+	}
+}
+
 func (b *EthAPIBackend) GetReceipts(ctx context.Context, hash common.Hash) (types.Receipts, error) {
 	return b.eth.blockchain.GetReceiptsByHash(hash), nil
 }

internal/ethapi/api_test.go

@@ -708,6 +708,9 @@ func (b testBackend) HistoryPruningCutoff() uint64 {
 	bn, _ := b.chain.HistoryPruningCutoff()
 	return bn
 }
+func (b testBackend) HistoryRetention() HistoryRetention {
+	return HistoryRetention{StateScheme: b.chain.TrieDB().Scheme()}
+}
 
 func TestEstimateGas(t *testing.T) {
 	t.Parallel()

internal/ethapi/backend.go

@@ -90,6 +90,7 @@ type Backend interface {
 	ChainConfig() *params.ChainConfig
 	Engine() consensus.Engine
 	HistoryPruningCutoff() uint64
+	HistoryRetention() HistoryRetention
 
 	// This is copied from filters.Backend
 	// eth/filters needs to be initialized from this backend type, so methods needed by

internal/ethapi/capabilities.go

@@ -0,0 +1,208 @@
+// Copyright 2026 The go-ethereum Authors
+// This file is part of the go-ethereum library.
+//
+// The go-ethereum library is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// The go-ethereum library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
+
+package ethapi
+
+import (
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/hexutil"
+	"github.com/ethereum/go-ethereum/core/rawdb"
+)
+
+// HistoryRetention reports a node's configured history retention windows.
+// It is consumed by the eth_capabilities RPC method to derive the response
+// described in https://github.com/ethereum/execution-apis/pull/755.
+type HistoryRetention struct {
+	// TxIndexHistory is the number of recent blocks for which the
+	// transaction lookup index is maintained. Zero means the index covers
+	// the entire available chain.
+	TxIndexHistory uint64
+
+	// LogIndexHistory is the number of recent blocks for which the log
+	// search index is maintained. Zero means the index covers the entire
+	// available chain.
+	LogIndexHistory uint64
+
+	// LogIndexDisabled reports whether the log search index has been
+	// turned off entirely.
+	LogIndexDisabled bool
+
+	// StateHistory is the number of recent blocks for which historical
+	// state is retained. Zero means the entire chain state is kept
+	// (archive node).
+	StateHistory uint64
+
+	// StateScheme is the state storage scheme in use, either "hash" or
+	// "path". The hash scheme does not support a sliding state window.
+	StateScheme string
+}
+
+// Capabilities reports which historical data the node can serve. It is
+// returned by the eth_capabilities RPC method as defined in
+// https://github.com/ethereum/execution-apis/pull/755.
+type Capabilities struct {
+	Head        CapabilityHead     `json:"head"`
+	State       CapabilityResource `json:"state"`
+	Tx          CapabilityResource `json:"tx"`
+	Logs        CapabilityResource `json:"logs"`
+	Receipts    CapabilityResource `json:"receipts"`
+	Blocks      CapabilityResource `json:"blocks"`
+	StateProofs CapabilityResource `json:"stateproofs"`
+}
+
+// CapabilityHead is the current canonical head as reported by the node.
+type CapabilityHead struct {
+	BlockNumber hexutil.Uint64 `json:"blockNumber"`
+	BlockHash   common.Hash    `json:"blockHash"`
+}
+
+// CapabilityResource describes the availability of a single data resource.
+type CapabilityResource struct {
+	Disabled       bool           `json:"disabled"`
+	OldestBlock    hexutil.Uint64 `json:"oldestBlock"`
+	DeleteStrategy DeleteStrategy `json:"deleteStrategy"`
+}
+
+// DeleteStrategy describes how data of a resource is removed over time.
+//
+// Two strategies are defined by the spec:
+//
+//   - "none":   data is never deleted; the resource is permanently
+//     retained from oldestBlock onwards.
+//   - "window": data is retained for a sliding window of the most recent
+//     RetentionBlocks blocks.
+//
+// RetentionBlocks is omitted from the JSON output for the "none" strategy.
+type DeleteStrategy struct {
+	Type            string  `json:"type"`
+	RetentionBlocks *uint64 `json:"retentionBlocks,omitempty"`
+}
+
+// strategyNone returns a DeleteStrategy with type "none".
+func strategyNone() DeleteStrategy {
+	return DeleteStrategy{Type: "none"}
+}
+
+// strategyWindow returns a DeleteStrategy with type "window" and the given
+// retention block count.
+func strategyWindow(retention uint64) DeleteStrategy {
+	return DeleteStrategy{Type: "window", RetentionBlocks: &retention}
+}
+
+// Capabilities implements the eth_capabilities RPC method as defined in
+// https://github.com/ethereum/execution-apis/pull/755. It returns a
+// description of the historical data this node can serve, allowing RPC
+// routers to determine which queries can be answered without hitting
+// "history pruned" errors.
+func (api *BlockChainAPI) Capabilities() *Capabilities {
+	head := api.b.CurrentHeader()
+	return buildCapabilities(
+		head.Number.Uint64(),
+		head.Hash(),
+		api.b.HistoryPruningCutoff(),
+		api.b.HistoryRetention(),
+	)
+}
+
+// buildCapabilities computes the eth_capabilities response from the head
+// block, the absolute history pruning cutoff, and the configured retention
+// windows. It is split out from the RPC method so the mapping rules can be
+// unit tested without a backend.
+func buildCapabilities(headNum uint64, headHash common.Hash, cutoff uint64, ret HistoryRetention) *Capabilities {
+	// windowOldest returns the oldest block reachable through a sliding
+	// window of `window` blocks, never going below the absolute history
+	// pruning cutoff. A window of zero means "no sliding deletion" and
+	// reports the cutoff itself.
+	windowOldest := func(window uint64) uint64 {
+		if window == 0 || headNum+1 <= window {
+			return cutoff
+		}
+		oldest := headNum + 1 - window
+		if oldest < cutoff {
+			return cutoff
+		}
+		return oldest
+	}
+
+	// resource builds a CapabilityResource for a window-style resource.
+	// A window of zero is reported as deleteStrategy "none".
+	resource := func(disabled bool, window uint64) CapabilityResource {
+		ds := strategyNone()
+		if window != 0 {
+			ds = strategyWindow(window)
+		}
+		return CapabilityResource{
+			Disabled:       disabled,
+			OldestBlock:    hexutil.Uint64(windowOldest(window)),
+			DeleteStrategy: ds,
+		}
+	}
+
+	// Headers, bodies and receipts share the same retention model in
+	// geth: they are either kept in full ("all") or pruned to a fixed
+	// boundary ("postmerge"). In neither case is there a sliding
+	// deletion window, so the strategy is always "none" and the oldest
+	// block equals the history pruning cutoff.
+	blocks := CapabilityResource{
+		Disabled:       false,
+		OldestBlock:    hexutil.Uint64(cutoff),
+		DeleteStrategy: strategyNone(),
+	}
+	receipts := blocks
+
+	tx := resource(false, ret.TxIndexHistory)
+	logs := resource(ret.LogIndexDisabled, ret.LogIndexHistory)
+
+	// State availability depends on the storage scheme:
+	//
+	//   - hash scheme:  archive when StateHistory == 0; otherwise only
+	//                   the head state is reachable, with no sliding
+	//                   window.
+	//   - path scheme:  honors the configured StateHistory window.
+	var state CapabilityResource
+	switch {
+	case ret.StateScheme == rawdb.HashScheme && ret.StateHistory == 0:
+		state = CapabilityResource{
+			Disabled:       false,
+			OldestBlock:    hexutil.Uint64(cutoff),
+			DeleteStrategy: strategyNone(),
+		}
+	case ret.StateScheme == rawdb.HashScheme:
+		state = CapabilityResource{
+			Disabled:       false,
+			OldestBlock:    hexutil.Uint64(headNum),
+			DeleteStrategy: strategyNone(),
+		}
+	default:
+		state = resource(false, ret.StateHistory)
+	}
+
+	// eth_getProof availability tracks state availability one-for-one.
+	stateproofs := state
+
+	return &Capabilities{
+		Head: CapabilityHead{
+			BlockNumber: hexutil.Uint64(headNum),
+			BlockHash:   headHash,
+		},
+		State:       state,
+		Tx:          tx,
+		Logs:        logs,
+		Receipts:    receipts,
+		Blocks:      blocks,
+		StateProofs: stateproofs,
+	}
+}