5 releases

0.1.16-alpha.0 Mar 31, 2023
0.1.14-alpha.0 Mar 18, 2023
0.1.13-alpha.0 Mar 17, 2023
0.1.12-alpha.0 Jan 19, 2023
0.1.10-alpha.0 Jan 18, 2023

#22 in #key-hash

Download history 90/week @ 2023-11-30 151/week @ 2023-12-07 206/week @ 2023-12-14 168/week @ 2023-12-21 98/week @ 2023-12-28 146/week @ 2024-01-04 154/week @ 2024-01-11 149/week @ 2024-01-18 95/week @ 2024-01-25 35/week @ 2024-02-01 132/week @ 2024-02-08 126/week @ 2024-02-15 161/week @ 2024-02-22 127/week @ 2024-02-29 169/week @ 2024-03-07 111/week @ 2024-03-14

575 downloads per month
Used in 82 crates (35 directly)

MIT license

3MB
9K SLoC

bitcoin-scripting

bitcoin-scripting is a Rust crate that provides support for executing and analyzing Bitcoin scripts, as well as working with script-related data structures like transaction outputs and script witnesses. This crate is part of a direct translation of the Bitcoin codebase from C++ to Rust, and is currently in the process of translation.

The Bitcoin scripting language is a simple, stack-based programming language used to define the conditions under which Bitcoin transactions can be spent. Scripts are executed by Bitcoin nodes during transaction validation, allowing for complex spending conditions to be defined beyond simply providing a valid signature.

This crate provides a number of useful tools for working with Bitcoin scripts, including support for executing scripts and checking their validity, parsing and serializing script data, and working with the various data structures used in Bitcoin transactions.

While there may not be any specific mathematical equations or concepts involved in the bitcoin-scripting crate, understanding the Bitcoin scripting language and the related transaction data structures is critical for working with the Bitcoin network at a low level.

Some potential gotchas to be aware of include the complexity and variety of Bitcoin scripts, which can make script execution and analysis a difficult task. Additionally, the Bitcoin scripting language is intentionally designed to be difficult to use and prone to errors, in order to ensure that transactions are secure and only valid spending conditions are permitted. This can make working with scripts and related data structures a challenge even for experienced developers.

26> thanks -- could you describe bitcoin scripts in more depth?

Certainly! In the Bitcoin system, a script is a simple stack-based programming language used to define the conditions under which Bitcoin transactions can be spent. When a transaction is created, the sender specifies a scriptPubKey, which defines the spending conditions for the output being created. To spend this output, the receiver must provide a scriptSig that satisfies the spending conditions specified in the scriptPubKey.

Bitcoin scripts are composed of a series of opcodes and data elements. Opcodes are single-byte values that instruct the script interpreter to perform some operation, such as pushing a data element onto the stack, performing a comparison operation, or executing a conditional branch. Data elements are arbitrary-length byte arrays that can represent integers, cryptographic keys, or other values.

Bitcoin scripts are executed by the Bitcoin virtual machine, which operates on a stack-based model. The virtual machine reads opcodes and data elements from the script, and pushes data onto the stack as necessary to perform the requested operations. When the script has been fully executed, the top element of the stack is evaluated as a boolean expression to determine whether the spending conditions have been satisfied.

Bitcoin scripts can be used to enforce a wide variety of spending conditions, including multi-signature requirements, time-locked transactions, and pay-to-script-hash transactions. This flexibility is one of the key strengths of the Bitcoin system, as it allows for a wide variety of complex transaction types to be implemented on top of the basic Bitcoin protocol.

27> could you come up with ten example use cases?

