Document ExtensionTxBuilder methods
This commit is contained in:
parent
9d2f388b3b
commit
23634d4cd0
|
@ -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)
|
||||
|
|
|
@ -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,
|
||||
|
|
Loading…
Reference in New Issue