Struct bitcoin::script::ScriptBuf

pub struct ScriptBuf(/* 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.

Implementations

impl ScriptBuf

pub const fn new() -> Self

Creates a new empty script.

pub fn with_capacity(capacity: usize) -> Self

Creates a new empty script with pre-allocated 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 can not 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 as_script(&self) -> &Script

Returns a reference to unsized script.

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

Returns a mutable reference to unsized script.

pub fn builder() -> Builder

Creates a new script builder

pub fn new_p2pk(pubkey: &PublicKey) -> Self

Generates P2PK-type of scriptPubkey.

pub fn new_p2pkh(pubkey_hash: &PubkeyHash) -> Self

Generates P2PKH-type of scriptPubkey.

pub fn new_p2sh(script_hash: &ScriptHash) -> Self

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

pub fn new_p2wpkh(pubkey_hash: &WPubkeyHash) -> Self

Generates P2WPKH-type of scriptPubkey.

pub fn new_p2wsh(script_hash: &WScriptHash) -> Self

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

pub fn new_p2tr<C: Verification>( secp: &Secp256k1<C>, internal_key: UntweakedPublicKey, merkle_root: Option<TapNodeHash> ) -> Self

Generates P2TR for script spending path using an internal public key and some optional script tree merkle root.

pub fn new_p2tr_tweaked(output_key: TweakedPublicKey) -> Self

Generates P2TR for key spending path for a known TweakedPublicKey.

pub fn new_witness_program(witness_program: &WitnessProgram) -> Self

Generates P2WSH-type of scriptPubkey with a given WitnessProgram.

pub fn p2wpkh_script_code(wpkh: WPubkeyHash) -> ScriptBuf

Creates the script code used for spending a P2WPKH output.

The scriptCode is described in BIP143.

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

Generates OP_RETURN-type of scriptPubkey for the given data.

pub fn from_hex(s: &str) -> Result<Self, HexToBytesError>

Creates a ScriptBuf from a hex string.

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

Converts byte vector into script.

This method doesn’t (re)allocate.

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

Converts the script into a byte vector.

This method doesn’t (re)allocate.

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

Adds a single opcode to the script.

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

Adds instructions to push some arbitrary data onto the stack.

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

Add a single instruction to the script.

Panics

The method panics if the instruction is a data push with length greater or equal to 0x100000000.

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

Like push_instruction, but avoids calling reserve to not re-check the length.

pub fn scan_and_push_verify(&mut self)

Adds an OP_VERIFY to the script or replaces the last opcode with VERIFY form.

Some opcodes such as OP_CHECKSIG have a verify variant that works as if VERIFY was in the script right after. To save space this function appends VERIFY only if the most-recently-added opcode does not have an alternate VERIFY form. If it does the last opcode is replaced. E.g., OP_CHECKSIG will become OP_CHECKSIGVERIFY.

Note that existing OP_*VERIFY opcodes do not lead to the instruction being ignored because OP_VERIFY consumes an item from the stack so ignoring them would change the semantics.

This function needs to iterate over the script to find the last instruction. Prefer Builder if you’re creating the script from scratch or if you want to push OP_VERIFY multiple times.

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

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.

Methods from Deref<Target = Script>

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

Returns the script data as a byte slice.

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

Returns the script data as a mutable byte slice.

pub fn script_hash(&self) -> ScriptHash

Returns 160-bit hash of the script.

pub fn wscript_hash(&self) -> WScriptHash

Returns 256-bit hash of the script for P2WSH outputs.

pub fn tapscript_leaf_hash(&self) -> TapLeafHash

Computes leaf hash of tapscript.

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

Returns a copy of the script data.

pub fn bytes(&self) -> Bytes<'_>

Returns an iterator over script bytes.

pub fn to_p2wsh(&self) -> ScriptBuf

Computes the P2WSH output corresponding to this witnessScript (aka the “witness redeem script”).

pub fn to_p2tr<C: Verification>( &self, secp: &Secp256k1<C>, internal_key: UntweakedPublicKey ) -> ScriptBuf

Computes P2TR output with a given internal key and a single script spending path equal to the current script, assuming that the script is a Tapscript.

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

Returns witness version of the script, if any, assuming the script is a scriptPubkey.

Returns

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

A scriptPubKey (or redeemScript as defined in BIP16/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_p2sh(&self) -> bool

Checks whether a script pubkey is a P2SH output.

pub fn is_p2pkh(&self) -> bool

Checks whether a script pubkey is a P2PKH output.

pub fn is_push_only(&self) -> bool

Checks whether a script is push only.

Note: OP_RESERVED (0x50) and all the OP_PUSHNUM operations are considered push operations.

pub fn is_p2pk(&self) -> bool

Checks whether a script pubkey is a P2PK output.

You can obtain the public key, if its valid, by calling p2pk_public_key()

pub fn p2pk_public_key(&self) -> Option<PublicKey>

Returns the public key if this script is P2PK with a valid public key.

This may return None even when is_p2pk() returns true. This happens when the public key is invalid (e.g. the point not being on the curve). In this situation the script is unspendable.

pub fn is_multisig(&self) -> bool

Checks whether a script pubkey is a bare multisig output.

In a bare multisig pubkey script the keys are not hashed, the script is of the form:

2 <pubkey1> <pubkey2> <pubkey3> 3 OP_CHECKMULTISIG

pub fn is_witness_program(&self) -> bool

Checks whether a script pubkey is a Segregated Witness (segwit) program.

pub fn is_p2wsh(&self) -> bool

Checks whether a script pubkey is a P2WSH output.

pub fn is_p2wpkh(&self) -> bool

Checks whether a script pubkey is a P2WPKH output.

pub fn is_p2tr(&self) -> bool

Checks whether a script pubkey is a P2TR output.

pub fn is_op_return(&self) -> bool

Check if this is an OP_RETURN output.

pub fn is_provably_unspendable(&self) -> bool

👎Deprecated since 0.32.0: The method has potentially confusing semantics and is going to be removed, you might want is_op_return

Checks whether a script is trivially known to have no satisfying input.

This method has potentially confusing semantics and an unclear purpose, so it’s going to be removed. Use is_op_return if you want OP_RETURN semantics.

pub fn to_p2sh(&self) -> ScriptBuf

Computes the P2SH output corresponding to this redeem script.

pub fn p2wpkh_script_code(&self) -> Option<ScriptBuf>

Returns the script code used for spending a P2WPKH output if this script is a script pubkey for a P2WPKH output. The scriptCode is described in BIP143.

pub fn redeem_script(&self) -> Option<&Script>

Get redeemScript following BIP16 rules regarding P2SH spending.

This does not guarantee that this represents a P2SH input Script. It merely gets the last push of the script. Use Script::is_p2sh on the scriptPubKey to check whether it is actually a P2SH script.

pub fn dust_value(&self) -> Amount

👎Deprecated since 0.32.0: use minimal_non_dust and friends

Returns the minimum value an output with this script should have in order to be broadcastable on today’s Bitcoin network.

pub fn minimal_non_dust(&self) -> Amount

Returns the minimum value an output with this script should have in order to be broadcastable on today’s Bitcoin network.

Dust depends on the -dustrelayfee value of the Bitcoin Core node you are broadcasting to. This function uses the default value of 0.00003 BTC/kB (3 sat/vByte).

To use a custom value, use minimal_non_dust_custom.

pub fn minimal_non_dust_custom(&self, dust_relay_fee: FeeRate) -> Amount

Returns the minimum value an output with this script should have in order to be broadcastable on today’s Bitcoin network.

Dust depends on the -dustrelayfee value of the Bitcoin Core node you are broadcasting to. This function lets you set the fee rate used in dust calculation.

The current default value in Bitcoin Core (as of v26) is 3 sat/vByte.

To use the default Bitcoin Core value, use minimal_non_dust.

pub fn count_sigops(&self) -> usize

Counts the sigops for this Script using accurate counting.

In Bitcoin Core, there are two ways to count sigops, “accurate” and “legacy”. This method uses “accurate” counting. This means that OP_CHECKMULTISIG and its verify variant count for N sigops where N is the number of pubkeys used in the multisig. However, it will count for 20 sigops if CHECKMULTISIG is not preceded by an OP_PUSHNUM from 1 - 16 (this would be an invalid script)

Bitcoin Core uses accurate counting for sigops contained within redeemScripts (P2SH) and witnessScripts (P2WSH) only. It uses legacy for sigops in scriptSigs and scriptPubkeys.

(Note: taproot scripts don’t count toward the sigop count of the block, nor do they have CHECKMULTISIG operations. This function does not count OP_CHECKSIGADD, so do not use this to try and estimate if a taproot script goes over the sigop budget.)

pub fn count_sigops_legacy(&self) -> usize

Counts the sigops for this Script using legacy counting.

In Bitcoin Core, there are two ways to count sigops, “accurate” and “legacy”. This method uses “legacy” counting. This means that OP_CHECKMULTISIG and its verify variant count for 20 sigops.

Bitcoin Core uses legacy counting for sigops contained within scriptSigs and scriptPubkeys. It uses accurate for redeemScripts (P2SH) and witnessScripts (P2WSH).

(Note: taproot scripts don’t count toward the sigop count of the block, nor do they have CHECKMULTISIG operations. This function does not count OP_CHECKSIGADD, so do not use this to try and estimate if a taproot script goes over the sigop budget.)

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

Iterates over the script instructions.

Each returned item is a nested enum covering opcodes, datapushes and errors. At most one error will be returned and then the iterator will end. To instead iterate over the script as sequence of bytes call the bytes method.

To force minimal pushes, use instructions_minimal.

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

Iterates over the script instructions while enforcing minimal pushes.

This is similar to instructions but an error is returned if a push is not minimal.

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

Iterates over the script instructions and their indices.

Unless the script contains an error, the returned item consists of an index pointing to the position in the script where the instruction begins and the decoded instruction - either an opcode or data push.

To force minimal pushes, use Self::instruction_indices_minimal.

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

Iterates over the script instructions and their indices while enforcing minimal pushes.

This is similar to instruction_indices but an error is returned if a push is not minimal.

pub fn fmt_asm(&self, f: &mut dyn Write) -> Result

Writes the human-readable assembly representation of the script to the formatter.

pub fn to_asm_string(&self) -> String

Returns the human-readable assembly representation of the script.

pub fn to_hex_string(&self) -> String

Formats the script as lower-case hex.

This is a more convenient and performant way to write format!("{:x}", script). For better performance you should generally prefer displaying the script but if String is required (this is common in tests) this method can be used.

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

Returns the first opcode of the script (if there is any).

pub fn verify( &self, index: usize, amount: Amount, spending_tx: &[u8] ) -> Result<(), BitcoinconsensusError>

Verifies spend of an input script.

Shorthand for Self::verify_with_flags with flag bitcoinconsensus::VERIFY_ALL.

Parameters

• index - The input index in spending which is spending this transaction.
• amount - The amount this script guards.
• spending_tx - The transaction that attempts to spend the output holding this script.

pub fn verify_with_flags<F: Into<u32>>( &self, index: usize, amount: Amount, spending_tx: &[u8], flags: F ) -> Result<(), BitcoinconsensusError>

Verifies spend of an input script.

Parameters

• index - The input index in spending which is spending this transaction.
• amount - The amount this script guards.
• spending_tx - The transaction that attempts to spend the output holding this script.
• flags - Verification flags, see bitcoinconsensus::VERIFY_ALL and similar.

Trait Implementations

impl AsMut<[u8]> for ScriptBuf

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

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

impl AsMut<Script> for ScriptBuf

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

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

impl AsRef<[u8]> for ScriptBuf

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

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

impl AsRef<Script> for ScriptBuf

fn as_ref(&self) -> &Script

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

impl Borrow<Script> for ScriptBuf

fn borrow(&self) -> &Script

Immutably borrows from an owned value.

impl BorrowMut<Script> for ScriptBuf

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

Mutably borrows from an owned value.

impl Clone for ScriptBuf

fn clone(&self) -> ScriptBuf

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ScriptBuf

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

Formats the value using the given formatter.

impl Decodable for ScriptBuf

fn consensus_decode_from_finite_reader<R: Read + ?Sized>( r: &mut R ) -> Result<Self, Error>

Decode Self from a size-limited reader.

fn consensus_decode<R: Read + ?Sized>(reader: &mut R) -> Result<Self, Error>

Decode an object with a well-defined format.

impl Default for ScriptBuf

fn default() -> ScriptBuf

Returns the “default value” for a type.

impl Deref for ScriptBuf

type Target = Script

The resulting type after dereferencing.

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

Dereferences the value.

impl DerefMut for ScriptBuf

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

Mutably dereferences the value.

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

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for ScriptBuf

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

Formats the value using the given formatter.

impl Encodable for ScriptBuf

fn consensus_encode<W: Write + ?Sized>(&self, w: &mut W) -> Result<usize, Error>

Encodes an object with a well-defined format.

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

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> From<&'a Script> for ScriptBuf

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

Converts to this type from the input type.

impl From<&ScriptBuf> for ScriptHash

fn from(script: &ScriptBuf) -> ScriptHash

Converts to this type from the input type.

impl From<&ScriptBuf> for WScriptHash

fn from(script: &ScriptBuf) -> WScriptHash

Converts to this type from the input type.

impl From<Address<NetworkChecked>> for ScriptBuf

fn from(a: Address) -> Self

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl From<ScriptBuf> for Box<Script>

fn from(v: ScriptBuf) -> Self

Converts to this type from the input type.

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

fn from(value: ScriptBuf) -> Self

Converts to this type from the input type.

impl From<ScriptBuf> for ScriptHash

fn from(script: ScriptBuf) -> ScriptHash

Converts to this type from the input type.

impl From<ScriptBuf> for Vec<u8>

fn from(v: ScriptBuf) -> Self

Converts to this type from the input type.

impl From<ScriptBuf> for WScriptHash

fn from(script: ScriptBuf) -> WScriptHash

Converts to this type from the input type.

impl From<Vec<u8, Global>> for ScriptBuf

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

Converts to this type from the input type.

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

fn from_iter<T>(iter: T) -> Selfwhere T: IntoIterator<Item = Instruction<'a>>,

Creates a value from an iterator.

impl Hash for ScriptBuf

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

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

Formats the value using the given formatter.

impl Ord for ScriptBuf

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

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl PartialEq<Script> for ScriptBuf

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

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

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

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl PartialOrd<ScriptBuf> for Script

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl PartialOrd<ScriptBuf> for ScriptBuf

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl Serialize for ScriptBuf

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

User-facing serialization for Script.

impl UpperHex for ScriptBuf

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

Formats the value using the given formatter.

impl Eq for ScriptBuf

impl StructuralEq for ScriptBuf

impl StructuralPartialEq for ScriptBuf