update snapshots timings as per review

Author: Cmdv

cardano-db-sync/src/Cardano/DbSync/Config/Types.hs

@@ -281,7 +281,7 @@ data JsonTypeConfig
   deriving (Eq, Show)
 
 data SnapshotIntervalConfig = SnapshotIntervalConfig
-  { sicFollowing :: !Word64
+  { sicNearTipEpoch :: !Word64
   , sicLagging :: !Word64
   }
   deriving (Eq, Show)
@@ -739,20 +739,20 @@ instance FromJSON JsonTypeConfig where
 instance ToJSON SnapshotIntervalConfig where
   toJSON cfg =
     Aeson.object
-      [ "following" .= sicFollowing cfg
+      [ "near_tip_epoch" .= sicNearTipEpoch cfg
       , "lagging" .= sicLagging cfg
       ]
 
 instance FromJSON SnapshotIntervalConfig where
   parseJSON = Aeson.withObject "snapshot_interval" $ \obj ->
     SnapshotIntervalConfig
-      <$> obj .: "following"
-      <*> obj .: "lagging"
+      <$> obj .:? "near_tip_epoch" .!= sicNearTipEpoch def
+      <*> obj .:? "lagging" .!= sicLagging def
 
 instance Default SnapshotIntervalConfig where
   def =
     SnapshotIntervalConfig
-      { sicFollowing = 500 -- Every 500 blocks when near tip
+      { sicNearTipEpoch = 580 -- Epoch threshold to consider being near tip
       , sicLagging = 100000 -- Every 100,000 blocks when syncing (less frequent)
       }
 

cardano-db-sync/src/Cardano/DbSync/Ledger/State.hs

@@ -186,7 +186,7 @@ mkHasLedgerEnv trce protoInfo dir nw systemStart syncOptions = do
       , leNetwork = nw
       , leSystemStart = systemStart
       , leAbortOnPanic = soptAbortOnInvalid syncOptions
-      , leSnapshotEveryFollowing = sicFollowing $ soptSnapshotInterval syncOptions
+      , leSnapshotNearTipEpoch = sicNearTipEpoch $ soptSnapshotInterval syncOptions
       , leSnapshotEveryLagging = sicLagging $ soptSnapshotInterval syncOptions
       , leInterpreter = intervar
       , leStateVar = svar
@@ -218,7 +218,8 @@ readStateUnsafe env = do
 applyBlockAndSnapshot :: HasLedgerEnv -> CardanoBlock -> Bool -> IO (ApplyResult, Bool)
 applyBlockAndSnapshot ledgerEnv blk isCons = do
   (oldState, appResult) <- applyBlock ledgerEnv blk
-  tookSnapshot <- storeSnapshotAndCleanupMaybe ledgerEnv oldState appResult (blockNo blk) isCons (isSyncedWithinSeconds (apSlotDetails appResult) 600)
+  -- 864000 seconds = 10 days; consider synced "near tip" if within 10 days of current time
+  tookSnapshot <- storeSnapshotAndCleanupMaybe ledgerEnv oldState appResult (blockNo blk) isCons (isSyncedWithinSeconds (apSlotDetails appResult) 864000)
   pure (appResult, tookSnapshot)
 
 -- The function 'tickThenReapply' does zero validation, so add minimal validation ('blockPrevHash'
@@ -330,8 +331,8 @@ storeSnapshotAndCleanupMaybe env oldState appResult blkNo isCons syncState =
     Just newEpoch
       | newEpochNo <- unEpochNo (Generic.neEpoch newEpoch)
       , newEpochNo > 0
-      , -- Snapshot every epoch when near tip, every 10 epochs when lagging, or always for epoch >= 580
-        (isCons && syncState == SyncFollowing) || (newEpochNo `mod` 10 == 0) || newEpochNo >= 580 ->
+      , -- Snapshot every epoch when near tip, every 10 epochs when lagging, or always for epoch >= threshold
+        (isCons && syncState == SyncFollowing) || (newEpochNo `mod` 10 == 0) || newEpochNo >= leSnapshotNearTipEpoch env ->
           do
             -- TODO: Instead of newEpochNo - 1, is there any way to get the epochNo from 'lssOldState'?
             liftIO $ saveCleanupState env oldState (Just $ EpochNo $ newEpochNo - 1)
@@ -346,8 +347,8 @@ storeSnapshotAndCleanupMaybe env oldState appResult blkNo isCons syncState =
     timeToSnapshot :: SyncState -> BlockNo -> Bool
     timeToSnapshot syncSt bNo =
       case (syncSt, unBlockNo bNo) of
-        (SyncFollowing, bno) -> bno `mod` leSnapshotEveryFollowing env == 0
-        (SyncLagging, _) -> False
+        (SyncFollowing, _) -> False -- No block-based snapshots when following
+        (SyncLagging, bno) -> bno `mod` leSnapshotEveryLagging env == 0
 
 saveCurrentLedgerState :: HasLedgerEnv -> CardanoLedgerState -> Maybe EpochNo -> IO ()
 saveCurrentLedgerState env lState mEpochNo = do

cardano-db-sync/src/Cardano/DbSync/Ledger/Types.hs

@@ -67,7 +67,7 @@ data HasLedgerEnv = HasLedgerEnv
   , leNetwork :: !Ledger.Network
   , leSystemStart :: !SystemStart
   , leAbortOnPanic :: !Bool
-  , leSnapshotEveryFollowing :: !Word64
+  , leSnapshotNearTipEpoch :: !Word64
   , leSnapshotEveryLagging :: !Word64
   , leInterpreter :: !(StrictTVar IO (Strict.Maybe CardanoInterpreter))
   , leStateVar :: !(StrictTVar IO (Strict.Maybe LedgerDB))

doc/configuration.md

@@ -616,17 +616,17 @@ Snapshot Interval Properties:
 
 | Property                         | Type      | Required | Default |
 | :------------------------------- | :-------- | :------- | :------ |
-| [following](#following)          | `integer` | Optional | 500     |
+| [near\_tip\_epoch](#near-tip-epoch) | `integer` | Optional | 580     |
 | [lagging](#lagging)              | `integer` | Optional | 100000  |
 
-### Following
+### Near Tip Epoch
 
-`snapshot_interval.following`
+`snapshot_interval.near_tip_epoch`
 
 * Type: `integer`
-* Default: `500`
+* Default: `580`
 
-Number of blocks between snapshots when db-sync is near the tip of the chain (within approximately 10 minutes). More frequent snapshots when following the tip ensure faster recovery from rollbacks.
+Epoch threshold used to determine snapshot behavior. When syncing reaches this epoch or later, db-sync is considered to be approaching or at the current tip of the chain. Combined with time-based detection (within 10 days of current time), this ensures snapshots are taken every epoch when near the tip for fast rollback recovery. During earlier epochs or when syncing behind, snapshots are taken every 10 epochs or according to the `lagging` block interval.
 
 ### Lagging
 
@@ -635,23 +635,24 @@ Number of blocks between snapshots when db-sync is near the tip of the chain (wi
 * Type: `integer`
 * Default: `100000`
 
-Number of blocks between snapshots when db-sync is syncing and significantly behind the tip of the chain. Less frequent snapshots during initial sync improves performance by reducing expensive disk operations.
+Number of blocks between snapshots when db-sync is syncing and significantly behind the tip of the chain (more than 10 days behind current time). Less frequent snapshots during initial sync improves performance by reducing expensive disk operations.
 
 ### Example
 
 ```json
 {
   "snapshot_interval": {
-    "following": 500,
+    "near_tip_epoch": 580,
     "lagging": 100000
   }
 }
 ```
 
 ### Performance Considerations
 
-- **Smaller `following` value**: Faster recovery from rollbacks when near the tip, but more frequent disk writes
+- **Lower `near_tip_epoch` value**: Start taking frequent epoch-based snapshots earlier in the chain history
+- **Higher `near_tip_epoch` value**: Delay frequent snapshots until later in the chain, improving sync speed for longer
 - **Larger `lagging` value**: Faster initial sync with reduced IOPS, but slower recovery if rollback is needed during sync
-- **Recommended for initial sync**: Use a large `lagging` value (50000-100000) to maximise sync speed
-- **Recommended when near tip**: Use a small `following` value (500-1000) to enable quick rollback recovery
+- **Recommended for initial sync**: Use a large `lagging` value (100000+) and appropriate `near_tip_epoch` to maximize sync speed
+- **Near tip detection**: Automatically switches to epoch-based snapshots when within 10 days of current time, regardless of epoch number