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<ScriptBufDecoderError>>

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 to_hex(&self) -> String

👎Deprecated since 1.0.0-rc.0:

use format!("{var:x}") instead

Gets the hex representation of this script.

Returns

Just the script bytes in hexadecimal not consensus encoding of the script i.e., the string will not include a length prefix.

pub fn builder() -> Builder<T>

Constructs a new script builder

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

Adds a single opcode to the script.

pub fn push_slice<D: AsRef<PushBytes>>(&mut self, data: D)

Adds instructions to push some arbitrary data onto the stack.

If the data can be exactly produced by a numeric opcode, that opcode will be used, since its behavior is equivalent but will not violate minimality rules. To avoid this, use ScriptBuf::push_slice_non_minimal which will always use a push opcode.

However, this method does not enforce any numeric minimality rules. If your pushes should be interpreted as numbers, ensure your input does not have any leading zeros. In particular, the number 0 should be encoded as an empty string rather than as a single 0 byte.

pub fn push_slice_non_minimal<D: AsRef<PushBytes>>(&mut self, data: D)

Adds instructions to push some arbitrary data onto the stack without minimality.

Standardness rules require push minimality according to CheckMinimalPush of core.

impl ScriptBuf<ScriptPubKeyTag>

pub fn new_op_return<T: AsRef<PushBytes>>(data: T) -> Self

Generates OP_RETURN-type of scriptPubkey for the given data.

pub fn new_p2sh(script_hash: ScriptHash) -> Self

Generates P2SH-type of scriptPubkey with a given hash of the redeem script.

pub fn new_p2a() -> Self

Generates pay to anchor output.

impl<T: ScriptHashableTag> ScriptBuf<T>

pub fn new_p2wsh(script_hash: WScriptHash) -> Self

Generates a P2WSH witness program script with a given hash of the witness script.

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_bytes(&self) -> Vec<u8>

👎Deprecated since 0.101.0:

use to_vec instead

Returns a copy of the script data.

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 to_hex(&self) -> String

👎Deprecated since 1.0.0-rc.0:

use format!("{var:x}") instead

Gets the hex representation of this script.

Returns

Just the script bytes in hexadecimal not consensus encoding of the script i.e., the string will not include a length prefix.

pub fn witness_version(&self) -> Option<WitnessVersion>

where T: ScriptHashableTag,

Returns witness version of the script, if any.

Returns

The witness version if this script is found to conform to the SegWit rules:

A scriptPubKey (or redeemScript as defined in BIP-0016/P2SH) that consists of a 1-byte push opcode (for 0 to 16) followed by a data push between 2 and 40 bytes gets a new special meaning. The value of the first push is called the “version byte”. The following byte vector pushed is called the “witness program”.

pub fn is_p2wsh(&self) -> bool

where T: ScriptHashableTag,

Checks whether a script pubkey is a P2WSH output.

pub fn is_p2wpkh(&self) -> bool

where T: ScriptHashableTag,

Checks whether a script pubkey is a P2WPKH output.

pub fn script_hash(&self) -> Result<ScriptHash, RedeemScriptSizeError>

Returns 160-bit hash of the script for P2SH outputs.

Errors

Returns an error if the script exceeds 520 bytes.

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> Decode 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: Eq> Eq for ScriptBuf<T>

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 From<ScriptBuf<WitnessScriptTag>> for SignetBlockScriptBuf

fn from(buf: WitnessScriptBuf) -> 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<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.