Merge pull request #119 from ethpandaops/release/state-expiry

Release/state expiry

Author: mattevans

backend/pkg/api/v1/proto/public.pb.go

@@ -81,6 +81,54 @@ message FilterMetadata {
   string order_by = 3;
 }
 
+// StateExpiryAccessTotalResponse is the v1 API response for state expiry access totals.
+message StateExpiryAccessTotalResponse {
+  StateExpiryAccessTotal item = 1;
+  FilterMetadata filters = 2;
+}
+
+// StateExpiryAccessTotal represents state expiry access statistics for public API consumption.
+message StateExpiryAccessTotal {
+  // Total number of accounts accessed in last 365 days
+  uint64 total_accounts = 1;
+  // Number of expired accounts (not accessed in last 365 days)
+  uint64 expired_accounts = 2;
+  // Total number of contract accounts accessed in last 365 days
+  uint64 total_contracts = 3;
+  // Number of expired contracts (not accessed in last 365 days)
+  uint64 expired_contracts = 4;
+}
+
+// StateExpiryBlockResponse is the v1 API response for state expiry block information.
+// Returns the execution layer block number from approximately 1 year ago, which is
+// used as the expiry boundary for state expiry calculations.
+message StateExpiryBlockResponse {
+  StateExpiryBlock item = 1;
+  FilterMetadata filters = 2;
+}
+
+// StateExpiryBlock represents the execution block from approximately 1 year ago
+// that serves as the boundary for state expiry calculations.
+message StateExpiryBlock {
+  // The execution layer block number from approximately 1 year ago
+  uint32 block_number = 1;
+}
+
+// StateExpiryStorageTotalResponse is the v1 API response for storage slot totals.
+// This endpoint provides the latest total storage slot statistics for state expiry analysis.
+message StateExpiryStorageTotalResponse {
+  StateExpiryStorageTotal item = 1;
+  FilterMetadata filters = 2;
+}
+
+// StateExpiryStorageTotal represents state expiry storage slot statistics for public API consumption.
+message StateExpiryStorageTotal {
+  // Total number of storage slots accessed in last 365 days
+  uint64 total_storage_slots = 1;
+  // Number of expired storage slots (not accessed in last 365 days)
+  uint64 expired_storage_slots = 2;
+}
+
 
 // Network represents an Ethereum network for public API consumption.
 // This provides essential network metadata needed by clients.
@@ -98,6 +146,86 @@ message NetworkFilterMetadata {
   int32 filtered_count = 3;             // Networks after filtering
 }
 
