Struct ScriptBuf 

pub struct ScriptBuf<T>(/* private fields */);

An owned, growable script.

ScriptBuf is the most common script type that has the ownership over the contents of the script. It has a close relationship with its borrowed counterpart, Script.

Just as other similar types, this implements Deref, so deref coercions apply. Also note that all the safety/validity restrictions that apply to Script apply to ScriptBuf as well.

Hexadecimal strings

Scripts are consensus encoded with a length prefix and as a result of this in some places in the ecosystem one will encounter hex strings that include the prefix while in other places the prefix is excluded. To support parsing and formatting scripts as hex we provide a bunch of different APIs and trait implementations. Please see [examples/script.rs] for a thorough example of all the APIs.

Panics

ScriptBuf is backed by Vec and inherits its panic behavior. This means that attempting to construct scripts larger than isize::MAX bytes will panic.

Implementations

impl<T> ScriptBuf<T>

pub const fn new() -> Self

Constructs a new empty script.

pub const fn from_bytes(bytes: Vec<u8>) -> Self

Converts byte vector into script.

This method doesn’t (re)allocate. bytes is just the script bytes not consensus encoding (i.e no length prefix).

pub fn from_hex_prefixed(s: &str) -> Result<Self, FromHexError>

Constructs a new ScriptBuf from a hex string.

The input string is expected to be consensus encoded i.e., includes the length prefix.

Errors

• If s cannot be parsed into a vector.
• If the parsed bytes cannot be decoded as a valid script (incl.the length prefix).

pub fn from_hex_no_length_prefix( s: &str, ) -> Result<Self, DecodeVariableLengthBytesError>

Constructs a new ScriptBuf from a hex string.

This is not consensus encoding. If your hex string is a consensus encoded script then use ScriptBuf::from_hex_prefixed.

There is no script decoding error path because what ever is in the hex input string is assumed to be the script. This means if you pass a consensus encoded hex string into this function there will be no error and the script will not be what you expect.

Errors

Errors if s cannot be parsed into a vector.

pub fn as_script(&self) -> &Script<T>

Returns a reference to unsized script.

pub fn as_mut_script(&mut self) -> &mut Script<T>

Returns a mutable reference to unsized script.

pub fn into_bytes(self) -> Vec<u8>

Converts the script into a byte vector.

This method doesn’t (re)allocate.

Returns

Just the script bytes not consensus encoding (which includes a length prefix).

pub fn into_boxed_script(self) -> Box<Script<T>>

Converts this ScriptBuf into a boxed Script.

This method reallocates if the capacity is greater than length of the script but should not when they are equal. If you know beforehand that you need to create a script of exact size use reserve_exact before adding data to the script so that the reallocation can be avoided.

pub fn with_capacity(capacity: usize) -> Self

Constructs a new empty script with at least the specified capacity.

pub fn reserve(&mut self, additional_len: usize)

Pre-allocates at least additional_len bytes if needed.

Reserves capacity for at least additional_len more bytes to be inserted in the given script. The script may reserve more space to speculatively avoid frequent reallocations. After calling reserve, capacity will be greater than or equal to self.len() + additional_len. Does nothing if capacity is already sufficient.

Panics

Panics if the new capacity exceeds isize::MAX bytes.

pub fn reserve_exact(&mut self, additional_len: usize)

Pre-allocates exactly additional_len bytes if needed.

Unlike reserve, this will not deliberately over-allocate to speculatively avoid frequent allocations. After calling reserve_exact, capacity will be greater than or equal to self.len() + additional. Does nothing if the capacity is already sufficient.

Note that the allocator may give the collection more space than it requests. Therefore, capacity cannot be relied upon to be precisely minimal. Prefer reserve if future insertions are expected.

Panics

Panics if the new capacity exceeds isize::MAX bytes.

pub fn capacity(&self) -> usize

Returns the number of bytes available for writing without reallocation.

It is guaranteed that script.capacity() >= script.len() always holds.

pub fn reserved_len_for_slice(len: usize) -> usize

Returns the encoded length for pushing a slice of bytes.

pub fn push_opcode(&mut self, opcode: Opcode)

Adds a single opcode to the script.

pub fn push_int(&mut self, n: i32) -> Result<(), Error>

Adds instructions to push an integer onto the stack.

Errors

Returns Error::NumericOverflow when n is outside the minimally encodable range.

pub fn push_int_unchecked(&mut self, n: i64)

Adds instructions to push an unchecked integer onto the stack.

pub fn push_int_non_minimal(&mut self, data: i64)

Adds instructions to push an integer without numeric-opcode optimization.

Panics

Panics only if the internally encoded script integer somehow exceeds the PushBytes limit.

