cardano-rpc: Implement FollowTip SyncService method

.changes/20260722_cardano_api_chaindb_follower_reexports.yml

@@ -0,0 +1,6 @@
+project: cardano-api
+pr: 1268
+kind:
+  - compatible
+description: |
+  Re-export the ChainDB follower API from Cardano.Api.Consensus: newFollower, Follower, ChainType, ChainUpdate, withRegistry, ResourceRegistry, configSecurityParam and SecurityParam.

.changes/20260722_cardano_rpc_follow_tip.yml

@@ -0,0 +1,6 @@
+project: cardano-rpc
+pr: 1268
+kind:
+  - feature
+description: |
+  Implement the FollowTip SyncService method: streams fully parsed blocks as the chain advances, starting from the first intersection point found on the chain (an empty-hash block ref denotes origin). An empty intersect list follows from the current tip; an unmatched intersect list fails with NOT_FOUND. Rollbacks are delivered as undo actions carrying the rolled-back blocks where they can be reconstructed from ChainDB, falling back to reset otherwise.

cardano-api/cardano-api.cabal

@@ -184,6 +184,7 @@ library
     prettyprinter-ansi-terminal,
     prettyprinter-configurable ^>=1.36,
     random,
+    resource-registry ^>=0.2,
     safe-exceptions,
     scientific,
     serialise,

cardano-api/src/Cardano/Api/Consensus.hs

@@ -52,22 +52,29 @@ module Cardano.Api.Consensus
   , ByronBlock
   , CardanoBlock
   , ChainDB.ChainDB
+  , ChainDB.ChainType (..)
+  , ChainDB.Follower (..)
   , ChainDB.getBlockComponent
   , ChainDB.getCurrentLedger
   , ChainDB.getTipHeader
+  , ChainDB.newFollower
+  , ChainUpdate (..)
   , ConfigSupportsNode
   , ChainDepState
   , GenTx (..)
   , EraMismatch (..)
   , HasHardForkHistory (..)
   , HasHeader
+  , Header
   , HeaderHash
   , NodeKernel (..)
   , OneEraHash (..)
   , PastHorizonException
   , PraosProtocolSupportsNode
   , PraosProtocolSupportsNodeCrypto
   , RealPoint (..)
+  , ResourceRegistry
+  , SecurityParam (..)
   , ShelleyGenesisStaking (..)
   , StandardCrypto
   , TopLevelConfig
@@ -79,12 +86,14 @@ module Cardano.Api.Consensus
   , byronIdTx
   , configBlock
   , configLedger
+  , configSecurityParam
   , condense
   , getOpCertCounters
   , interpreterToEpochInfo
   , mkInterpreter
   , unsafeExtendSafeZone
   , txId
+  , withRegistry
   )
 where
 

cardano-api/src/Cardano/Api/Consensus/Internal/Reexport.hs

@@ -2,10 +2,12 @@ module Cardano.Api.Consensus.Internal.Reexport
   ( BlockComponent (..)
   , ByronBlock
   , CardanoBlock
+  , ChainUpdate (..)
   , ConfigSupportsNode
   , ChainDepState
   , GenTx (..)
   , HasHeader
+  , Header
   , HeaderHash
   , EraMismatch (..)
   , NodeKernel (..)
@@ -15,6 +17,8 @@ module Cardano.Api.Consensus.Internal.Reexport
   , PraosProtocolSupportsNode
   , PraosProtocolSupportsNodeCrypto
   , RealPoint (..)
+  , ResourceRegistry
+  , SecurityParam (..)
   , ShelleyGenesisStaking (..)
   , StandardCrypto
   , TopLevelConfig
@@ -26,18 +30,21 @@ module Cardano.Api.Consensus.Internal.Reexport
   , byronIdTx
   , configBlock
   , configLedger
+  , configSecurityParam
   , condense
   , getOpCertCounters
   , interpreterToEpochInfo
   , mkInterpreter
   , unsafeExtendSafeZone
   , txId
+  , withRegistry
   )
 where
 
 import Cardano.Protocol.Crypto (StandardCrypto)
 import Ouroboros.Consensus.Block
   ( HasHeader
+  , Header
   , HeaderHash
   , RealPoint (..)
   , blockHash
@@ -46,7 +53,13 @@ import Ouroboros.Consensus.Block
   )
 import Ouroboros.Consensus.Byron.Ledger (ByronBlock (byronBlockRaw), GenTx (..), byronIdTx)
 import Ouroboros.Consensus.Cardano.Block (CardanoBlock, EraMismatch (..))
-import Ouroboros.Consensus.Config (TopLevelConfig, configBlock, configLedger)
+import Ouroboros.Consensus.Config
+  ( TopLevelConfig
+  , configBlock
+  , configLedger
+  , configSecurityParam
+  )
+import Ouroboros.Consensus.Config.SecurityParam (SecurityParam (..))
 import Ouroboros.Consensus.Config.SupportsNode (ConfigSupportsNode)
 import Ouroboros.Consensus.HardFork.Abstract (HasHardForkHistory (..))
 import Ouroboros.Consensus.HardFork.Combinator.AcrossEras (OneEraHash (..))