+// StateExpiryAccessHistoryResponse is the v1 API response for state expiry access history data.
+// This endpoint provides aggregated data about Ethereum address access patterns chunked by 10000 blocks.
+message StateExpiryAccessHistoryResponse {
+  repeated StateExpiryAccessHistory items = 1;
+  PaginationMetadata pagination = 2;
+  FilterMetadata filters = 3;
+}
+
+// StateExpiryAccessHistory represents address access statistics for a 10000-block chunk.
+// This data is useful for analyzing state expiry patterns and understanding address activity over time.
+message StateExpiryAccessHistory {
+  // The starting block number of this 10000-block chunk
+  uint32 chunk_start_block_number = 1;
+
+  // Number of unique accounts that were accessed for the first time in this chunk
+  // These are addresses that had never been accessed before this chunk
+  uint32 first_accessed_accounts = 2;
+
+  // Number of unique accounts whose most recent access was in this chunk
+  // These addresses haven't been accessed in any later chunks
+  uint32 last_accessed_accounts = 3;
+}
+
+// StateExpiryStorageHistoryResponse is the v1 API response for state expiry storage slot history data.
+// This endpoint provides aggregated data about Ethereum storage slot access patterns chunked by 10000 blocks.
+message StateExpiryStorageHistoryResponse {
+  repeated StateExpiryStorageHistory items = 1;
+  PaginationMetadata pagination = 2;
+  FilterMetadata filters = 3;
+}
+
+// StateExpiryStorageHistory represents storage slot statistics for a 10000-block chunk.
+// This data is useful for analyzing state expiry patterns and understanding storage slot activity over time.
+message StateExpiryStorageHistory {
+  // The starting block number of this 10000-block chunk
+  uint32 chunk_start_block_number = 1;
+
+  // Number of storage slots that were accessed for the first time in this chunk
+  // These are slots that had never been accessed before this chunk
+  uint32 first_accessed_slots = 2;
+
+  // Number of storage slots whose most recent access was in this chunk
+  // These slots haven't been accessed in any later chunks
+  uint32 last_accessed_slots = 3;
+}
+
+// StateExpiryStorageExpiredTopResponse is the v1 API response for top contracts by expired storage slots.
+// This endpoint provides the top 100 contracts ranked by the number of expired storage slots (not accessed in last 365 days).
+message StateExpiryStorageExpiredTopResponse {
+  repeated StateExpiryStorageExpiredTop items = 1;
+  FilterMetadata filters = 2;
+}
+
+// StateExpiryStorageExpiredTop represents a contract ranked by expired storage slots for public API consumption.
+message StateExpiryStorageExpiredTop {
+  // Rank by expired storage slots (1=highest)
+  uint32 rank = 1;
+  // The contract address
+  string contract_address = 2;
+  // Number of expired storage slots for this contract (not accessed in last 365 days)
+  uint64 expired_slots = 3;
+}
+
+// StateExpiryStorageTopResponse is the v1 API response for top contracts by total storage slots.
+// This endpoint provides the top 100 contracts ranked by the total number of storage slots.
+message StateExpiryStorageTopResponse {
+  repeated StateExpiryStorageTop items = 1;
+  FilterMetadata filters = 2;
+}
+
+// StateExpiryStorageTop represents a contract ranked by total storage slots for public API consumption.
+message StateExpiryStorageTop {
+  // Rank by total storage slots (1=highest)
+  uint32 rank = 1;
+  // The contract address
+  string contract_address = 2;
+  // Total number of storage slots for this contract
+  uint64 total_storage_slots = 3;
+}
+
 // ListBeaconSlotMevRelayResponse is the v1 API response for MEV relay bid counts by slot.
 message ListBeaconSlotMevRelayResponse {
   repeated MevRelayBidCount relays = 1;

backend/pkg/api/v1/proto/public.proto

@@ -150,5 +150,56 @@ func (r *PublicRouter) GetRoutes() []RouteConfig {
 			Cache:       middleware.CacheRealtime,
 			Description: "Get prepared blocks for a specific slot",
 		},
+
+		// State expiry endpoints
+		{
+			Path:        "/{network}/state-expiry/access/history",
+			Handler:     r.handleStateExpiryAccessHistory,
+			Methods:     []string{http.MethodGet, http.MethodOptions},
+			Cache:       middleware.CacheNearRealtime,
+			Description: "Get address access history chunked by 10000 blocks for state expiry analysis",
+		},
+		{
+			Path:        "/{network}/state-expiry/storage/history",
+			Handler:     r.handleStateExpiryStorageHistory,
+			Methods:     []string{http.MethodGet, http.MethodOptions},
+			Cache:       middleware.CacheNearRealtime,
+			Description: "Get storage slot history chunked by 10000 blocks for state expiry analysis",
+		},
+		{
+			Path:        "/{network}/state-expiry/access/total",
+			Handler:     r.handleStateExpiryAccessTotal,
+			Methods:     []string{http.MethodGet, http.MethodOptions},
+			Cache:       middleware.CacheNearRealtime,
+			Description: "Get total address access statistics for state expiry analysis",
+		},
+		{
+			Path:        "/{network}/state-expiry/storage/expired/top",
+			Handler:     r.handleStateExpiryStorageExpiredTop,
+			Methods:     []string{http.MethodGet, http.MethodOptions},
+			Cache:       middleware.CacheNearRealtime,
+			Description: "Get top 100 contracts by expired storage slots for state expiry analysis",
+		},
+		{
+			Path:        "/{network}/state-expiry/storage/top",
+			Handler:     r.handleStateExpiryStorageTop,
+			Methods:     []string{http.MethodGet, http.MethodOptions},
+			Cache:       middleware.CacheNearRealtime,
+			Description: "Get top 100 contracts by total storage slots for state expiry analysis",
+		},
+		{
+			Path:        "/{network}/state-expiry/storage/total",
+			Handler:     r.handleStateExpiryStorageTotal,
+			Methods:     []string{http.MethodGet, http.MethodOptions},
+			Cache:       middleware.CacheNearRealtime,
+			Description: "Get total storage slot statistics for state expiry analysis",
+		},
+		{
+			Path:        "/{network}/state-expiry/expiry/block",
+			Handler:     r.handleStateExpiryBlock,
+			Methods:     []string{http.MethodGet, http.MethodOptions},
+			Cache:       middleware.CacheNearRealtime,
+			Description: "Get the execution block number from approximately 1 year ago for state expiry boundary",
+		},
 	}
 }