pub fn push_slice<D: AsRef<[u8]>>(&mut self, data: D)

Adds instructions to push some arbitrary data onto the stack.

pub fn push_slice_non_minimal<D: AsRef<[u8]>>(&mut self, data: D)

Adds instructions to push arbitrary data without minimal-push optimization.

Panics

Panics only if data exceeds the maximum size supported by PushBytes.

pub fn push_instruction(&mut self, instruction: Instruction<'_>)

Adds a single instruction.

pub fn scan_and_push_verify(&mut self)

Adds an OP_VERIFY or rewrites the last opcode to its VERIFY form when possible.

Methods from Deref<Target = Script<T>>

pub fn as_bytes(&self) -> &[u8]

Returns the script data as a byte slice.

This is just the script bytes not consensus encoding (which includes a length prefix).

pub fn as_mut_bytes(&mut self) -> &mut [u8]

Returns the script data as a mutable byte slice.

This is just the script bytes not consensus encoding (which includes a length prefix).

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

Returns a copy of the script data.

This is just the script bytes not consensus encoding (which includes a length prefix).

pub fn to_hex_string_prefixed(&self) -> String

Consensus encodes the script as lower-case hex.

Consensus encoding includes a length prefix. To hex encode without the length prefix use to_hex_string_no_length_prefix.

pub fn to_hex_string_no_length_prefix(&self) -> String

Encodes the script as lower-case hex.

This is not consensus encoding. The returned hex string will not include the length prefix. See to_hex_string_prefixed.

pub fn len(&self) -> usize

Returns the length in bytes of the script.

pub fn is_empty(&self) -> bool

Returns whether the script is the empty script.

pub fn instructions(&self) -> Instructions<'_>

Iterates over decoded instructions.

pub fn instructions_minimal(&self) -> Instructions<'_>

Iterates over decoded instructions while enforcing minimal pushes.

pub fn count_sigops(&self) -> usize

Counts signature-check operations using accurate multisig counting.

This is the counting mode used by the node for redeem scripts and witness scripts. OP_CHECKSIGADD is not counted by Tidecoin consensus.

pub fn count_sigops_legacy(&self) -> usize

Counts signature-check operations using legacy multisig counting.

This is the counting mode used by the node for scriptSigs and scriptPubKeys in context-free block sanity checks.

pub fn instruction_indices(&self) -> InstructionIndices<'_>

Iterates over decoded instructions together with their byte indices.

pub fn instruction_indices_minimal(&self) -> InstructionIndices<'_>

Iterates over decoded instructions and indices while enforcing minimal pushes.

pub fn last_opcode(&self) -> Option<Opcode>

Returns the last opcode if the final instruction is an opcode.

pub fn last_pushdata(&self) -> Option<&PushBytes>

Returns the last pushed byte slice if the final instruction is a data push.

Trait Implementations

impl<'a, T> Arbitrary<'a> for ScriptBuf<T>

Available on crate feature arbitrary only.

fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self>

Generate an arbitrary value of Self from the given unstructured data.

fn arbitrary_take_rest(u: Unstructured<'a>) -> Result<Self, Error>

Generate an arbitrary value of Self from the entirety of the given unstructured data.

fn size_hint(depth: usize) -> (usize, Option<usize>)

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

fn try_size_hint( depth: usize, ) -> Result<(usize, Option<usize>), MaxRecursionReached>

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

impl<T> AsMut<Script<T>> for ScriptBuf<T>

fn as_mut(&mut self) -> &mut Script<T>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<T> AsMut<[u8]> for ScriptBuf<T>

fn as_mut(&mut self) -> &mut [u8]

Converts this type into a mutable reference of the (usually inferred) input type.

impl<T> AsRef<Script<T>> for ScriptBuf<T>

fn as_ref(&self) -> &Script<T>

Converts this type into a shared reference of the (usually inferred) input type.

impl<T> AsRef<[u8]> for ScriptBuf<T>

fn as_ref(&self) -> &[u8]

Converts this type into a shared reference of the (usually inferred) input type.

impl<T> Borrow<Script<T>> for ScriptBuf<T>

fn borrow(&self) -> &Script<T>

Immutably borrows from an owned value.

impl<T> BorrowMut<Script<T>> for ScriptBuf<T>

fn borrow_mut(&mut self) -> &mut Script<T>

Mutably borrows from an owned value.

impl<T: Clone> Clone for ScriptBuf<T>

fn clone(&self) -> ScriptBuf<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for ScriptBuf<T>

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

Formats the value using the given formatter.

impl<T> Decodable for ScriptBuf<T>

type Decoder = ScriptBufDecoder<T>

Associated decoder for the type.

fn decoder() -> Self::Decoder

Constructs a “default decoder” for the type.

impl<T> Default for ScriptBuf<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T> Deref for ScriptBuf<T>

type Target = Script<T>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T> DerefMut for ScriptBuf<T>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'de, T> Deserialize<'de> for ScriptBuf<T>

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T> Display for ScriptBuf<T>

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

Formats the value using the given formatter.

impl<T> Encodable for ScriptBuf<T>

type Encoder<'e> = ScriptEncoder<'e> where Self: 'e

The encoder associated with this type. Conceptually, the encoder is like an iterator which yields byte slices.

fn encoder(&self) -> Self::Encoder<'_>

Constructs a “default encoder” for the type.

impl<T: Eq> Eq for ScriptBuf<T>

impl<'a, Tg> Extend<Instruction<'a>> for ScriptBuf<Tg>

fn extend<T>(&mut self, iter: T)

where T: IntoIterator<Item = Instruction<'a>>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a, T> From<&'a Script<T>> for ScriptBuf<T>

fn from(value: &'a Script<T>) -> Self

Converts to this type from the input type.

impl<'a, T> From<Cow<'a, Script<T>>> for ScriptBuf<T>

fn from(value: Cow<'a, Script<T>>) -> Self

Converts to this type from the input type.

impl<T> From<ScriptBuf<T>> for Box<Script<T>>

fn from(v: ScriptBuf<T>) -> Self

Converts to this type from the input type.

impl<T> From<ScriptBuf<T>> for Cow<'_, Script<T>>

fn from(value: ScriptBuf<T>) -> Self

Converts to this type from the input type.

impl<T> From<ScriptBuf<T>> for Vec<u8>

fn from(v: ScriptBuf<T>) -> Self

Converts to this type from the input type.

impl<T> From<Vec<u8>> for ScriptBuf<T>

fn from(v: Vec<u8>) -> Self

Converts to this type from the input type.

impl<'a, Tg> FromIterator<Instruction<'a>> for ScriptBuf<Tg>

fn from_iter<T>(iter: T) -> Self

where T: IntoIterator<Item = Instruction<'a>>,

Creates a value from an iterator.

impl<T: Hash> Hash for ScriptBuf<T>

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<T> LowerHex for ScriptBuf<T>

Available on crate feature hex only.

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

Formats the value using the given formatter.

impl<T: Ord> Ord for ScriptBuf<T>

fn cmp(&self, other: &ScriptBuf<T>) -> 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<T: PartialEq> PartialEq for ScriptBuf<T>

fn eq(&self, other: &ScriptBuf<T>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<T: PartialEq> PartialEq<Script<T>> for ScriptBuf<T>

fn eq(&self, other: &Script<T>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<T: PartialEq> PartialEq<ScriptBuf<T>> for Script<T>

fn eq(&self, other: &ScriptBuf<T>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<T: PartialOrd> PartialOrd for ScriptBuf<T>

fn partial_cmp(&self, other: &ScriptBuf<T>) -> 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<T: PartialOrd> PartialOrd<Script<T>> for ScriptBuf<T>

fn partial_cmp(&self, other: &Script<T>) -> 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<T: PartialOrd> PartialOrd<ScriptBuf<T>> for Script<T>

fn partial_cmp(&self, other: &ScriptBuf<T>) -> 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<T> Serialize for ScriptBuf<T>

Available on crate feature serde only.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

User-facing serialization for Script.

impl<T: PartialEq> StructuralPartialEq for ScriptBuf<T>

impl<T: ScriptHashableTag> TryFrom<&ScriptBuf<T>> for ScriptHash

type Error = RedeemScriptSizeError

The type returned in the event of a conversion error.

fn try_from(redeem_script: &ScriptBuf<T>) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<&ScriptBuf<WitnessScriptTag>> for WScriptHash

type Error = WitnessScriptSizeError

The type returned in the event of a conversion error.

fn try_from(witness_script: &WitnessScriptBuf) -> Result<Self, Self::Error>

Performs the conversion.

impl<T: ScriptHashableTag> TryFrom<ScriptBuf<T>> for ScriptHash

type Error = RedeemScriptSizeError

The type returned in the event of a conversion error.

fn try_from(redeem_script: ScriptBuf<T>) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<ScriptBuf<WitnessScriptTag>> for WScriptHash

type Error = WitnessScriptSizeError

The type returned in the event of a conversion error.

fn try_from(witness_script: WitnessScriptBuf) -> Result<Self, Self::Error>

Performs the conversion.

impl<T> UpperHex for ScriptBuf<T>

Available on crate feature hex only.

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

Formats the value using the given formatter.