Merge pull request #1325 from IntersectMBO/mgalazyn/feature/rpc-readerasummary

cardano-rpc: Implement ReadEraSummary gRPC method

Author: carbolymer

.changes/20260903_cardano_rpc_read_era_summary.yml

@@ -0,0 +1,7 @@
+project: cardano-rpc
+pr: 1325
+kind:
+  - feature
+  - breaking
+description: |
+  Implement the `ReadEraSummary` gRPC method, returning the era name and the start and end boundaries (Unix-epoch milliseconds, slot, epoch) of every era in the chain's history. The `NodeKernelAccess` type is now abstract; use the functions of `Cardano.Rpc.Server.NodeKernelAccess` instead of its record fields.

cardano-rpc/README.md

@@ -21,7 +21,7 @@ Use a dedicated chain indexing service for those.
 | [ReadData](https://utxorpc.org/query/spec/#readdatarequest) | ❌ Not supported, needs a chain indexer |
 | [ReadTx](https://utxorpc.org/query/spec/#queryservice) | ❌ Not supported, needs a chain indexer |
 | [ReadGenesis](https://utxorpc.org/query/spec/#queryservice) | ✅ Supported |
-| [ReadEraSummary](https://utxorpc.org/query/spec/#queryservice) | ⬜ Not supported |
+| [ReadEraSummary](https://utxorpc.org/query/spec/#queryservice) | ✅ Supported |
 | [ReadState](https://utxorpc.org/query/spec/#queryservice) | ⬜ Not supported |
 
 ### [SubmitService](https://utxorpc.org/submit/spec/)

cardano-rpc/cardano-rpc.cabal

@@ -71,6 +71,7 @@ library
     Cardano.Rpc.Server.Internal.UtxoRpc.Type.Byron
     Cardano.Rpc.Server.Internal.UtxoRpc.Type.Certificate
     Cardano.Rpc.Server.Internal.UtxoRpc.Type.ChainPoint
+    Cardano.Rpc.Server.Internal.UtxoRpc.Type.EraSummary
     Cardano.Rpc.Server.Internal.UtxoRpc.Type.Genesis
     Cardano.Rpc.Server.Internal.UtxoRpc.Type.Governance
     Cardano.Rpc.Server.Internal.UtxoRpc.Type.PlutusData
@@ -81,10 +82,10 @@ library
     Cardano.Rpc.Server.Internal.UtxoRpc.Type.TxEval
     Cardano.Rpc.Server.Internal.UtxoRpc.Type.TxOutput
     Cardano.Rpc.Server.NodeKernelAccess
-    Cardano.Rpc.Server.NodeKernelAccess.Type
 
   other-modules:
     Cardano.Rpc.Server.Internal.Orphans
+    Cardano.Rpc.Server.NodeKernelAccess.Internal.Type
     Paths_cardano_rpc
 
   autogen-modules:
@@ -110,6 +111,7 @@ library
     cardano-ledger-dijkstra,
     cardano-ledger-shelley,
     cardano-rpc:gen,
+    cardano-slotting,
     containers,
     contra-tracer,
     data-default,
@@ -125,10 +127,13 @@ library
     mempack,
     microlens,
     network,
+    ouroboros-consensus,
+    ouroboros-consensus:cardano,
     proto-lens >=0.7.1.7,
     proto-lens-protobuf-types,
     random,
     rio,
+    sop-extras,
     strict-sop-core,
     text,
     time,
@@ -183,6 +188,7 @@ test-suite cardano-rpc-test
     cardano-ledger-shelley,
     cardano-ledger-shelley:testlib,
     cardano-rpc,
+    cardano-slotting,
     containers,
     formatting,
     grpc-spec,
@@ -191,10 +197,12 @@ test-suite cardano-rpc-test
     hedgehog-quickcheck,
     memory,
     mtl,
+    ouroboros-consensus,
     ouroboros-consensus:cardano,
     proto-lens,
     rio,
     scientific,
+    sop-extras,
     tasty,
     tasty-hedgehog,
     text,
@@ -209,6 +217,7 @@ test-suite cardano-rpc-test
   build-tool-depends: tasty-discover:tasty-discover
   other-modules:
     Test.Cardano.Rpc.ByronTx
+    Test.Cardano.Rpc.EraSummary
     Test.Cardano.Rpc.Eval
     Test.Cardano.Rpc.FetchBlockTx
     Test.Cardano.Rpc.FollowTipStream

cardano-rpc/src/Cardano/Rpc/Server.hs

@@ -71,7 +71,7 @@ methodsUtxoRpc
   => Methods m (ProtobufMethodsOf UtxoRpc.QueryService)
 methodsUtxoRpc =
   UnsupportedMethod -- readData
-    . UnsupportedMethod -- readEraSummary
+    . Method (mkNonStreaming $ wrapInSpan TraceRpcQueryReadEraSummarySpan . readEraSummaryMethod)
     . Method (mkNonStreaming $ wrapInSpan TraceRpcQueryReadGenesisSpan . readGenesisMethod)
     . Method (mkNonStreaming $ wrapInSpan TraceRpcQueryParamsSpan . readParamsMethod)
     . UnsupportedMethod -- readState

cardano-rpc/src/Cardano/Rpc/Server/Internal/Env.hs

@@ -10,7 +10,7 @@ where
 import Cardano.Api
 import Cardano.Rpc.Server.Config
 import Cardano.Rpc.Server.Internal.Tracing
-import Cardano.Rpc.Server.NodeKernelAccess.Type (NodeKernelAccess)
+import Cardano.Rpc.Server.NodeKernelAccess.Internal.Type (NodeKernelAccess)
 
 import Control.Tracer (Tracer)
 import Data.IORef

cardano-rpc/src/Cardano/Rpc/Server/Internal/Monad.hs

@@ -24,7 +24,7 @@ where
 import Cardano.Api
 import Cardano.Rpc.Server.Internal.Env
 import Cardano.Rpc.Server.Internal.Tracing
-import Cardano.Rpc.Server.NodeKernelAccess.Type (NodeKernelAccess)
+import Cardano.Rpc.Server.NodeKernelAccess.Internal.Type (NodeKernelAccess)
 
 import RIO
 

cardano-rpc/src/Cardano/Rpc/Server/Internal/Tracing.hs

@@ -37,6 +37,8 @@ data TraceRpcQuery
     TraceRpcQuerySearchUtxosSpan TraceSpanEvent
   | -- | Span trace marking ReadGenesis query
     TraceRpcQueryReadGenesisSpan TraceSpanEvent
+  | -- | Span trace marking ReadEraSummary query
+    TraceRpcQueryReadEraSummarySpan TraceSpanEvent
   deriving Show
 
 instance Pretty TraceRpc where
@@ -70,6 +72,8 @@ instance Pretty TraceRpcQuery where
     TraceRpcQuerySearchUtxosSpan (SpanEnd _) -> "Finished query search UTXO method"
     TraceRpcQueryReadGenesisSpan (SpanBegin _) -> "Started query read genesis method"
     TraceRpcQueryReadGenesisSpan (SpanEnd _) -> "Finished query read genesis method"
+    TraceRpcQueryReadEraSummarySpan (SpanBegin _) -> "Started query read era summary method"
+    TraceRpcQueryReadEraSummarySpan (SpanEnd _) -> "Finished query read era summary method"
 
 instance Error TraceRpcQuery where
   prettyError = pretty

cardano-rpc/src/Cardano/Rpc/Server/Internal/UtxoRpc/Query.hs

@@ -16,6 +16,7 @@ module Cardano.Rpc.Server.Internal.UtxoRpc.Query
   , readUtxosMethod
   , searchUtxosMethod
   , readGenesisMethod
+  , readEraSummaryMethod
   , paginateByTxIn
   )
 where
@@ -201,14 +202,11 @@ readGenesisMethod
   -> m (Proto UtxoRpc.ReadGenesisResponse)
 readGenesisMethod _req = do
   -- TODO: field masks are ignored for now (same as readParamsMethod)
-  NodeKernelAccess
-    { genesisConfig =
-      genesisBundle@GenesisBundle
+  nodeKernelAccess <- grabNodeKernelAccess
+  let genesisBundle@GenesisBundle
         { shelleyGenesisHash
         , shelleyGenesis = (shelleyGenesisFile, shelleyGenesisCache)
-        }
-    } <-
-    grabNodeKernelAccess
+        } = genesisConfig nodeKernelAccess
   shelleyGenesis <-
     readThroughCache shelleyGenesisCache $
       readShelleyGenesisWithInitialFunds shelleyGenesisFile shelleyGenesisHash
@@ -267,6 +265,21 @@ readShelleyGenesisWithInitialFunds shelleyGenesisFile@(File path) bootGenesisHas
         <> ": "
         <> Text.pack reason
 
+-- | Handle the @ReadEraSummary@ RPC method.
+-- Returns the node's hard-fork era summary: one entry per era the node's
+-- ledger state has seen so far, with name and start/end boundaries. See
+-- 'eraSummariesToProto' for exactly which fields are populated.
+readEraSummaryMethod
+  :: MonadRpc e m
+  => Proto UtxoRpc.ReadEraSummaryRequest
+  -> m (Proto UtxoRpc.ReadEraSummaryResponse)
+readEraSummaryMethod _req = do
+  -- TODO: field masks are ignored for now (same as readParamsMethod)
+  nodeKernelAccess <- grabNodeKernelAccess
+  summary <- readHardForkSummary nodeKernelAccess
+  pure $
+    defMessage & U5c.cardano .~ eraSummariesToProto (nodeKernelSystemStart nodeKernelAccess) summary
+
 -- | The CAIP-2 chain identifier for a Cardano network, keyed on the Shelley
 -- network magic.
 -- This follows Dolos, the reference UTxO RPC implementation: the three

cardano-rpc/src/Cardano/Rpc/Server/Internal/UtxoRpc/Sync.hs

@@ -66,7 +66,7 @@ fetchBlockMethod request = do
         <> tshow maxFetchBlockRefs
         <> "; batch your requests"
 
-  nodeKernelAccess@NodeKernelAccess{systemStart, readEraHistory} <- grabNodeKernelAccess
+  nodeKernelAccess <- grabNodeKernelAccess
   blocks <- forM (request ^. U5c.ref) $ \blockRef -> do
     (slot, headerHash) <- blockRefToPoint blockRef
     let throwNotFound =
@@ -77,7 +77,8 @@ fetchBlockMethod request = do
               <> serialiseToRawBytesHexText headerHash
     (rawBytes, blockInMode) <-
       fetchBlock nodeKernelAccess slot headerHash >>= maybe throwNotFound pure
-    timestamp <- slotTimestampOrThrow systemStart readEraHistory slot
+    timestamp <-
+      slotTimestampOrThrow (nodeKernelSystemStart nodeKernelAccess) (readEraHistory nodeKernelAccess) slot
     pure $ mkAnyChainBlock rawBytes blockInMode timestamp
   pure $ defMessage & U5c.block .~ blocks
 
@@ -94,8 +95,11 @@ readTipMethod
   => Proto U5c.ReadTipRequest
   -> m (Proto U5c.ReadTipResponse)
 readTipMethod _request = do
-  NodeKernelAccess{chainDb, systemStart, readEraHistory} <- grabNodeKernelAccess
-  tip <- readTipBlockRef chainDb (slotTimestampOrThrow systemStart readEraHistory)
+  nodeKernelAccess <- grabNodeKernelAccess
+  tip <-
+    readTipBlockRef
+      nodeKernelAccess
+      (slotTimestampOrThrow (nodeKernelSystemStart nodeKernelAccess) (readEraHistory nodeKernelAccess))
   pure $ defMessage & U5c.maybe'tip .~ tip
 
 -- | Handle the @FollowTip@ SyncService RPC method: stream fully parsed
@@ -115,7 +119,7 @@ readTipMethod _request = do
 -- slot and hash only, like ChainSync's @MsgRollBackward@. The tracked
 -- window is sized to the node's security parameter /k/, so no rollback
 -- consensus can produce falls outside it (see
--- 'Cardano.Rpc.Server.NodeKernelAccess.Type.NodeKernelAccess').
+-- 'Cardano.Rpc.Server.NodeKernelAccess.securityParam').
 -- Every response also carries the current chain tip.
 --
 -- Errors: @INVALID_ARGUMENT@ if an intersection block ref has an invalid
@@ -131,28 +135,27 @@ followTipMethod
   -- ^ Callback used to send each streamed response
   -> m ()
 followTipMethod request send = do
-  nodeKernelAccess@NodeKernelAccess{chainDb, systemStart, readEraHistory, securityParam} <-
-    grabNodeKernelAccess
+  nodeKernelAccess <- grabNodeKernelAccess
   requestedPoints <- traverse blockRefToIntersectPoint (request ^. U5c.intersect)
   withFollower nodeKernelAccess $ \follower -> do
     -- an empty intersect list follows from the current tip; resolving it
     -- reaches into ChainDB directly (there is no 'ChainFollower' operation
     -- for "the current tip point"), so this step stays here rather than
     -- moving into 'followTipStream', which only takes an already-resolved,
     -- non-empty point list
-    let slotTimestamp = slotTimestampOrThrow systemStart readEraHistory
+    let slotTimestamp = slotTimestampOrThrow (nodeKernelSystemStart nodeKernelAccess) (readEraHistory nodeKernelAccess)
     startPoints <-
       if null requestedPoints
         then do
-          tipHeader <- liftIO $ Consensus.getTipHeader chainDb
+          tipHeader <- readChainTipHeader nodeKernelAccess
           pure [maybe ChainPointAtGenesis tipHeaderPoint tipHeader]
         else pure requestedPoints
     followTipStream
       follower
-      (readTipBlockRef chainDb slotTimestamp)
+      (readTipBlockRef nodeKernelAccess slotTimestamp)
       slotTimestamp
       (fetchBlockByChainPoint nodeKernelAccess)
-      (fromIntegral . L.unNonZero $ Consensus.maxRollbacks securityParam)
+      (fromIntegral . L.unNonZero $ Consensus.maxRollbacks (securityParam nodeKernelAccess))
       send
       startPoints
 
@@ -262,7 +265,7 @@ followTipStream
   -> Int
   -- ^ How many applied points to track for undo re-fetch. In production
   -- this is the node's security parameter /k/
-  -- ('Cardano.Rpc.Server.NodeKernelAccess.Type.securityParam'). Consensus
+  -- ('Cardano.Rpc.Server.NodeKernelAccess.securityParam'). Consensus
   -- never rolls back more than /k/ blocks, so tracking /k/ points covers
   -- every rollback the protocol can produce, on any network. An entry
   -- costs roughly 40 bytes, so the window costs about @40 * k@ bytes per
@@ -378,12 +381,12 @@ followTipStream ChainFollower{nextChange, findIntersect} readTip slotTimestamp f
 -- 'mkTipBlockRef', or 'Nothing' at origin.
 readTipBlockRef
   :: MonadIO m
-  => Consensus.ChainDB IO (Consensus.CardanoBlock Consensus.StandardCrypto)
+  => NodeKernelAccess
   -> (SlotNo -> m UTCTime)
   -- ^ Convert a slot to its wall-clock timestamp
   -> m (Maybe (Proto U5c.BlockRef))
-readTipBlockRef chainDb slotTimestamp = do
-  tipHeader <- liftIO $ Consensus.getTipHeader chainDb
+readTipBlockRef nodeKernelAccess slotTimestamp = do
+  tipHeader <- readChainTipHeader nodeKernelAccess
   forM tipHeader $ \header ->
     mkTipBlockRef header <$> slotTimestamp (Consensus.blockSlot header)
 
@@ -396,8 +399,8 @@ slotTimestampOrThrow
   -- ^ Read current era history from the ledger state
   -> SlotNo
   -> m UTCTime
-slotTimestampOrThrow systemStart readEraHistory slot = do
-  eraHistory <- readEraHistory
+slotTimestampOrThrow systemStart readEraHistoryAction slot = do
+  eraHistory <- readEraHistoryAction
   slotToUTCTime systemStart eraHistory slot
     & either (const throwPastHorizon) pure
  where

cardano-rpc/src/Cardano/Rpc/Server/Internal/UtxoRpc/Type.hs

@@ -5,6 +5,7 @@
 module Cardano.Rpc.Server.Internal.UtxoRpc.Type
   ( utxoRpcPParamsToProtocolParams
   , genesisBundleToProto
+  , eraSummariesToProto
   , utxoToUtxoRpcAnyUtxoData
   , txInTxOutToAnyUtxoData
   , anyUtxoDataUtxoRpcToUtxo
@@ -31,6 +32,7 @@ where
 
 import Cardano.Rpc.Server.Internal.UtxoRpc.Type.BigInt
 import Cardano.Rpc.Server.Internal.UtxoRpc.Type.ChainPoint
+import Cardano.Rpc.Server.Internal.UtxoRpc.Type.EraSummary
 import Cardano.Rpc.Server.Internal.UtxoRpc.Type.Genesis
 import Cardano.Rpc.Server.Internal.UtxoRpc.Type.PlutusData
 import Cardano.Rpc.Server.Internal.UtxoRpc.Type.ProtocolParameters