// SPDX-License-Identifier: CC0-1.0 //! Bitcoin scripts. //! //! *[See also the `Script` type](Script).* //! //! This module provides the structures and functions needed to support scripts. //! //!
//! What is Bitcoin script //! //! Scripts define Bitcoin's digital signature scheme: a signature is formed //! from a script (the second half of which is defined by a coin to be spent, //! and the first half provided by the spending transaction), and is valid iff //! the script leaves `TRUE` on the stack after being evaluated. Bitcoin's //! script is a stack-based assembly language similar in spirit to [Forth]. //! //! Script is represented as a sequence of bytes on the wire, each byte representing an operation, //! or data to be pushed on the stack. //! //! See [Bitcoin Wiki: Script][wiki-script] for more information. //! //! [Forth]: https://en.wikipedia.org/wiki/Forth_(programming_language) //! //! [wiki-script]: https://en.bitcoin.it/wiki/Script //!
//! //! In this library we chose to keep the byte representation in memory and decode opcodes only when //! processing the script. This is similar to Rust choosing to represent strings as UTF-8-encoded //! bytes rather than slice of `char`s. In both cases the individual items can have different sizes //! and forcing them to be larger would waste memory and, in case of Bitcoin script, even some //! performance (forcing allocations). //! //! ## `Script` vs `ScriptBuf` vs `Builder` //! //! These are the most important types in this module and they are quite similar, so it may seem //! confusing what the differences are. `Script` is an unsized type much like `str` or `Path` are //! and `ScriptBuf` is an owned counterpart to `Script` just like `String` is an owned counterpart //! to `str`. //! //! However it is common to construct an owned script and then pass it around. For this case a //! builder API is more convenient. To support this we provide `Builder` type which is very similar //! to `ScriptBuf` but its methods take `self` instead of `&mut self` and return `Self`. It also //! contains a cache that may make some modifications faster. This cache is usually not needed //! outside of creating the script. //! //! At the time of writing there's only one operation using the cache - `push_verify`, so the cache //! is minimal but we may extend it in the future if needed. mod borrowed; mod builder; mod instruction; mod owned; mod push_bytes; #[cfg(test)] mod tests; pub mod witness_program; pub mod witness_version; use alloc::rc::Rc; #[cfg(any(not(rust_v_1_60), target_has_atomic = "ptr"))] use alloc::sync::Arc; use core::borrow::{Borrow, BorrowMut}; use core::cmp::Ordering; use core::fmt; use core::ops::{Deref, DerefMut}; use hashes::{hash160, sha256}; use io::{BufRead, Write}; #[cfg(feature = "serde")] use serde; use crate::blockdata::opcodes::all::*; use crate::blockdata::opcodes::{self, Opcode}; use crate::consensus::{encode, Decodable, Encodable}; use crate::internal_macros::impl_asref_push_bytes; use crate::prelude::*; use crate::{io, OutPoint}; #[rustfmt::skip] // Keep public re-exports separate. #[doc(inline)] pub use self::{ borrowed::*, builder::*, instruction::*, owned::*, push_bytes::*, }; hashes::hash_newtype! { /// A hash of Bitcoin Script bytecode. pub struct ScriptHash(hash160::Hash); /// SegWit version of a Bitcoin Script bytecode hash. pub struct WScriptHash(sha256::Hash); } impl_asref_push_bytes!(ScriptHash, WScriptHash); impl From for ScriptHash { fn from(script: ScriptBuf) -> ScriptHash { script.script_hash() } } impl From<&ScriptBuf> for ScriptHash { fn from(script: &ScriptBuf) -> ScriptHash { script.script_hash() } } impl From<&Script> for ScriptHash { fn from(script: &Script) -> ScriptHash { script.script_hash() } } impl From for WScriptHash { fn from(script: ScriptBuf) -> WScriptHash { script.wscript_hash() } } impl From<&ScriptBuf> for WScriptHash { fn from(script: &ScriptBuf) -> WScriptHash { script.wscript_hash() } } impl From<&Script> for WScriptHash { fn from(script: &Script) -> WScriptHash { script.wscript_hash() } } /// Encodes an integer in script(minimal CScriptNum) format. /// /// Writes bytes into the buffer and returns the number of bytes written. /// /// Note that `write_scriptint`/`read_scriptint` do not roundtrip if the value written requires /// more than 4 bytes, this is in line with Bitcoin Core (see [`CScriptNum::serialize`]). /// /// [`CScriptNum::serialize`]: pub fn write_scriptint(out: &mut [u8; 8], n: i64) -> usize { let mut len = 0; if n == 0 { return len; } let neg = n < 0; let mut abs = n.unsigned_abs(); while abs > 0xFF { out[len] = (abs & 0xFF) as u8; len += 1; abs >>= 8; } // If the number's value causes the sign bit to be set, we need an extra // byte to get the correct value and correct sign bit if abs & 0x80 != 0 { out[len] = abs as u8; len += 1; out[len] = if neg { 0x80u8 } else { 0u8 }; len += 1; } // Otherwise we just set the sign bit ourselves else { abs |= if neg { 0x80 } else { 0 }; out[len] = abs as u8; len += 1; } len } /// Decodes an integer in script(minimal CScriptNum) format. /// /// Notice that this fails on overflow: the result is the same as in /// bitcoind, that only 4-byte signed-magnitude values may be read as /// numbers. They can be added or subtracted (and a long time ago, /// multiplied and divided), and this may result in numbers which /// can't be written out in 4 bytes or less. This is ok! The number /// just can't be read as a number again. /// This is a bit crazy and subtle, but it makes sense: you can load /// 32-bit numbers and do anything with them, which back when mult/div /// was allowed, could result in up to a 64-bit number. We don't want /// overflow since that's surprising --- and we don't want numbers that /// don't fit in 64 bits (for efficiency on modern processors) so we /// simply say, anything in excess of 32 bits is no longer a number. /// This is basically a ranged type implementation. /// /// This code is based on the `CScriptNum` constructor in Bitcoin Core (see `script.h`). pub fn read_scriptint(v: &[u8]) -> Result { let last = match v.last() { Some(last) => last, None => return Ok(0), }; if v.len() > 4 { return Err(Error::NumericOverflow); } // Comment and code copied from Bitcoin Core: // https://github.com/bitcoin/bitcoin/blob/447f50e4aed9a8b1d80e1891cda85801aeb80b4e/src/script/script.h#L247-L262 // If the most-significant-byte - excluding the sign bit - is zero // then we're not minimal. Note how this test also rejects the // negative-zero encoding, 0x80. if (*last & 0x7f) == 0 { // One exception: if there's more than one byte and the most // significant bit of the second-most-significant-byte is set // it would conflict with the sign bit. An example of this case // is +-255, which encode to 0xff00 and 0xff80 respectively. // (big-endian). if v.len() <= 1 || (v[v.len() - 2] & 0x80) == 0 { return Err(Error::NonMinimalPush); } } Ok(scriptint_parse(v)) } /// Decodes an integer in script format without non-minimal error. /// /// The overflow error for slices over 4 bytes long is still there. /// See [`read_scriptint`] for a description of some subtleties of /// this function. pub fn read_scriptint_non_minimal(v: &[u8]) -> Result { if v.is_empty() { return Ok(0); } if v.len() > 4 { return Err(Error::NumericOverflow); } Ok(scriptint_parse(v)) } // Caller to guarantee that `v` is not empty. fn scriptint_parse(v: &[u8]) -> i64 { let (mut ret, sh) = v.iter().fold((0, 0), |(acc, sh), n| (acc + ((*n as i64) << sh), sh + 8)); if v[v.len() - 1] & 0x80 != 0 { ret &= (1 << (sh - 1)) - 1; ret = -ret; } ret } /// Decodes a boolean. /// /// This is like "`read_scriptint` then map 0 to false and everything /// else as true", except that the overflow rules don't apply. #[inline] pub fn read_scriptbool(v: &[u8]) -> bool { match v.split_last() { Some((last, rest)) => !((last & !0x80 == 0x00) && rest.iter().all(|&b| b == 0)), None => false, } } // We internally use implementation based on iterator so that it automatically advances as needed // Errors are same as above, just different type. fn read_uint_iter(data: &mut core::slice::Iter<'_, u8>, size: usize) -> Result { if data.len() < size { Err(UintError::EarlyEndOfScript) } else if size > usize::from(u16::MAX / 8) { // Casting to u32 would overflow Err(UintError::NumericOverflow) } else { let mut ret = 0; for (i, item) in data.take(size).enumerate() { ret = usize::from(*item) // Casting is safe because we checked above to not repeat the same check in a loop .checked_shl((i * 8) as u32) .ok_or(UintError::NumericOverflow)? .checked_add(ret) .ok_or(UintError::NumericOverflow)?; } Ok(ret) } } fn opcode_to_verify(opcode: Option) -> Option { opcode.and_then(|opcode| match opcode { OP_EQUAL => Some(OP_EQUALVERIFY), OP_NUMEQUAL => Some(OP_NUMEQUALVERIFY), OP_CHECKSIG => Some(OP_CHECKSIGVERIFY), OP_CHECKMULTISIG => Some(OP_CHECKMULTISIGVERIFY), _ => None, }) } // We keep all the `Script` and `ScriptBuf` impls together since its easier to see side-by-side. impl From for Box