Struct Cost

pub struct Cost(/* private fields */);

CPU cost of a Simplicity expression.

The cost is measured in milli weight units and can be converted into weight units using the appropriate method.

Roughly speaking, the operational semantics of a combinator on the Bit Machine determine its cost.

First, every combinator has a fixed overhead cost. Frame allocations, copy and write operations cost proportional to the number of allocated or written bits. Frame moves / drops or cursor moves are one-step operations that are covered by the overhead.

The cost of a program is compared to its budget. A program is valid if it does not exceed its budget.

The budget is the size of the witness stack of the transaction input that includes the program. Users pay for their Simplicity programs in terms of fees which are based on transaction size, like normal Tapscript.

Programs that are CPU-heavy need to be padded so that the witness stack provides a large-enough budget.

Implementations

impl Cost

pub const CONSENSUS_MAX: Self

Maximum cost allowed by consensus.

This is equal to the maximum budget that any program can have inside a Taproot transaction: 4 million weight units plus 50 free weight units for validation.

This assumes a block that consists of a single transaction which in turn consists of nothing but its witness stack.

Transactions include other data besides the witness stack. Also, transaction may have multiple inputs and blocks usually include multiple transactions. This means that the maximum budget is an unreachable upper bound.

pub const fn of_type(bit_width: usize) -> Self

Return the cost of a type with the given bit width.

pub const fn from_milliweight(milliweight: u32) -> Self

Convert the given milli weight units into cost.

pub fn is_consensus_valid(self) -> bool

Return whether the cost is allowed by consensus.

This means the cost is within the maximum budget that any program inside a Taproot transaction can have.

pub fn is_budget_valid(self, script_witness: &Vec<Vec<u8>>) -> bool

Return whether the cost is within the budget of the given script witness of a transaction input.

The script witness is passed as &Vec<Vec<u8>> in order to use the consensus encoding implemented for this type.

pub fn get_padding(self, script_witness: &Vec<Vec<u8>>) -> Option<Vec<u8>>

Return the annex bytes that are required as padding so the transaction input has enough budget to cover the cost.

The first annex byte is 0x50, as defined in BIP 341. The following padding bytes are 0x00.

Trait Implementations

impl Add for Cost

type Output = Cost

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self::Output

Performs the + operation.

impl Clone for Cost

fn clone(&self) -> Cost

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Cost

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

Formats the value using the given formatter.

impl Display for Cost

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

Formats the value using the given formatter.

impl From<Cost> for Weight

fn from(value: Cost) -> Self

Converts to this type from the input type.

impl From<Weight> for Cost

fn from(value: Weight) -> Self

Converts to this type from the input type.

impl Hash for Cost

fn hash<__H: Hasher>(&self, state: &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 Ord for Cost

fn cmp(&self, other: &Cost) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Cost

fn eq(&self, other: &Cost) -> 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 PartialOrd for Cost

fn partial_cmp(&self, other: &Cost) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for Cost

impl Eq for Cost

impl StructuralPartialEq for Cost