Document how Finalized and NonFinalized clones are different

zebra-state/src/service/finalized_state.rs

@@ -45,8 +45,11 @@ pub(super) use zebra_db::ZebraDb;
 /// The finalized part of the chain state, stored in the db.
 ///
 /// `rocksdb` allows concurrent writes through a shared reference,
-/// so finalized state instances are cloneable. When the final clone is dropped,
-/// the database is closed.
+/// so clones of the finalized state represent the same database instance.
+/// When the final clone is dropped, the database is closed.
+///
+/// This is different from `NonFinalizedState::clone()`,
+/// which returns an independent copy of the chains.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct FinalizedState {
     // Configuration

zebra-state/src/service/non_finalized_state.rs

@@ -30,7 +30,13 @@ mod tests;
 pub(crate) use chain::Chain;
 
 /// The state of the chains in memory, including queued blocks.
-#[derive(Debug, Clone)]
+///
+/// Clones of the non-finalized state contain independent copies of the chains.
+/// This is different from `FinalizedState::clone()`,
+/// which returns a shared reference to the database.
+///
+/// Most chain data is clone-on-write using [`Arc`].
+#[derive(Clone, Debug)]
 pub struct NonFinalizedState {
     /// Verified, non-finalized chains, in ascending order.
     ///