From f11a6b4ff17b9155fcf1d0b3228d2cbdcbd0f846 Mon Sep 17 00:00:00 2001
From: Luke Parker <lukeparker5132@gmail.com>
Date: Mon, 2 Sep 2024 22:31:15 -0400
Subject: [PATCH] Better document the forwarded output flow

---
 processor/primitives/src/eventuality.rs  |  7 +++++--
 processor/scanner/src/eventuality/mod.rs | 15 ++++++++++-----
 processor/scanner/src/lib.rs             | 10 ++++++++++
 3 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/processor/primitives/src/eventuality.rs b/processor/primitives/src/eventuality.rs
index eb6cda9c..6a52194d 100644
--- a/processor/primitives/src/eventuality.rs
+++ b/processor/primitives/src/eventuality.rs
@@ -19,8 +19,11 @@ pub trait Eventuality: Sized + Send + Sync {
   /// identified, the full check is performed.
   fn lookup(&self) -> Vec<u8>;
 
-  /// The output this plan forwarded.
-  fn forwarded_output(&self) -> Option<Self::OutputId>;
+  /// The output the resolution of this Eventuality was supposed to spend.
+  ///
+  /// If the resolution of this Eventuality has multiple inputs, there is no singular spent output
+  /// so this MUST return None.
+  fn singular_spent_output(&self) -> Option<Self::OutputId>;
 
   /// Read an Eventuality.
   fn read(reader: &mut impl io::Read) -> io::Result<Self>;
diff --git a/processor/scanner/src/eventuality/mod.rs b/processor/scanner/src/eventuality/mod.rs
index 83ec50ab..98d278d9 100644
--- a/processor/scanner/src/eventuality/mod.rs
+++ b/processor/scanner/src/eventuality/mod.rs
@@ -352,19 +352,24 @@ impl<D: Db, S: ScannerFeed, Sch: Scheduler<S>> ContinuallyRan for EventualityTas
           non_external_outputs.iter().filter(|output| output.kind() == OutputType::Forwarded)
         {
           let Some(eventuality) = completed_eventualities.get(&output.transaction_id()) else {
-            // Output sent to the forwarding address yet not actually forwarded
+            // Output sent to the forwarding address yet not one we made
             continue;
           };
-          let Some(forwarded) = eventuality.forwarded_output() else {
-            // This was a TX made by us, yet someone burned to the forwarding address
+          let Some(forwarded) = eventuality.singular_spent_output() else {
+            // This was a TX made by us, yet someone burned to the forwarding address as it doesn't
+            // follow the structure of forwarding transactions
             continue;
           };
 
-          let (return_address, in_instruction) =
+          let Some((return_address, in_instruction)) =
             ScannerGlobalDb::<S>::return_address_and_in_instruction_for_forwarded_output(
               &txn, &forwarded,
             )
-            .expect("forwarded an output yet didn't save its InInstruction to the DB");
+          else {
+            // This was a TX made by us, coincidentally with the necessary structure, yet wasn't
+            // forwarding an output
+            continue;
+          };
           queue_output_until_block::<S>(
             &mut txn,
             b + S::WINDOW_LENGTH,
diff --git a/processor/scanner/src/lib.rs b/processor/scanner/src/lib.rs
index d894f819..539bd4a7 100644
--- a/processor/scanner/src/lib.rs
+++ b/processor/scanner/src/lib.rs
@@ -216,14 +216,24 @@ pub struct SchedulerUpdate<S: ScannerFeed> {
 
 impl<S: ScannerFeed> SchedulerUpdate<S> {
   /// The outputs to accumulate.
+  ///
+  /// These MUST be accumulated.
   pub fn outputs(&self) -> &[OutputFor<S>] {
     &self.outputs
   }
+
   /// The outputs to forward to the latest multisig.
+  ///
+  /// These MUST be forwarded in a 1-input 1-output transaction or dropped (if the fees are too
+  /// high to make the forwarding transaction).
   pub fn forwards(&self) -> &[OutputFor<S>] {
     &self.forwards
   }
+
   /// The outputs to return.
+  ///
+  /// These SHOULD be returned as specified (potentially in batch). They MAY be dropped if the fees
+  /// are too high to make the return transaction.
   pub fn returns(&self) -> &[Return<S>] {
     &self.returns
   }