Struct Node

pub struct Node<N: Marker> { /* private fields */ }

A node in a Simplicity expression.

There are three node types provided by this library: ConstructNode, CommitNode, and RedeemNode, which represent Simplicty programs during construction, at commitment time, and at redemption time, respectively.

This generic structure is used to define conversions and mapping functions over nodes and DAGs, and allows users to define their own custom node types.

For equality and hashing purposes, nodes are characterized entirely by their CMR and cached data. Users who create custom nodes should define a custom type for Marker::CachedData and think carefully about whether and how to implement the std::hash::Hash or equality traits.

Implementations

impl<J: Jet> Node<Named<Commit<J>>>

pub fn from_node(root: &CommitNode<J>) -> Arc<Self>

pub fn name(&self) -> &Arc<str>

Accessor for the node’s name

pub fn ihr(&self) -> Option<Ihr>

Accessor for the node’s name

pub fn arrow(&self) -> &FinalArrow

Accessor for the node’s type arrow

pub fn to_commit_node(&self) -> Arc<CommitNode<J>>

Forget the names, yielding an ordinary CommitNode.

pub fn to_construct_node( &self, witness: &HashMap<Arc<str>, Value>, disconnect: &HashMap<Arc<str>, Arc<NamedCommitNode<J>>>, ) -> Arc<ConstructNode<J>>

pub fn encode<W: Write>(&self, w: &mut BitWriter<W>) -> Result<usize>

👎Deprecated since 0.5.0: use Self::encode_without_witness instead

Encode a Simplicity expression to bits without any witness data

pub fn encode_to_vec(&self) -> Vec<u8>

👎Deprecated since 0.5.0: use Self::to_vec_without_witness instead

Encode a Simplicity program to a vector of bytes, without any witness data.

impl<J: Jet> Node<Named<Construct<J>>>

pub fn new( inference_context: &Context, name: Arc<str>, position: Position, user_source_types: Arc<[Type]>, user_target_types: Arc<[Type]>, inner: Inner<Arc<Self>, J, Arc<Self>, WitnessOrHole>, ) -> Result<Self, Error>

Construct a named construct node from parts.

pub fn renamed(&self, new_name: Arc<str>) -> Self

Creates a copy of a node with a different name.

pub fn name(&self) -> &Arc<str>

Accessor for the node’s name

pub fn position(&self) -> Position

Accessor for the node’s position

pub fn arrow(&self) -> &Arrow

Accessor for the node’s arrow

pub fn inference_context(&self) -> &Context

Accessor for the node’s type inference context.

pub fn finalize_types_main(&self) -> Result<Arc<NamedCommitNode<J>>, ErrorSet>

Finalizes the types of the underlying crate::ConstructNode.

pub fn finalize_types_non_main( &self, ) -> Result<Arc<NamedCommitNode<J>>, ErrorSet>

Finalizes the types of the underlying crate::ConstructNode, without setting the root node’s arrow to 1->1.

pub fn finalize_types_inner( &self, for_main: bool, ) -> Result<Arc<NamedCommitNode<J>>, ErrorSet>

impl<J: Jet> Node<Commit<J>>

pub fn arrow(&self) -> &FinalArrow

Accessor for the node’s arrow

pub fn amr(&self) -> Option<Amr>

Accessor for the node’s AMR, if known

pub fn ihr(&self) -> Option<Ihr>

Accessor for the node’s IHR, if known

pub fn finalize<C: Converter<Commit<J>, Redeem<J>>>( &self, converter: &mut C, ) -> Result<Arc<RedeemNode<J>>, C::Error>

Finalizes a DAG, by iterating through through it without sharing, attaching witnesses, and hiding branches.

This is a thin wrapper around Node::convert which fixes a few types to make it easier to use.

pub fn unfinalize_types(&self) -> Result<Arc<ConstructNode<J>>, Error>

Convert a CommitNode back to a ConstructNode by redoing type inference

pub fn decode<I: Iterator<Item = u8>>( bits: BitIter<I>, ) -> Result<Arc<Self>, DecodeError>

Decode a Simplicity program from bits, without witness data.

Usage

Use this method only if the serialization does not include the witness data. This means, the program simply has no witness during commitment, or the witness is provided by other means.

If the serialization contains the witness data, then use RedeemNode::decode().

pub fn encode<W: Write>(&self, w: &mut BitWriter<W>) -> Result<usize>

👎Deprecated since 0.5.0: use Self::encode_without_witness instead

Encode a Simplicity expression to bits without any witness data

pub fn encode_to_vec(&self) -> Vec<u8>

👎Deprecated since 0.5.0: use Self::to_vec_without_witness instead

Encode a Simplicity program to a vector of bytes, without any witness data.

impl<J: Jet> Node<Construct<J>>

pub fn arrow(&self) -> &Arrow

Accessor for the node’s arrow

pub fn set_arrow_to_program(&self) -> Result<(), Error>

