Document ExtensionTxBuilder methods

zcash_extensions/src/transparent/demo.rs

@@ -362,7 +362,7 @@ impl<'a, B: ExtensionTxBuilder<'a>> DemoBuilder<&mut B> {
         self.txn_builder
             .add_tze_output(
                 self.extension_id,
-                transfer_amount, // can this be > prevout.1.value?
+                transfer_amount, 
                 &Precondition::close(hash_2),
             )
             .map_err(DemoBuildError::BaseBuilderError)

zcash_primitives/src/extensions/transparent.rs

@@ -3,6 +3,11 @@
 use crate::transaction::components::{Amount, OutPoint, TzeOut};
 use std::fmt;
 
+/// Binary parsing capability for TZE preconditions & witnesses.
+///
+/// Serialization formats interpreted by implementations of this
+/// trait become consensus-critical upon activation of of the
+/// extension that uses them.
 pub trait FromPayload: Sized {
     type Error;
 
@@ -10,12 +15,23 @@ pub trait FromPayload: Sized {
     fn from_payload(mode: u32, payload: &[u8]) -> Result<Self, Self::Error>;
 }
 
+/// Binary serialization capability for TZE preconditions & witnesses.
+///
+/// Serialization formats used by implementations of this
+/// trait become consensus-critical upon activation of of the
+/// extension that uses them.
 pub trait ToPayload {
     /// Returns a serialized payload and its corresponding mode.
     fn to_payload(&self) -> (u32, Vec<u8>);
 }
 
 /// A condition that can be used to encumber transparent funds.
+///
+/// This struct is an intermediate representation between the 
+/// serialized binary format which is used inside of a transaction
+/// and extension-specific types. The payload field of this struct
+/// is treated as opaque to all but extension corresponding to the
+/// encapsulated extension_id value.
 #[derive(Clone, Debug)]
 pub struct Precondition {
     pub extension_id: u32,
@@ -24,6 +40,8 @@ pub struct Precondition {
 }
 
 impl Precondition {
+    /// Produce the intermediate format for an extension-specific precondition
+    /// type.
     pub fn from<P: ToPayload>(extension_id: u32, value: &P) -> Precondition {
         let (mode, payload) = value.to_payload();
         Precondition {
@@ -33,6 +51,8 @@ impl Precondition {
         }
     }
 
+    /// Attempt to parse an extension-specific precondition value from the 
+    /// intermediate representation.
     pub fn try_to<P: FromPayload>(&self) -> Result<P, P::Error> {
         P::from_payload(self.mode, &self.payload)
     }
@@ -40,6 +60,12 @@ impl Precondition {
 
 /// Data that satisfies the precondition for prior encumbered funds, enabling them to be
 /// spent.
+///
+/// This struct is an intermediate representation between the 
+/// serialized binary format which is used inside of a transaction
+/// and extension-specific types. The payload field of this struct
+/// is treated as opaque to all but extension corresponding to the
+/// encapsulated extension_id value.
 #[derive(Clone, Debug)]
 pub struct Witness {
     pub extension_id: u32,
@@ -48,6 +74,8 @@ pub struct Witness {
 }
 
 impl Witness {
+    /// Produce the intermediate format for an extension-specific witness
+    /// type.
     pub fn from<P: ToPayload>(extension_id: u32, value: &P) -> Witness {
         let (mode, payload) = value.to_payload();
         Witness {
@@ -56,6 +84,12 @@ impl Witness {
             payload,
         }
     }
+
+    /// Attempt to parse an extension-specific witness value from the 
+    /// intermediate representation.
+    pub fn try_to<P: FromPayload>(&self) -> Result<P, P::Error> {
+        P::from_payload(self.mode, &self.payload)
+    }
 }
 
 #[derive(Debug, PartialEq)]
@@ -106,18 +140,27 @@ pub trait Extension<C> {
     }
 }
 
-/// This extension trait is satisfied by [`transaction::builder::Builder`]. It provides a
-/// minimal contract for interacting with the transaction builder, that extension library authors
-/// can use to add extension-specific builder traits that may be used to interact with the
-/// transaction builder.  This may make it simpler for projects that include transaction-builder
-/// functionality to integrate with third-party extensions without those extensions being coupled to
-/// a particular transaction or builder representation.
+/// This extension trait is satisfied by [`transaction::builder::Builder`]. It provides a minimal
+/// contract for interacting with the transaction builder, that extension library authors can use
+/// to add extension-specific builder traits that may be used to interact with the transaction
+/// builder. This may make it simpler for projects that include transaction-builder functionality
+/// to integrate with third-party extensions without those extensions being coupled to a particular
+/// transaction or builder representation.
 ///
 /// [`transaction::builder::Builder`]: crate::transaction::builder::Builder
 pub trait ExtensionTxBuilder<'a> {
     type BuildCtx;
     type BuildError;
 
+    /// Add a TZE input to the transaction under construction by providing a witness
+    /// to a precondition identified by a prior outpoint. 
+    ///
+    /// The `witness_builder` function allows the transaction builder to provide extra
+    /// contextual information from the transaction under construction to be used 
+    /// in the production of this witness (for example, so that the witness may
+    /// internally make commitments based upon this information.) For the standard
+    /// transaction builder, the value provided here is the transaction under
+    /// construction.
     fn add_tze_input<WBuilder, W: ToPayload>(
         &mut self,
         extension_id: u32,
@@ -127,6 +170,8 @@ pub trait ExtensionTxBuilder<'a> {
     where
         WBuilder: 'a + (FnOnce(&Self::BuildCtx) -> Result<W, Self::BuildError>);
 
+    /// Add a TZE precondition to the transaction which must be satisfied by a future
+    /// transaction's witness in order to spend the specified amount.
     fn add_tze_output<P: ToPayload>(
         &mut self,
         extension_id: u32,