Clairify LedgerPeersConsensusInterface.

- Rename getBlockHash to getImmutableBlockPoint.
- The callback in getImmutableBlockPoint now has a dedicated GetImmutableBlockPointError error type.

Author: geo2a

cardano-diffusion/changelog.d/20260504_105437_geo2a_consensus_issue_1852.md

@@ -0,0 +1,25 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+For top level release notes, leave all the headers commented out.
+-->
+
+
+### Breaking
+
+- Rename `getBlockHash` to `getImmutableBlockPoint` to better reflect that it queries the immutable DB and returns a `Point`.
+- Change the return type of `getBlockHash` (renamed to `getImmutableBlockPoint`) from `Maybe (Point RawBlockHash)` to `Either GetImmutableBlockPointError (Point RawBlockHash)`, replacing an opaque `Nothing` with structured error information.
+
+<!--
+### Non-Breaking
+
+- A bullet item for the Non-Breaking category.
+
+-->
+<!--
+### Patch
+
+- A bullet item for the Patch category.
+
+-->

cardano-diffusion/lib/Cardano/Network/LedgerPeerConsensusInterface.hs

@@ -2,6 +2,7 @@
 
 module Cardano.Network.LedgerPeerConsensusInterface
   ( LedgerPeersConsensusInterface (..)
+  , GetImmutableBlockPointError (..)
     -- * Re-exports
   , FetchMode (..)
   , LedgerStateJudgement (..)
@@ -18,6 +19,20 @@ import Ouroboros.Network.BlockFetch.ConsensusInterface (FetchMode (..))
 import Ouroboros.Network.PeerSelection.LedgerPeers.Type (RawBlockHash)
 
 
+-- | Error returned by 'getImmutableBlockPoint'.
+--
+data GetImmutableBlockPointError
+  = -- | Genesis point was provided as the target, which has no slot or hash
+    -- to look up.
+    ImmutableBlockPointGenesisPoint
+  | -- | The block was not found in ImmutableDB because the target slot
+    -- is not yet immutable.
+    ImmutableBlockPointNotYetImmutable
+  | -- | ImmutableDB is empty (tip is at origin).
+    ImmutableBlockPointTipIsOrigin
+  deriving (Show, Eq)
+
+
 -- | Cardano Node specific consensus interface actions.
 --
 data LedgerPeersConsensusInterface m =
@@ -39,6 +54,8 @@ data LedgerPeersConsensusInterface m =
   -- | Ask the Consensus layer's immutable DB for a point. The callback will yield either:
   --   - the block at the target slot if there is a block in the immutable DB at that slot;
   --   - or the block from the next occupied slot.
-  , getBlockHash
-      :: forall r. Point RawBlockHash -> (m (Maybe (Point RawBlockHash)) -> m r) -> m r
+  , getImmutableBlockPoint
+      :: forall r. Point RawBlockHash
+      -> (m (Either GetImmutableBlockPointError (Point RawBlockHash)) -> m r)
+      -> m r
   }

cardano-diffusion/lib/Cardano/Network/PeerSelection/Governor/Monitor.hs

@@ -691,7 +691,7 @@ jobVerifyPeerSnapshot :: MonadSTM m
                       -> Cardano.LedgerPeersConsensusInterface m
                       -> Job () m (Completion m extraState extraDebugState extraFlags extraPeers peeraddr peerconn)
 jobVerifyPeerSnapshot (slotNo, fileHash)
-                      Cardano.LedgerPeersConsensusInterface { getBlockHash }
+                      Cardano.LedgerPeersConsensusInterface { getImmutableBlockPoint }
   = Job job (const (completion False)) () "jobVerifyPeerSnapshot"
   where
     completion result = return . Completion $ \st _now ->
@@ -700,9 +700,9 @@ jobVerifyPeerSnapshot (slotNo, fileHash)
         decisionState = st,
         decisionJobs  = [] }
 
-    job = getBlockHash (BlockPoint slotNo fileHash) $ \promise -> do
+    job = getImmutableBlockPoint (BlockPoint slotNo fileHash) $ \promise -> do
       waited <- promise
       case waited of
-        Just (BlockPoint { withHash }) -> do
+        Right (BlockPoint { withHash }) -> do
           completion $ fileHash == withHash
         _otherwise -> completion False

cardano-diffusion/tests/lib/Test/Cardano/Network/Diffusion/Testnet/Simulation.hs

@@ -1273,7 +1273,7 @@ diffusionSimulationM
                     Cardano.LedgerPeersConsensusInterface {
                       Cardano.readFetchMode = pure (PraosFetchMode FetchModeDeadline)
                     , Cardano.getLedgerStateJudgement = pure TooOld
-                    , Cardano.getBlockHash = error "getBlockHash not implemented"
+                    , Cardano.getImmutableBlockPoint = error "getImmutableBlockPoint not implemented"
                     , Cardano.updateOutboundConnectionsState =
                         \a -> do
                           a' <- readTVar onlyOutboundConnectionsStateVar

cardano-diffusion/tests/lib/Test/Cardano/Network/PeerSelection.hs

@@ -4324,7 +4324,7 @@ _governorFindingPublicRoots targetNumberOfRootPeers readDomains readUseBootstrap
                     lpExtraAPI = Cardano.LedgerPeersConsensusInterface {
                       readFetchMode = pure (PraosFetchMode FetchModeDeadline),
                       getLedgerStateJudgement = readLedgerStateJudgement,
-                      getBlockHash = error "getBlockHash not implemented",
+                      getImmutableBlockPoint = error "getImmutableBlockPoint not implemented",
                       updateOutboundConnectionsState = \a -> do
                         a' <- readTVar olocVar
                         when (a /= a') $

cardano-diffusion/tests/lib/Test/Cardano/Network/PeerSelection/MockEnvironment.hs

@@ -486,7 +486,7 @@ mockPeerSelectionActions' tracer
           lpExtraAPI = Cardano.LedgerPeersConsensusInterface {
             readFetchMode = pure (PraosFetchMode FetchModeDeadline),
             getLedgerStateJudgement = readLedgerStateJudgement,
-            getBlockHash = error "getBlockHash not implemented",
+            getImmutableBlockPoint = error "getImmutableBlockPoint not implemented",
             updateOutboundConnectionsState = \a -> do
               a' <- readTVar outboundConnectionsStateVar
               when (a /= a') $