bit_machine: replace ExecTracker API with a much more general one

This replaces the `ExecTracker` API with one which is able to detect
every node, not just cases and jets; which is able to read the input
value for every node (as a bit iterator which can be converted to a
value with Value::from_padded_bits) and the output value for terminal
nodes; and which can do all the existing things that the tracker can
do.

I suspect we want to add some examples or unit tests, in particular
around "debug nodes".

Fixes #324

Author: apoelstra

src/bit_machine/frame.rs

@@ -43,6 +43,19 @@ impl Frame {
         self.len
     }
 
+    /// Makes a copy of the frame.
+    ///
+    /// This copies *only the indices* and none of the underlying
+    /// data. It is the caller's responsibility to make sure that
+    /// the indices are not invalidated.
+    pub(super) fn shallow_copy(&self) -> Self {
+        Self {
+            cursor: self.cursor,
+            start: self.start,
+            len: self.len,
+        }
+    }
+
     /// Reset the cursor to the start.
     pub(super) fn reset_cursor(&mut self) {
         self.cursor = self.start;

src/bit_machine/mod.rs

@@ -22,7 +22,7 @@ use crate::{Cmr, FailEntropy, Value};
 use frame::Frame;
 
 pub use self::limits::LimitError;
-pub use self::tracker::{ExecTracker, NoTracker, PruneTracker, SetTracker};
+pub use self::tracker::{ExecTracker, NoTracker, NodeOutput, PruneTracker, SetTracker};
 
 /// An iterator over the contents of a read or write frame which yields bits.
 pub type FrameIter<'a> = crate::BitIter<core::iter::Copied<core::slice::Iter<'a, u8>>>;
@@ -271,6 +271,10 @@ impl BitMachine {
         }
 
         'main_loop: loop {
+            // Make a copy of the input frame to give to the tracker.
+            let input_frame = self.read.last().map(Frame::shallow_copy);
+            let mut jet_result = Ok(());
+
             match ip.inner() {
                 node::Inner::Unit => {}
                 node::Inner::Iden => {
@@ -336,32 +340,18 @@ impl BitMachine {
                     let (sum_a_b, _c) = ip.arrow().source.as_product().unwrap();
                     let (a, b) = sum_a_b.as_sum().unwrap();
 
-                    if tracker.is_track_debug_enabled() {
-                        if let node::Inner::AssertL(_, cmr) = ip.inner() {
-                            let mut bits = in_frame.as_bit_iter(&self.data);
-                            // Skips 1 + max(a.bit_width, b.bit_width) - a.bit_width
-                            bits.nth(a.pad_left(b))
-                                .expect("AssertL: unexpected end of frame");
-                            let value = Value::from_padded_bits(&mut bits, _c)
-                                .expect("AssertL: decode `C` value");
-                            tracker.track_dbg_call(cmr, value);
-                        }
-                    }
-
                     match (ip.inner(), choice_bit) {
                         (node::Inner::Case(_, right), true)
                         | (node::Inner::AssertR(_, right), true) => {
                             self.fwd(1 + a.pad_right(b));
                             call_stack.push(CallStack::Back(1 + a.pad_right(b)));
                             call_stack.push(CallStack::Goto(right));
-                            tracker.track_right(ip.ihr());
                         }
                         (node::Inner::Case(left, _), false)
                         | (node::Inner::AssertL(left, _), false) => {
                             self.fwd(1 + a.pad_left(b));
                             call_stack.push(CallStack::Back(1 + a.pad_left(b)));
                             call_stack.push(CallStack::Goto(left));
-                            tracker.track_left(ip.ihr());
                         }
                         (node::Inner::AssertL(_, r_cmr), true) => {
                             return Err(ExecutionError::ReachedPrunedBranch(*r_cmr))
@@ -373,13 +363,43 @@ impl BitMachine {
                     }
                 }
                 node::Inner::Witness(value) => self.write_value(value),
-                node::Inner::Jet(jet) => self.exec_jet(*jet, env, tracker)?,
+                node::Inner::Jet(jet) => {
+                    jet_result = self.exec_jet(*jet, env);
+                }
                 node::Inner::Word(value) => self.write_value(value.as_value()),
                 node::Inner::Fail(entropy) => {
                     return Err(ExecutionError::ReachedFailNode(*entropy))
                 }
             }
 
+            // Notify the tracker.
+            {
+                // Notice that, because the read frame stack is only ever
+                // shortened by `drop_read_frame`, and that method was not
+                // called above, this frame is still valid and correctly
+                // describes the Bit Machine "input" to the current node,
+                // no matter the node.
+                let read_iter = input_frame
+                    .map(|frame| frame.as_bit_iter(&self.data))
+                    .unwrap_or(crate::BitIter::from([].iter().copied()));
+                // See the docs on `tracker::NodeOutput` for more information about
+                // this match.
+                let output = match (ip.inner(), &jet_result) {
+                    (node::Inner::Unit | node::Inner::Iden | node::Inner::Witness(_), _)
+                    | (node::Inner::Jet(_), Ok(_)) => NodeOutput::Success(
+                        self.write
+                            .last()
+                            .map(|r| r.as_bit_iter(&self.data))
+                            .unwrap_or(crate::BitIter::from([].iter().copied())),
+                    ),
+                    (node::Inner::Jet(_), Err(_)) => NodeOutput::JetFailed,
+                    _ => NodeOutput::NonTerminal,
+                };
+                tracker.visit_node(ip, read_iter, output);
+            }
+            // Fail if the jet failed.
+            jet_result?;
+
             ip = loop {
                 match call_stack.pop() {
                     Some(CallStack::Goto(next)) => break next,
@@ -410,12 +430,7 @@ impl BitMachine {
         }
     }
 
-    fn exec_jet<J: Jet, T: ExecTracker<J>>(
-        &mut self,
-        jet: J,
-        env: &J::Environment,
-        tracker: &mut T,
-    ) -> Result<(), JetFailed> {
+    fn exec_jet<J: Jet>(&mut self, jet: J, env: &J::Environment) -> Result<(), JetFailed> {
         use crate::ffi::c_jets::frame_ffi::{c_readBit, c_writeBit, CFrameItem};
         use crate::ffi::c_jets::uword_width;
         use crate::ffi::ffi::UWORD;
@@ -501,15 +516,13 @@ impl BitMachine {
         let output_width = jet.target_ty().to_bit_width();
         // Input buffer is implicitly referenced by input read frame!
         // Same goes for output buffer
-        let (input_read_frame, input_buffer) = unsafe { get_input_frame(self, input_width) };
+        let (input_read_frame, _input_buffer) = unsafe { get_input_frame(self, input_width) };
         let (mut output_write_frame, output_buffer) = unsafe { get_output_frame(output_width) };
 
         let jet_fn = jet.c_jet_ptr();
         let c_env = J::c_jet_env(env);
         let success = jet_fn(&mut output_write_frame, input_read_frame, c_env);
 
-        tracker.track_jet_call(&jet, &input_buffer, &output_buffer, success);
-
         if !success {
             Err(JetFailed)
         } else {

src/bit_machine/tracker.rs

@@ -8,40 +8,60 @@
 //!
 //! It is a private module but all types and traits are re-exported above.
 
-use simplicity_sys::ffi::UWORD;
 use std::collections::HashSet;
 
 use crate::jet::Jet;
-use crate::{Cmr, Ihr, Value};
+use crate::node::Inner;
+use crate::{Ihr, RedeemNode, Value};
 
-/// A type that keeps track of Bit Machine execution.
+/// Write frame of a terminal (childless) Simplicity program node.
 ///
-/// The trait is implemented for [`SetTracker`], that tracks which case branches were executed,
-/// and it is implemented for [`NoTracker`], which is a dummy tracker that is
-/// optimized out by the compiler.
+/// When a terminal node of a program is encountered in the Bit Machine, it
+/// has a well-defined "output": the contents of the topmost write frame in
+/// the machine. In particular, for `witness` nodes this will be the witness
+/// data, for jets it will be the result of the jet, and so on.
 ///
-/// The trait enables us to turn tracking on or off depending on a generic parameter.
-pub trait ExecTracker<J: Jet> {
-    /// Track the execution of the left branch of the case node with the given `ihr`.
-    fn track_left(&mut self, ihr: Ihr);
-
-    /// Track the execution of the right branch of the case node with the given `ihr`.
-    fn track_right(&mut self, ihr: Ihr);
-
-    /// Track the execution of a `jet` call with the given `input_buffer`, `output_buffer`, and call result `success`.
-    fn track_jet_call(
-        &mut self,
-        jet: &J,
-        input_buffer: &[UWORD],
-        output_buffer: &[UWORD],
-        success: bool,
-    );
-
-    /// Track the potential execution of a `dbg!` call with the given `cmr` and `value`.
-    fn track_dbg_call(&mut self, cmr: &Cmr, value: Value);
+/// For non-terminal nodes, the Bit Machine typically does some setup, then
+/// executes the nodes' children, then does some teardown. So at no point is
+/// there a well-defined "output" we can provide.
+#[derive(Debug, Clone)]
+pub enum NodeOutput<'m> {
+    /// Non-terminal node, which has no output.
+    NonTerminal,
+    /// Node was a jet which failed, i.e. aborted the program, and therefore
+    /// has no output.
+    JetFailed,
+    /// Node succeeded. This is its output frame.
+    Success(super::FrameIter<'m>),
+}
 
-    /// Check if tracking debug calls is enabled.
-    fn is_track_debug_enabled(&self) -> bool;
+/// An object which can be used to introspect the execution of the Bit Machine.
+///
+/// If this tracker records accesses to the left and right children of `Case` nodes, you
+/// may want to also implement [`PruneTracker`] so that this data can be used by
+/// [`RedeemNode::prune_with_tracker`] to prune the program. The most straightforward
+/// way to do this is to embed a [`SetTracker`] in your tracker and forward all the trait
+/// methods to that.
+pub trait ExecTracker<J: Jet> {
+    /// Called immediately after a specific node of the program is executed, but before
+    /// its children are executed.
+    ///
+    /// More precisely, this iterates through the through the Simplicity program tree in
+    /// *pre* ordering. That is, for the program `comp iden unit` the nodes will be visited
+    /// in the order `comp`, `iden`, `unit`.
+    ///
+    /// This method can be used for logging, to track left or right accesses of the children of a
+    /// `Case` node (to do this, call `input.peek_bit()`; false means left and true means right),
+    /// to extract debug information (which may be embedded in the hidden CMR in `AssertL`
+    /// and `AssertR` nodes, depending how the program was constructed), and so on.
+    ///
+    /// The provided arguments are:
+    ///   * `node` is the node which was just visited.
+    ///   * `input` is an iterator over the read frame when the node's execution began
+    ///   * for terminal nodes (`witness`, `unit`, `iden` and jets), `output` is an iterator
+    ///     the write frame after the node has executed. See [`NodeOutput`] for more information.
+    fn visit_node(&mut self, _node: &RedeemNode<J>, _input: super::FrameIter, _output: NodeOutput) {
+    }
 }
 
 pub trait PruneTracker<J: Jet>: ExecTracker<J> {
@@ -60,20 +80,21 @@ pub struct SetTracker {
 }
 
 impl<J: Jet> ExecTracker<J> for SetTracker {
-    fn track_left(&mut self, ihr: Ihr) {
-        self.left.insert(ihr);
-    }
-
-    fn track_right(&mut self, ihr: Ihr) {
-        self.right.insert(ihr);
-    }
-
-    fn track_jet_call(&mut self, _: &J, _: &[UWORD], _: &[UWORD], _: bool) {}
-
-    fn track_dbg_call(&mut self, _: &Cmr, _: Value) {}
-
-    fn is_track_debug_enabled(&self) -> bool {
-        false
+    fn visit_node<'d>(
+        &mut self,
+        node: &RedeemNode<J>,
+        mut input: super::FrameIter,
+        _output: NodeOutput,
+    ) {
+        match (node.inner(), input.next()) {
+            (Inner::AssertL(..) | Inner::Case(..), Some(false)) => {
+                self.left.insert(node.ihr());
+            }
+            (Inner::AssertR(..) | Inner::Case(..), Some(true)) => {
+                self.right.insert(node.ihr());
+            }
+            _ => {}
+        }
     }
 }
 
@@ -92,16 +113,21 @@ impl<J: Jet> PruneTracker<J> for SetTracker {
 pub struct NoTracker;
 
 impl<J: Jet> ExecTracker<J> for NoTracker {
-    fn track_left(&mut self, _: Ihr) {}
-
-    fn track_right(&mut self, _: Ihr) {}
-
-    fn track_jet_call(&mut self, _: &J, _: &[UWORD], _: &[UWORD], _: bool) {}
-
-    fn track_dbg_call(&mut self, _: &Cmr, _: Value) {}
-
-    fn is_track_debug_enabled(&self) -> bool {
-        // Set flag to test frame decoding in unit tests
-        cfg!(test)
+    fn visit_node<'d>(
+        &mut self,
+        node: &RedeemNode<J>,
+        mut input: super::FrameIter,
+        output: NodeOutput,
+    ) {
+        if cfg!(test) {
+            // In unit tests, attempt to decode values from the frames, confirming that
+            // decoding works.
+            Value::from_padded_bits(&mut input, &node.arrow().source)
+                .expect("decoding input should work");
+            if let NodeOutput::Success(mut output) = output {
+                Value::from_padded_bits(&mut output, &node.arrow().target)
+                    .expect("decoding output should work");
+            }
+        }
     }
 }