1 files changed, 11 insertions, 0 deletions
diff --git a/src/validationinterface.h b/src/validationinterface.h
index 6089bc2b3c..3a5fed0106 100644
--- a/src/validationinterface.h
+++ b/src/validationinterface.h
@@ -99,6 +99,17 @@ protected:
     /**
      * Notifies listeners of the new active block chain on-disk.
      *
+     * Prior to this callback, any updates are not guaranteed to persist on disk
+     * (ie clients need to handle shutdown/restart safety by being able to
+     * understand when some updates were lost due to unclean shutdown).
+     *
+     * When this callback is invoked, the validation changes done by any prior
+     * callback are guaranteed to exist on disk and survive a restart, including
+     * an unclean shutdown.
+     *
+     * Provides a locator describing the best chain, which is likely useful for
+     * storing current state on disk in client DBs.
+     *
      * Called on a background thread.
      */
     virtual void ChainStateFlushed(const CBlockLocator &locator) {}