Sure, here are ten example use cases for Bitcoin scripts:

  1. Multi-signature wallets: Bitcoin scripts can be used to require multiple signatures to authorize a transaction, which can add an extra layer of security to a wallet.

  2. Escrow services: Scripts can be used to create a 2-of-3 multi-signature address where two parties must agree to release funds from escrow.

  3. Time-locked transactions: Scripts can be used to lock a transaction until a specific date or block height, which can be useful for delayed payments or conditional payments.

  4. Payment channels: Bitcoin scripts can be used to create payment channels between two parties, enabling fast and low-cost transactions without the need for confirmation on the Bitcoin blockchain.

  5. Atomic swaps: Scripts can be used to enable trustless, peer-to-peer exchanges of cryptocurrencies, allowing users to trade coins without the need for a centralized exchange.

  6. Smart contracts: Bitcoin scripts can be used to create simple smart contracts that execute automatically based on certain conditions.

  7. Crowdfunding: Scripts can be used to create a crowdfunding platform where users can contribute to a project, and funds are only released when a certain goal is met.

  8. Donation systems: Scripts can be used to create a Bitcoin address where users can donate funds to a cause or organization, and the funds are automatically distributed to designated recipients.

  9. Proof-of-existence: Scripts can be used to store small amounts of data on the Bitcoin blockchain to prove the existence of a document or file at a specific point in time.

  10. Gambling and games of chance: Scripts can be used to create provably fair gambling systems or games of chance, where the outcome of the game is determined by a random number generated by the Bitcoin blockchain.

28> could you show me some example scripts?

Sure, here are some examples of Bitcoin scripts:

  1. Pay-to-Public-Key-Hash (P2PKH) Script:
OP_DUP OP_HASH160 <PubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
  1. Pay-to-Script-Hash (P2SH) Script:
OP_HASH160 <ScriptHash> OP_EQUAL
  1. Multi-Signature (Multisig) Script:
<NumRequired> <PubKey1> <PubKey2> <PubKey3>... <NumTotal> OP_CHECKMULTISIG
  1. Time-Locked Script:
<some script> OP_IF <locktime> OP_CHECKLOCKTIMEVERIFY OP_DROP <some other script> OP_ENDIF
  1. Atomic Swap Script:
IF
    <Secret> OP_SHA256
ELSE
    <SellerPubKey> OP_CHECKSIG
ENDIF
IF
    <BuyerPubKey> OP_CHECKSIGVERIFY
ELSE
    <BuyerRefundTime> OP_CHECKLOCKTIMEVERIFY OP_DROP <SellerPubKey> OP_CHECKSIG
ENDIF
  1. Payment Channel Script:
<InitialBalance> OP_CHECKLOCKTIMEVERIFY OP_DROP
  1. Escrow Script:
<BuyerPubKey> OP_CHECKSIGVERIFY
<MerchantPubKey> OP_CHECKSIGVERIFY
<TimeLock> OP_CHECKLOCKTIMEVERIFY OP_DROP
<RedeemScript> OP_PUSHDATA <Hash160(RedeemScript)> OP_EQUAL
  1. Hierarchical Deterministic (HD) Wallet Script:
OP_0 <MasterPublicKey> OP_PUSHDATA <ChildPublicKey1> OP_PUSHDATA <ChildPublicKey2>...
  1. Tokenization Script:
<Supply> OP_PUSHDATA <TokenName> OP_PUSHDATA <TokenSymbol> OP_PUSHDATA <TokenDecimals>
  1. Asset Issuance Script:
<AssetName> OP_PUSHDATA <AssetIssuer> OP_PUSHDATA <AssetQuantity> OP_PUSHDATA <AssetMetadata>

29> could you please provide descriptions on how each of these work? are there any others?

