Struct walletd_bitcoin::Script

#[repr(transparent)]
pub struct Script(_);

Bitcoin script slice.

See also the bitcoin::blockdata::script module.

Script is a script slice, the most primitive script type. It’s usually seen in its borrowed form &Script. It is always encoded as a series of bytes representing the opcodes and data pushes.

Validity

Script does not have any validity invariants - it’s essentially just a marked slice of bytes. This is similar to Path vs OsStr where they are trivially cast-able to each-other and Path doesn’t guarantee being a usable FS path but having a newtype still has value because of added methods, readability and basic type checking.

Although at least data pushes could be checked not to overflow the script, bad scripts are allowed to be in a transaction (outputs just become unspendable) and there even are such transactions in the chain. Thus we must allow such scripts to be placed in the transaction.

Slicing safety

Slicing is similar to how str works: some ranges may be incorrect and indexing by usize is not supported. However, as opposed to std, we have no way of checking correctness without causing linear complexity so there are no panics on invalid ranges! If you supply an invalid range, you’ll get a garbled script.

The range is considered valid if it’s at a boundary of instruction. Care must be taken especially with push operations because you could get a reference to arbitrary attacker-supplied bytes that look like a valid script.

It is recommended to use .instructions() method to get an iterator over script instructions and work with that instead.

Memory safety

The type is #[repr(transparent)] for internal purposes only! No consumer crate may rely on the represenation of the struct!

References

Bitcoin Core References

• CScript definition

Implementations

impl Script

pub fn from_bytes(bytes: &[u8]) -> &Script

Treat byte slice as Script

pub fn from_bytes_mut(bytes: &mut [u8]) -> &mut Script

Treat mutable byte slice as 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 empty() -> &'static Script

Creates a new empty script.

pub fn builder() -> Builder

Creates a new script builder

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, Global>

Returns a copy of the script data.

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

Returns an iterator over script bytes.

pub fn to_v0_p2wsh(&self) -> ScriptBuf

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

pub fn to_v1_p2tr<C>( &self, secp: &Secp256k1<C>, internal_key: XOnlyPublicKey ) -> ScriptBufwhere C: Verification,

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.

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_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). It also implies the script is unspendable.

pub fn is_witness_program(&self) -> bool

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

pub fn is_v0_p2wsh(&self) -> bool

Checks whether a script pubkey is a P2WSH output.

pub fn is_v0_p2wpkh(&self) -> bool

Checks whether a script pubkey is a P2WPKH output.

pub fn is_v1_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

Checks whether a script can be proven to have no satisfying input.

pub fn dust_value(&self) -> Amount

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

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<(), Error>

Writes the assembly decoding of the script to the formatter.

pub fn to_asm_string(&self) -> String

Returns the assembly decoding 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 is can be used.

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

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

pub fn into_script_buf(self: Box<Script, Global>) -> ScriptBuf

Converts a Box<Script> into a ScriptBuf without copying or allocating.

Trait Implementations

impl AsMut<[u8]> for Script

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

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

impl AsMut<Script> for Script

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

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

impl AsRef<[u8]> for Script

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

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

impl AsRef<Script> for Script

fn as_ref(&self) -> &Script

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

impl Debug for Script

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

Formats the value using the given formatter.

impl Display for Script

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

Formats the value using the given formatter.

impl Encodable for Script

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

Encodes an object with a well-defined format.

impl Hash for Script

fn hash<__H>(&self, state: &mut __H)where __H: Hasher,

Feeds this value into the given Hasher.

impl Index<(Bound<usize>, Bound<usize>)> for Script

Script subslicing operation - read slicing safety!

type Output = Script

The returned type after indexing.

fn index( &self, index: (Bound<usize>, Bound<usize>) ) -> &<Script as Index<(Bound<usize>, Bound<usize>)>>::Output

Performs the indexing (container[index]) operation.

impl Index<Range<usize>> for Script

Script subslicing operation - read slicing safety!

type Output = Script

The returned type after indexing.

fn index(&self, index: Range<usize>) -> &<Script as Index<Range<usize>>>::Output

Performs the indexing (container[index]) operation.

impl Index<RangeFrom<usize>> for Script

Script subslicing operation - read slicing safety!

type Output = Script

The returned type after indexing.

fn index( &self, index: RangeFrom<usize> ) -> &<Script as Index<RangeFrom<usize>>>::Output

Performs the indexing (container[index]) operation.

impl Index<RangeFull> for Script

Script subslicing operation - read slicing safety!

type Output = Script

The returned type after indexing.

fn index(&self, index: RangeFull) -> &<Script as Index<RangeFull>>::Output

Performs the indexing (container[index]) operation.

impl Index<RangeInclusive<usize>> for Script

Script subslicing operation - read slicing safety!

type Output = Script

The returned type after indexing.

fn index( &self, index: RangeInclusive<usize> ) -> &<Script as Index<RangeInclusive<usize>>>::Output

Performs the indexing (container[index]) operation.

impl Index<RangeTo<usize>> for Script

Script subslicing operation - read slicing safety!

type Output = Script

The returned type after indexing.

fn index( &self, index: RangeTo<usize> ) -> &<Script as Index<RangeTo<usize>>>::Output

Performs the indexing (container[index]) operation.

impl Index<RangeToInclusive<usize>> for Script

Script subslicing operation - read slicing safety!

type Output = Script

The returned type after indexing.

fn index( &self, index: RangeToInclusive<usize> ) -> &<Script as Index<RangeToInclusive<usize>>>::Output

Performs the indexing (container[index]) operation.

impl LowerHex for Script

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

Formats the value using the given formatter.

impl Ord for Script

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

This method returns an Ordering between self and other.

impl PartialEq<Script> for Script

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 PartialOrd<Script> for Script

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 ToOwned for Script

type Owned = ScriptBuf

The resulting type after obtaining ownership.

fn to_owned(&self) -> <Script as ToOwned>::Owned

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

Uses borrowed data to replace owned data, usually by cloning.

impl UpperHex for Script

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

Formats the value using the given formatter.

impl Eq for Script

impl StructuralEq for Script

impl StructuralPartialEq for Script