Document why we do a UTXO check that looks redundant (#5106)

Also inline the call stack for the check, so it is efficient.

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

zebra-state/src/service.rs

@@ -669,6 +669,14 @@ impl Service<Request> for StateService {
 
                 let timer = CodeTimer::start();
 
+                // # Consensus
+                //
+                // A non-finalized block verification could have called AwaitUtxo
+                // before this finalized block arrived in the state.
+                // So we need to check for pending UTXOs here for non-finalized blocks,
+                // even though it is redundant for most finalized blocks.
+                // (Finalized blocks are verified using block hash checkpoints
+                // and transaction merkle tree block header commitments.)
                 self.pending_utxos.check_against(&finalized.new_outputs);
 
                 // # Performance

zebra-state/src/service/pending_utxos.rs

@@ -38,6 +38,7 @@ impl PendingUtxos {
     /// Notify all requests waiting for the [`transparent::Utxo`] pointed to by
     /// the given [`transparent::OutPoint`] that the [`transparent::Utxo`] has
     /// arrived.
+    #[inline]
     pub fn respond(&mut self, outpoint: &transparent::OutPoint, utxo: transparent::Utxo) {
         if let Some(sender) = self.0.remove(outpoint) {
             // Adding the outpoint as a field lets us cross-reference
@@ -59,6 +60,7 @@ impl PendingUtxos {
     }
 
     /// Check the list of pending UTXO requests against the supplied [`transparent::Utxo`] index.
+    #[inline]
     pub fn check_against(&mut self, utxos: &HashMap<transparent::OutPoint, transparent::Utxo>) {
         for (outpoint, utxo) in utxos.iter() {
             self.respond(outpoint, utxo.clone())