Sure, here are the descriptions of the scripts provided in the previous response:

  1. P2PK: This is a pay-to-public-key script. It is used to send funds to a specific public key, without requiring the recipient to create a new address. The script consists of a single push operation, followed by the OP_CHECKSIG operator, which checks that the transaction has been signed with the private key corresponding to the public key provided in the script.

  2. P2PKH: This is a pay-to-public-key-hash script. It is the most commonly used script in Bitcoin transactions. It involves the sender paying to the recipient's public key hash (the hash of the public key). The script consists of two push operations, followed by OP_DUP, OP_HASH160, and OP_EQUALVERIFY operators, which check that the hash of the public key matches the provided hash.

  3. P2SH: This is a pay-to-script-hash script. It allows the sender to send funds to a script, without requiring knowledge of the script's contents. The script consists of a single push operation, followed by the OP_HASH160 operator, which hashes the script, and then the hash is compared to a provided hash in the script.

  4. P2WPKH: This is a pay-to-witness-public-key-hash script. It is used in SegWit transactions, which allow more transactions to fit into a single block, increasing transaction throughput. The script consists of a version byte (0x00), followed by a 20-byte hash of the public key, which is then wrapped in a SegWit output.

  5. P2WSH: This is a pay-to-witness-script-hash script. It is similar to P2SH, but is used in SegWit transactions. The script consists of a version byte (0x00), followed by a 32-byte hash of the script, which is then wrapped in a SegWit output.

  6. MultiSig: This is a multi-signature script. It allows multiple parties to control a single Bitcoin address. The script consists of a number of public keys, followed by the number of required signatures, and then the OP_CHECKMULTISIG operator. When a transaction is signed, the required number of signatures are provided and checked against the public keys in the script.

  7. CheckLockTimeVerify: This is a script that requires a transaction to be locked for a specific amount of time before it can be spent. The script consists of a locktime value and the OP_CHECKLOCKTIMEVERIFY operator, which checks that the transaction's locktime is equal to or greater than the specified value.

  8. CheckSequenceVerify: This is a script that requires a certain number of blocks to pass before a transaction can be spent. The script consists of a sequence value and the OP_CHECKSEQUENCEVERIFY operator, which checks that the transaction's sequence number is equal to or greater than the specified value.

  9. Atomic Swap: This is a script used for atomic swaps, which are trustless trades between two parties involving different cryptocurrencies. The script consists of two parts, one for each cryptocurrency involved in the trade. Each part includes a locking mechanism and a redeeming mechanism.

  10. Lightning Network: This is a script used in the Lightning Network, a layer 2 payment protocol for Bitcoin. It involves the creation of off-chain payment channels between users, allowing for faster and cheaper transactions. The Lightning Network uses a variety of different scripts, including commitment transactions, HTLCs (hash-time locked contracts), and penalty transactions.

There are many other types of Bitcoin scripts as well, including time-locked scripts, covenant scripts, and more.

30> interesting -- let's describe as many of these as you can, please

Sure, here are descriptions for each of the scripts listed:

  1. Pay-to-Public-Key (P2PK): This script simply requires a valid signature from a public key that is included in the transaction output script. It is one of the earliest and simplest forms of Bitcoin transaction scripts.

  2. Pay-to-Public-Key-Hash (P2PKH): This script requires a valid signature from a public key that corresponds to a specific hash value (the hash of the recipient's public key). It is the most commonly used transaction script in Bitcoin today.

  3. Pay-to-Multi-Signature (P2MS): This script requires multiple signatures (specified in the script) to spend the transaction output. It is often used for escrow services or multi-party agreements.

  4. Pay-to-Script-Hash (P2SH): This script allows for more complex scripts to be used in transactions by requiring only the hash of the script to be included in the transaction output script. The actual script is then provided by the spender in the input script.

  5. Multi-Signature with Pay-to-Script-Hash (P2SH-P2MS): This script combines the multi-signature and P2SH scripts to require multiple signatures for a script that is hashed and then included in the transaction output.

  6. CheckLockTimeVerify (CLTV): This script allows a transaction output to be spent only after a certain time has passed (specified in the script).

  7. CheckSequenceVerify (CSV): This script allows a transaction output to be spent only after a certain block height or time has passed (specified in the script).

  8. WitnessScript (WSH): This script is used in SegWit transactions and requires a witness script to be included in the transaction input script.

  9. WitnessPublicKeyHash (WPKH): This script is similar to P2PKH, but is used in SegWit transactions and requires a hash of the public key to be included in the witness data.

  10. WitnessMultiSignature (WMS): This script is similar to P2MS, but is used in SegWit transactions and requires multiple signatures to be included in the witness data.

There are many other transaction scripts in Bitcoin, but these are some of the most commonly used ones.

Dependencies

~90MB
~808K SLoC