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
|
self.txn_builder
|
||||||
.add_tze_output(
|
.add_tze_output(
|
||||||
self.extension_id,
|
self.extension_id,
|
||||||
transfer_amount, // can this be > prevout.1.value?
|
transfer_amount,
|
||||||
&Precondition::close(hash_2),
|
&Precondition::close(hash_2),
|
||||||
)
|
)
|
||||||
.map_err(DemoBuildError::BaseBuilderError)
|
.map_err(DemoBuildError::BaseBuilderError)
|
||||||
|
|
|
@ -3,6 +3,11 @@
|
||||||
use crate::transaction::components::{Amount, OutPoint, TzeOut};
|
use crate::transaction::components::{Amount, OutPoint, TzeOut};
|
||||||
use std::fmt;
|
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 {
|
pub trait FromPayload: Sized {
|
||||||
type Error;
|
type Error;
|
||||||
|
|
||||||
|
@ -10,12 +15,23 @@ pub trait FromPayload: Sized {
|
||||||
fn from_payload(mode: u32, payload: &[u8]) -> Result<Self, Self::Error>;
|
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 {
|
pub trait ToPayload {
|
||||||
/// Returns a serialized payload and its corresponding mode.
|
/// Returns a serialized payload and its corresponding mode.
|
||||||
fn to_payload(&self) -> (u32, Vec<u8>);
|
fn to_payload(&self) -> (u32, Vec<u8>);
|
||||||
}
|
}
|
||||||
|
|
||||||
/// A condition that can be used to encumber transparent funds.
|
/// 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)]
|
#[derive(Clone, Debug)]
|
||||||
pub struct Precondition {
|
pub struct Precondition {
|
||||||
pub extension_id: u32,
|
pub extension_id: u32,
|
||||||
|
@ -24,6 +40,8 @@ pub struct Precondition {
|
||||||
}
|
}
|
||||||
|
|
||||||
impl Precondition {
|
impl Precondition {
|
||||||
|
/// Produce the intermediate format for an extension-specific precondition
|
||||||
|
/// type.
|
||||||
pub fn from<P: ToPayload>(extension_id: u32, value: &P) -> Precondition {
|
pub fn from<P: ToPayload>(extension_id: u32, value: &P) -> Precondition {
|
||||||
let (mode, payload) = value.to_payload();
|
let (mode, payload) = value.to_payload();
|
||||||
Precondition {
|
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> {
|
pub fn try_to<P: FromPayload>(&self) -> Result<P, P::Error> {
|
||||||
P::from_payload(self.mode, &self.payload)
|
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
|
/// Data that satisfies the precondition for prior encumbered funds, enabling them to be
|
||||||
/// spent.
|
/// 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)]
|
#[derive(Clone, Debug)]
|
||||||
pub struct Witness {
|
pub struct Witness {
|
||||||
pub extension_id: u32,
|
pub extension_id: u32,
|
||||||
|
@ -48,6 +74,8 @@ pub struct Witness {
|
||||||
}
|
}
|
||||||
|
|
||||||
impl Witness {
|
impl Witness {
|
||||||
|
/// Produce the intermediate format for an extension-specific witness
|
||||||
|
/// type.
|
||||||
pub fn from<P: ToPayload>(extension_id: u32, value: &P) -> Witness {
|
pub fn from<P: ToPayload>(extension_id: u32, value: &P) -> Witness {
|
||||||
let (mode, payload) = value.to_payload();
|
let (mode, payload) = value.to_payload();
|
||||||
Witness {
|
Witness {
|
||||||
|
@ -56,6 +84,12 @@ impl Witness {
|
||||||
payload,
|
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)]
|
#[derive(Debug, PartialEq)]
|
||||||
|
@ -106,18 +140,27 @@ pub trait Extension<C> {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// This extension trait is satisfied by [`transaction::builder::Builder`]. It provides a
|
/// This extension trait is satisfied by [`transaction::builder::Builder`]. It provides a minimal
|
||||||
/// minimal contract for interacting with the transaction builder, that extension library authors
|
/// contract for interacting with the transaction builder, that extension library authors can use
|
||||||
/// can use to add extension-specific builder traits that may be used to interact with the
|
/// to add extension-specific builder traits that may be used to interact with the transaction
|
||||||
/// transaction builder. This may make it simpler for projects that include transaction-builder
|
/// builder. This may make it simpler for projects that include transaction-builder functionality
|
||||||
/// functionality to integrate with third-party extensions without those extensions being coupled to
|
/// to integrate with third-party extensions without those extensions being coupled to a particular
|
||||||
/// a particular transaction or builder representation.
|
/// transaction or builder representation.
|
||||||
///
|
///
|
||||||
/// [`transaction::builder::Builder`]: crate::transaction::builder::Builder
|
/// [`transaction::builder::Builder`]: crate::transaction::builder::Builder
|
||||||
pub trait ExtensionTxBuilder<'a> {
|
pub trait ExtensionTxBuilder<'a> {
|
||||||
type BuildCtx;
|
type BuildCtx;
|
||||||
type BuildError;
|
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>(
|
fn add_tze_input<WBuilder, W: ToPayload>(
|
||||||
&mut self,
|
&mut self,
|
||||||
extension_id: u32,
|
extension_id: u32,
|
||||||
|
@ -127,6 +170,8 @@ pub trait ExtensionTxBuilder<'a> {
|
||||||
where
|
where
|
||||||
WBuilder: 'a + (FnOnce(&Self::BuildCtx) -> Result<W, Self::BuildError>);
|
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>(
|
fn add_tze_output<P: ToPayload>(
|
||||||
&mut self,
|
&mut self,
|
||||||
extension_id: u32,
|
extension_id: u32,
|
||||||
|
|
Loading…
Reference in New Issue