Struct simplicity::node::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 imr(&self) -> Option<Imr>

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_witness_node( &self, witness: &HashMap<Arc<str>, Arc<Value>>, disconnect: &HashMap<Arc<str>, Arc<NamedCommitNode<J>>> ) -> Arc<WitnessNode<J>>

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

Encode a Simplicity expression to bits without any witness data

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

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

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

pub fn new( 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 finalize_types_main(&self) -> Result<Arc<NamedCommitNode<J>>, ErrorSet>

Finalizes the types of the underlying [ConstructNode].

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

Finalizes the types of the underlying [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 imr(&self) -> Option<Imr>

Accessor for the node’s IMR, 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: &mut BitIter<I> ) -> Result<Arc<Self>, Error>

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>

Encode a Simplicity expression to bits without any witness data

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

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_without_fixing] 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 decode<I: Iterator<Item = u8>>( bits: &mut 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 [RedeemNode::decode()].

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

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 imr(&self) -> Imr

Accessor for the node’s IMR

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_witness_node(&self) -> Arc<WitnessNode<J>>

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

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

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

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

Encode the program to bits.

Includes witness data. Returns the number of written bits.

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

Encode the program to a byte vector.

Includes witness data.

impl<J: Jet> Node<Witness<J>>

pub fn pruned(&self) -> Arc<Self>

Creates a copy of the node (and its entire DAG with the prune bit set)

pub fn arrow(&self) -> &Arrow

Accessor for the node’s arrow

pub fn must_prune(&self) -> bool

Whether the “must prune” bit is set on this node

pub fn prune_and_retype(&self) -> Arc<Self>

pub fn finalize(&self) -> Result<Arc<RedeemNode<J>>, Error>

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.

Trait Implementations

impl<'a, N: Marker> DagLike for &'a 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 ) -> 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: Marker> Display 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: 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

This method tests for self and other values to be equal, and is used by ==.

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

This method 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,