lnrpc/chainrpc: surface re-org depth and Done over the chain notifier

docs/release-notes/release-notes-0.22.0.md

@@ -77,6 +77,14 @@
 
 ## RPC Updates
 
+* The `ChainNotifier` confirmation and spend notification streams are now
+  [richer at the re-org boundary](https://github.com/lightningnetwork/lnd/pull/10943):
+  the `Reorg` message carries the re-org `depth` (populated for confirmation
+  notifications), and a new `Done` event is sent once a watch reaches the
+  backend's re-org safety depth. Previously the re-org depth was dropped and the
+  done signal was conveyed only by closing the stream, which callers could not
+  distinguish from an unrelated teardown.
+
 ## lncli Updates
 
 ## Breaking Changes

lnrpc/chainrpc/chain_server.go

@@ -439,27 +439,40 @@ func (s *Server) RegisterConfirmationsNtfn(in *ConfRequest,
 			}
 
 		// The transaction satisfying the request has been reorged out
-		// of the chain, so we'll send an event describing it.
-		case _, ok := <-confEvent.NegativeConf:
+		// of the chain, so we'll send an event describing it. The depth
+		// of the re-org is forwarded so reorg-safety-aware callers can
+		// reason about how far the chain rewound.
+		case depth, ok := <-confEvent.NegativeConf:
 			if !ok {
 				return chainntnfs.ErrChainNotifierShuttingDown
 			}
 
 			reorg := &ConfEvent{
-				Event: &ConfEvent_Reorg{Reorg: &Reorg{}},
+				Event: &ConfEvent_Reorg{
+					Reorg: &Reorg{Depth: uint32(depth)},
+				},
 			}
 			if err := confStream.Send(reorg); err != nil {
 				return err
 			}
 
 		// The transaction satisfying the request has confirmed and is
-		// no longer under the risk of being reorged out of the chain,
-		// so we can safely exit.
+		// no longer under the risk of being reorged out of the chain.
+		// Send an explicit Done event before exiting so callers can
+		// distinguish reaching re-org safety depth from the stream
+		// being torn down for any other reason.
 		case _, ok := <-confEvent.Done:
 			if !ok {
 				return chainntnfs.ErrChainNotifierShuttingDown
 			}
 
+			done := &ConfEvent{
+				Event: &ConfEvent_Done{Done: &Done{}},
+			}
+			if err := confStream.Send(done); err != nil {
+				return err
+			}
+
 			return nil
 
 		// The response stream's context for whatever reason has been
@@ -565,12 +578,21 @@ func (s *Server) RegisterSpendNtfn(in *SpendRequest,
 
 		// The spending transaction of the requests has confirmed
 		// on-chain and is no longer under the risk of being reorged out
-		// of the chain, so we can safely exit.
+		// of the chain. Send an explicit Done event before exiting so
+		// callers can distinguish reaching re-org safety depth from the
+		// stream being torn down for any other reason.
 		case _, ok := <-spendEvent.Done:
 			if !ok {
 				return chainntnfs.ErrChainNotifierShuttingDown
 			}
 
+			done := &SpendEvent{
+				Event: &SpendEvent_Done{Done: &Done{}},
+			}
+			if err := spendStream.Send(done); err != nil {
+				return err
+			}
+
 			return nil
 
 		// The response stream's context for whatever reason has been