Sets the source and target type of the node to unit

pub fn finalize_types(&self) -> Result<Arc<CommitNode<J>>, Error>

Convert a ConstructNode to a CommitNode by finalizing all of the types.

Also sets the source and target type of this node to unit. This is almost certainly what you want, since the resulting CommitNode cannot be further composed, and needs to be 1->1 to go on-chain. But if you don’t, call Self::finalize_types_non_program instead.

pub fn finalize_types_non_program(&self) -> Result<Arc<CommitNode<J>>, Error>

Convert a ConstructNode to a CommitNode by finalizing all of the types.

Does not sets the source and target type of this node to unit.

pub fn finalize_unpruned(&self) -> Result<Arc<RedeemNode<J>>, FinalizeError>

Finalize the witness program as an unpruned redeem program.

Witness nodes must be populated with sufficient data, to ensure that the resulting redeem program successfully runs on the Bit Machine. Furthermore, all disconnected branches must be populated, even those that are not executed.

The resulting redeem program is not pruned.

See

RedeemNode::prune

pub fn finalize_pruned( &self, env: &J::Environment, ) -> Result<Arc<RedeemNode<J>>, FinalizeError>

Finalize the witness program as a pruned redeem program.

Witness nodes must be populated with sufficient data, to ensure that the resulting redeem program successfully runs on the Bit Machine. Furthermore, all disconnected branches must be populated, even those that are not executed.

The resulting redeem program is pruned based on the given transaction environment.

See

RedeemNode::prune

pub fn decode<I: Iterator<Item = u8>>( bits: BitIter<I>, ) -> Result<Arc<Self>, Error>

Decode a Simplicity expression from bits, without witness data.

Usage

Use this method only if the serialization does not include the witness data. This means, the program simply has no witness during commitment, or the witness is provided by other means.

If the serialization contains the witness data, then use crate::RedeemNode::decode().

pub fn encode<W: Write>(&self, w: &mut BitWriter<W>) -> Result<usize>

👎Deprecated since 0.5.0: use Self::encode_without_witness instead

Encode a Simplicity expression to bits, with no witness data

impl<J: Jet> Node<Redeem<J>>

pub fn amr(&self) -> Amr

Accessor for the node’s AMR

pub fn ihr(&self) -> Ihr

Accessor for the node’s IHR

pub fn arrow(&self) -> &FinalArrow

Accessor for the node’s type arrow

pub fn bounds(&self) -> NodeBounds

Accessor for the node’s bit machine bounds

pub fn unfinalize(&self) -> Result<Arc<CommitNode<J>>, Error>

Convert a RedeemNode back to a CommitNode by forgetting witnesses and cached data.

pub fn to_construct_node(&self) -> Arc<ConstructNode<J>>

Convert a RedeemNode back into a ConstructNode by loosening the finalized types, witness data and disconnected branches.

pub fn prune( &self, env: &J::Environment, ) -> Result<Arc<RedeemNode<J>>, ExecutionError>

Prune the redeem program for the given transaction environment.

Pruning works as follows:

1. Run the redeem program on the Bit Machine.
2. Mark all (un)used case branches using the IHR of the case node.
3. Rebuild the program and omit unused branches.

The pruning result depends on the witness data (which is already part of the redeem program) and on the transaction environment. These two inputs determine which case branches are used and which are not. Pruning must be done for each transaction environment separately, starting from the same original, unpruned program. Pruning is a lossy process, so pruning an already pruned program is not sound.

Pruning fails if the original, unpruned program fails to run on the Bit Machine (step 1). In this case, the witness data needs to be revised. The other pruning steps (2 & 3) never fail.

pub fn decode<I1, I2>( program: BitIter<I1>, witness: BitIter<I2>, ) -> Result<Arc<Self>, DecodeError>

where I1: Iterator<Item = u8>, I2: Iterator<Item = u8>,

Decode a Simplicity program from bits, including the witness data.

pub fn encode<W1, W2>( &self, prog: &mut BitWriter<W1>, witness: &mut BitWriter<W2>, ) -> Result<usize>

where W1: Write, W2: Write,

👎Deprecated since 0.5.0: use Self::encode_with_witness instead

Encode the program to bits.

Includes witness data. Returns the number of written bits.

pub fn encode_to_vec(&self) -> (Vec<u8>, Vec<u8>)

👎Deprecated since 0.5.0: use Self::to_vec_with_witness instead

Encode the program and witness data to byte vectors.

impl<N: Marker> Node<N>

pub fn inner(&self) -> &Inner<Arc<Node<N>>, N::Jet, N::Disconnect, N::Witness>

Accessor for the node’s “inner value”, i.e. its combinator

pub fn cmr(&self) -> Cmr

Accessor for the node’s CMR

pub fn sharing_id(&self) -> Option<N::SharingId>

Accessor for the node’s cached data

pub fn cached_data(&self) -> &N::CachedData