@@ -68,3 +81,6 @@ import Ouroboros.Consensus.Protocol.Praos.Common
 import Ouroboros.Consensus.Shelley.Node (ShelleyGenesisStaking (..))
 import Ouroboros.Consensus.Storage.Common (BlockComponent (..))
 import Ouroboros.Consensus.Util.Condense (condense)
+import Ouroboros.Network.Block (ChainUpdate (..))
+
+import Control.ResourceRegistry (ResourceRegistry, withRegistry)

cardano-rpc/README.md

@@ -35,7 +35,7 @@ It implements [UTxO RPC](https://utxorpc.org/introduction) protobuf communicatio
 |--------|--------|
 | [FetchBlock](https://utxorpc.org/sync/spec/#fetchblockrequest) | ✅ Supported |
 | [DumpHistory](https://utxorpc.org/sync/spec/#dumphistoryrequest) | ⬜ Not supported |
-| [FollowTip](https://utxorpc.org/sync/spec/#followtiprequest) | ⬜ Not supported |
+| [FollowTip](https://utxorpc.org/sync/spec/#followtiprequest) | ✅ Supported |
 | [ReadTip](https://utxorpc.org/sync/spec/#readtiprequest) | ✅ Supported |
 
 ### [WatchService](https://utxorpc.org/watch/spec/)

cardano-rpc/cardano-rpc.cabal

@@ -66,6 +66,7 @@ library
     Cardano.Rpc.Server.Internal.UtxoRpc.Sync
     Cardano.Rpc.Server.Internal.UtxoRpc.Type
     Cardano.Rpc.Server.Internal.UtxoRpc.Type.BigInt
+    Cardano.Rpc.Server.Internal.UtxoRpc.Type.Block
     Cardano.Rpc.Server.Internal.UtxoRpc.Type.Byron
     Cardano.Rpc.Server.Internal.UtxoRpc.Type.Certificate
     Cardano.Rpc.Server.Internal.UtxoRpc.Type.ChainPoint
@@ -173,6 +174,7 @@ test-suite cardano-rpc-test
     hedgehog,
     hedgehog-extras,
     memory,
+    ouroboros-consensus:cardano,
     proto-lens,
     rio,
     tasty,
@@ -191,6 +193,7 @@ test-suite cardano-rpc-test
     Test.Cardano.Rpc.ByronTx
     Test.Cardano.Rpc.Eval
     Test.Cardano.Rpc.FetchBlockTx
+    Test.Cardano.Rpc.FollowTipStream
     Test.Cardano.Rpc.Pagination
     Test.Cardano.Rpc.Predicate
     Test.Cardano.Rpc.ProtocolParameters

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

@@ -84,7 +84,7 @@ methodsSyncRpc
 methodsSyncRpc =
   Method (mkNonStreaming $ const unimplemented) -- dumpHistory
     . Method (mkNonStreaming $ wrapInSpan TraceRpcFetchBlockSpan . fetchBlockMethod)
-    . Method (mkServerStreaming $ \_ _ -> unimplemented) -- followTip
+    . Method (mkServerStreaming $ \req -> wrapInSpan TraceRpcFollowTipSpan . followTipMethod req)
     . Method (mkNonStreaming $ wrapInSpan TraceRpcReadTipSpan . readTipMethod)
     $ NoMoreMethods
  where

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

@@ -101,12 +101,12 @@ data TraceRpcSync
     TraceRpcFetchBlockSpan TraceSpanEvent
   | -- | ReadTip span
     TraceRpcReadTipSpan TraceSpanEvent
+  | -- | FollowTip span
+    TraceRpcFollowTipSpan TraceSpanEvent
   | -- | Requested block was not found
     TraceRpcFetchBlockNotFound SlotNo
   | -- | Node kernel access is not yet available
     TraceRpcNodeKernelAccessUnavailable
-  | -- | Ledger forker error
-    TraceRpcForkerError String
   deriving Show
 
 instance Pretty TraceRpcSync where
@@ -115,9 +115,10 @@ instance Pretty TraceRpcSync where
     TraceRpcFetchBlockSpan (SpanEnd _) -> "Finished FetchBlock method"
     TraceRpcReadTipSpan (SpanBegin _) -> "Started ReadTip method"
     TraceRpcReadTipSpan (SpanEnd _) -> "Finished ReadTip method"
+    TraceRpcFollowTipSpan (SpanBegin _) -> "Started FollowTip method"
+    TraceRpcFollowTipSpan (SpanEnd _) -> "Finished FollowTip method"
     TraceRpcFetchBlockNotFound slot -> "Block not found at slot " <> pshow slot
     TraceRpcNodeKernelAccessUnavailable -> "Node kernel access not yet initialised"
-    TraceRpcForkerError e -> "Ledger forker error: " <> pretty e
 
 instance Error TraceRpcSync where
   prettyError = pretty