simplicity

Module node

Source
Expand description

Simplicity Program Nodes

The types in this module are used to represent Simplicity expressions as DAGs. The nodes of this DAG are individual combinators along with some cached data about the node, which depends on the specific node type.

All nodes represent the root of an expression. Expressions whose source and target types are both unit are called “programs”. Generally speaking, any nodes that users hold directly will be programs.

There are three main node types:

  1. crate::RedeemNode represents a Simplicity node as it exists on the blockchain. Every witness node is populated with a correctly-typed Value, every disconnect node has a child, every non-executed branch of a case combinator is pruned, and there is nothing you can do to modify the expression.

    RedeemNodes can be executed on the bit machine and have complete types and resource bounds, and can be serialized in the consensus bit-encoding.

  2. CommitNode represents a Simplicity node as it is committed to on the blockchain. This means that witness and (TODO) disconnect nodes are not populated, but type inference is complete and resource bounds are available. case combinators may have pruned children (in which case they are instead considered assertl or assertr combinators), or not.

    There is a bit-encoding for CommitNodes which is essentially only used by this library. It consists of the bit-encoding.of the combinators, fully shared except that witness and disconnect nodes (and their ancestors) are unshared. No witness data is included.

    TODO there is also a human-readable encoding.

  3. ConstructNode represents an “under-construction” Simplicity expression. These nodes’ types are not necessarily complete, and are inferred as the program is constructed. This is the only node that you can programmatically construct. It has no encoding, human-readable or bitwise, and is intended to exist only ephemerally.

The following conversions are possible between the node types:

  1. ConstructNode::finalize_types converts a ConstructNode to a CommitNode by setting any free variables, as well as the source and target of the root node, to unit.

    This conversion requires no input from the user but may fail with a type error, in case of infinitely-sized types or in the case that the unit bounds cannot be applied.

  2. CommitNode::finalize converts a CommitNode to a RedeemNode by attaching witnesses to each witness node, and deciding whether to hide branches for each case node.

  3. CommitNode::unfinalize_types converts a CommitNode to a ConstructNode by throwing away all types and re-inferring them. It cannot fail.

  4. RedeemNode::unfinalize converts a RedeemNode to a CommitNode by throwing away witness and (TODO) disconnect data. It cannot recover pruned branches so is of limited usefulness, but it is included for completeness.

Structs§

Commit
CommitData
Construct
ConstructData
Display
Convenience structure for displaying a Simplictiy expression with its witness.
DisplayExpr
Display a Simplicity expression as a linear string.
Hiding
Wrapper that allows a node to be “hidden” during program construction.
NoDisconnect
Null data type used as dummy for crate::node::Marker::Disconnect
NoWitness
Null data type used as dummy for Marker::Witness
Node
A node in a Simplicity expression.
Redeem
RedeemData
SimpleFinalizer
Basic finalizer which converts a super::CommitNode to a super::RedeemNode by attaching witness data from an iterator.

Enums§

Hide
A decision about which, if any, child branches of a case combinator to hide during a Node::convert conversion
Inner
Internal “Simplicity DAG” structure.

Traits§

Constructible
Converter
The primary trait controlling how a node conversion is done.
CoreConstructible
DisconnectConstructible
Disconnectable
Trait representing a “disconnected expression”.
JetConstructible
Marker
WitnessConstructible

Type Aliases§

CommitNode
ConstructNode
RedeemNode