Accessor for the node’s cached data

pub fn from_parts( inner: Inner<Arc<Self>, N::Jet, N::Disconnect, N::Witness>, data: N::CachedData, ) -> Self

Contruct a node from its constituent parts.

This method can be used to directly costruct a node. It will compute the CMR automatically based on the value of inner but requires that cached_data be provided.

If available, [`Constructible’] and its dependent traits will be easier to use.

pub fn convert<S, M, C>( &self, converter: &mut C, ) -> Result<Arc<Node<M>>, C::Error>

where S: for<'a> SharingTracker<&'a Self> + Default, M: Marker<Jet = <N as Marker>::Jet>, C: Converter<N, M>,

Generic conversion function from one type of node to another, with the ability to prune during the conversion.

Parameterized over what kind of sharing to use when iterating over the DAG, and what conversion logic to use.

See the documentation for Converter for details.

pub fn display(&self) -> Display<'_, N>

pub fn display_expr(&self) -> DisplayExpr<'_, N>

Display the Simplicity expression as a linear string.

The linear string has no sharing and may be exponentially larger than the originally shared expression!

pub fn encode_without_witness<W: Write>(&self, prog: W) -> Result<usize>

Encode a Simplicity expression to bits without any witness data.

pub fn to_vec_without_witness(&self) -> Vec<u8>

Encode a Simplicity expression to a vector of bytes, without any witness data.

impl<N: Marker<Witness = Value>> Node<N>

pub fn encode_with_witness<W1: Write, W2: Write>( &self, prog: W1, witness: W2, ) -> Result<(usize, usize)>

Encode the program and witness data to bits.

Returns the number of written bits for the program and witness, respectively.

pub fn to_vec_with_witness(&self) -> (Vec<u8>, Vec<u8>)

Encode the program and witness data to byte vectors.

Trait Implementations

impl<N: Marker> DagLike for &Node<N>

type Node = Node<N>

The type of the DAG node, with no references or wrappers

fn data(&self) -> &Node<N>

A pointer to the underlying data

fn as_dag_node(&self) -> Dag<Self>

Interpret the node as a DAG node

fn left_child(&self) -> Option<Self>

Accessor for the left child of the node, if one exists

fn right_child(&self) -> Option<Self>

Accessor for the right child of the node, if one exists

fn n_children(&self) -> usize

Number of children that the node has.

fn rtl_post_order_iter<S: SharingTracker<SwapChildren<Self>> + Default>( self, ) -> RtlPostOrderIter<Self, S>

Obtains an iterator of all the nodes rooted at the DAG, in right-to-left post order.

fn pre_order_iter<S: SharingTracker<Self> + Default>( self, ) -> PreOrderIter<Self, S>

Obtains an iterator of all the nodes rooted at the DAG, in pre-order.

fn verbose_pre_order_iter<S: SharingTracker<Self> + Default>( self, max_depth: Option<usize>, ) -> VerbosePreOrderIter<Self, S>

where Self: Clone,

Obtains a verbose iterator of all the nodes rooted at the DAG, in pre-order.

fn post_order_iter<S: SharingTracker<Self> + Default>( self, ) -> PostOrderIter<Self, S>

Obtains an iterator of all the nodes rooted at the DAG, in post order.

fn is_shared_as<S: SharingTracker<Self> + Default>(self) -> bool

where Self: Clone,

Checks whether a DAG’s internal sharing (as expressed by shared pointers) matches the given target sharing.

fn post_order_iter_with_tracker<S: SharingTracker<Self>>( self, tracker: S, ) -> PostOrderIter<Self, S>

Obtains an post-order iterator of all the nodes rooted at DAG, using the given tracker.

impl<N: Marker> Debug for Node<N>

where for<'a> &'a Node<N>: DagLike,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'n, M: Marker> From<&'n Node<M>> for Display<'n, M>

fn from(node: &'n Node<M>) -> Self

Converts to this type from the input type.

impl<'a, M: Marker> From<&'a Node<M>> for DisplayExpr<'a, M>

fn from(node: &'a Node<M>) -> Self

Converts to this type from the input type.

impl<N: Marker> HasCmr for Node<N>

fn cmr(&self) -> Cmr

Access the Commitment Merkle Root.

impl<N: Marker> Hash for Node<N>

where N::CachedData: Hash,

fn hash<H: Hasher>(&self, h: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<N: Marker> PartialEq for Node<N>

where N::CachedData: PartialEq,

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<N: Marker> SharingTracker<&Node<N>> for MaxSharing<N>

fn record(&mut self, d: &&Node<N>, index: usize) -> Option<usize>

Marks an object as having been seen, and record the index when it was seen.

fn seen_before(&self, d: &&Node<N>) -> Option<usize>

Check whether an object has been seen before; if so, return the index it was recorded at.

impl<N: Marker> Eq for Node<N>

where N::CachedData: Eq,