bips Documentation

Bitcoin Improvement Proposals

10,970 stars Wikitext 1 file · ~3,306 tokens
RAW Doc

Technical Documentation: bitcoin/bips

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`bip-0375/README.md`)

BIP-375 Validation Reference

A reference validation implementation for BIP-375: Sending Silent Payments with PSBTs.

Core Files

  • validator/bip352_crypto.py - Silent payment output script derivation
  • validator/inputs.py - PSBT input utility functions
  • validator/psbt_bip375.py - BIP-375 specific PSBT/PSBTMap extensions
  • validator/validate_psbt.py - Main BIP-375 validation functions
  • test_runner.py - Test infrastructure (executable)

Dependencies

  • deps/bitcoin_test/psbt.py - Bitcoin test framework PSBT module - PR #21283
  • deps/bitcoin_test/messages.py - Bitcoin test framework primitives and message structures
  • deps/dleq.py - Reference DLEQ implementation from BIP-374
  • deps/secp256k1lab/ - vendored copy of secp256k1lab library at version 1.0.0

Testing

Run Tests

bash
python test_runner.py                    # Run all tests
python test_runner.py -v                 # Verbose mode with detailed validation status
python test_runner.py -vv                # More verbose with validation check failure reason

python test_runner.py -f vectors.json    # Use custom test vector file

Generating Test Vectors

Test vectors were generated using test_generator.py

Overview (`bip-0446/README.md`)

`OP_TEMPLATEHASH` test vectors

The test vectors are split into basic sanity checks and more extensive coverage. Both are JSON files containing a JSON
array of JSON objects. Each JSON object in the array represents a Script validation test case.

For basics.json, each object contains the following fields:

  • spending_tx: a hexadecimal string representing a serialized Bitcoin transaction. This is the transaction to be
    validated.
  • input_index: a JSON integer representing the index of the transaction input for which to perform Script validation.
  • spent_outputs: a JSON array of hexadecimal strings representing serialized Bitcoin transaction outputs. This is the
    list of outputs pointed to by the inputs of the transaction to be validated.
  • valid: a JSON boolean. Whether script validation should succeed.
  • comment: a JSON string. Reason why script validation should succeed or fail.

For script_assets_test.json, each object contains the following fields:

  • tx: a hexadecimal string representing a serialized Bitcoin transaction. This is the transaction to be validated.
  • index: a JSON integer representing the index of the transaction input for which to perform Script validation.
  • prevouts: a JSON array of hexadecimal strings representing serialized Bitcoin transaction outputs. This is the list
    of outputs pointed to by the inputs of the transaction to be validated.
  • flags: a JSON array of strings representing the script validation flags to enable for this test case.
  • success: an optional JSON object representing the transaction input fields to set such as script validation
    succeeds. The subfields are the following:
    • scriptSig: a JSON hexadecimal string representing the serialized input script.
    • witness: a JSON array of hexadecimal strings representing the witness stack for this input.
  • final: an optional JSON boolean which, if true, indicates script validation should always succeed with more
    validation flags than specified in flags.
  • failure: an optional JSON object representing the transaction input fields to set such as script validation
    fails. The subfields are the following:
    • scriptSig: a JSON hexadecimal string representing the serialized input script.
    • witness: a JSON array of hexadecimal strings representing the witness stack for this input.

Location of code that generated the test basics.json here. Example usage of script_assets_test.json here.

Overview (`bip-0054/test_vectors/README.md`)

BIP54 test vectors

This folder contains a set of test vectors for each mitigation introduced in the BIP. This document
presents them in more detail.

The code used to generate half of the test vectors is included with the implementation and available
here. The other half requires mining mainnet blocks and is published
separately. In both cases it is implemented as a regular Bitcoin Core unit test, and
the test vectors are persisted as a JSON file if the UPDATE_JSON_TESTS preprocessor directive is
set (off by default).

To compile the header and block miners you may have to link to
libatomic explicitly. This can be achieved like so:

text
cmake -B atomicbuild -DAPPEND_LDFLAGS="-latomic"
cmake --build atomicbuild/ -j $(nproc)

Premined headers are also provided along with the header miner to allow changing
some of the last headers without having to re-generate the whole chain.

Difficulty adjustment exploits

The timestamps.json test vectors exercise the two constraints on block header
timestamps introduced by BIP54 to mitigate the Timewarp and Murch-Zawy attacks. Each test case
features a chain of mainnet headers starting from the genesis block, and whether this header chain
is valid by BIP54 rules. Each test case also contains a comment describing why this particular chain
is (in)valid according to BIP54. All test cases are valid according to current Bitcoin consensus
rules. It is intended to be used to test a BIP54 implementation by feeding the header chain to a
Bitcoin node implementation, enforcing the BIP54 rules on this chain from genesis.

The test vector file contains a single JSON object, with child objects nested recursively in
extensions arrays. Each object contains a segment of a header chain, and its children contain
alternative continuations of that chain. Each path from the top-level object to a leaf represents
one complete test case, allowing test cases to share common prefixes.

Every object contains:

  • block_headers: a JSON array of strings containing consecutive, hex-encoded mainnet block
    headers. The top-level object's headers start with genesis. Each child object's headers directly
    follow the last header of its parent.

An object that branches into further continuations also contains:

  • extensions: a JSON array of child objects with the same format.

A leaf object has no extensions entry and instead contains:

  • valid: a JSON boolean indicating whether the complete header chain is valid according to BIP54.
  • comment: a JSON string describing the test case.

To reconstruct a test case's header chain, concatenate the block_headers arrays along the path
from the top-level object to that test case's leaf, in that order.

For the purpose of testing a Timewarp fix, a Timewarp attack was included early on in the history of
testnet3. An implementer of BIP54 may want to ensure that syncing testnet3 by enforcing BIP54 since
genesis will treat block 00000000118da1e2165a19307b86f87eba814845e8a0f99734dce279ca3fb029 as
invalid.

Long block validation time

The sigops.json file contains test vectors for the limit on the number of
potentially-executed legacy signature operations in a single transaction, introduced by BIP54 in
order to mitigate long block validation times. Each test case represents a transaction and whether a
block containing it would be valid according to BIP54. The test cases feature an extensive set of
combinations of inputs and output types, ways to run into the limit, historical violations and some
pathological transactions exhibiting the specific implementation details. All test cases but those
belonging to this last category feature transactions that are valid under current Bitcoin consensus
rules. Each test case also features a comment describing why the transaction is (in)valid according
to BIP54.

The test vector file features a JSON array of JSON objects, each corresponding to a test case. Each
JSON object features the following entries:

  • spent_outputs: a JSON array of strings. An ordered list of hex-encoded Bitcoin-serialized
    transaction outputs spent by each input of this test case's transaction.
  • tx: a JSON string. A hex-encoded Bitcoin-serialized transaction to be evaluated.
  • valid: a JSON boolean. Whether this transaction is valid according to current consensus rules
    supplemented by BIP54.
  • comment: a JSON string. Description of the test case.

Merkle tree malleability with 64-byte transactions

The txsize.json file contains test cases exercising the new constraint on
non-witness transaction size introduced in BIP54. Each test case contains a transaction and whether
it would be valid according to BIP54, as well as a comment describing why it is (in)valid. All test
cases are otherwise valid according to current Bitcoin consensus rules.

The test vector file features a JSON array of JSON objects, each corresponding to a test case. Each
JSON object features the following entries:

  • tx: a JSON string. A hex-encoded Bitcoin-serialized transaction to be evaluated.
  • valid: a JSON boolean. Whether this transaction is valid according to BIP54.
  • comment: a JSON string. Description of the test case.

Possibility of duplicate coinbase transactions

The coinbases.json file contains test cases exercising the new restrictions on
coinbase transactions introduced in BIP54 to prevent duplicate coinbase transactions without
resorting to BIP30 validation. Each test case contains a chain of mainnet blocks (including the
genesis block), and whether this block chain is valid according to BIP54. All test cases are valid
according to current Bitcoin's consensus rules, except one that features a block containing a
coinbase transaction timelocked to a future block height.

The test vector file features a JSON array of JSON objects, each corresponding to a test case. Each
JSON object features the following entries:

  • block_chain: a JSON array of strings. An ordered list of hex-encoded mainnet blocks.
  • valid: a JSON boolean. Whether this block chain is valid according to current Bitcoin consensus
    rules supplemented by BIP54.
  • comment: a JSON string. Description of the test case.

Overview (`bip-0352/secp256k1lab/README.md`)

secp256k1lab

An INSECURE implementation of the secp256k1 elliptic curve and related cryptographic schemes written in Python, intended for prototyping, experimentation and education.

Features:

  • Low-level secp256k1 field and group arithmetic.
  • Schnorr signing/verification and key generation according to BIP-340.
  • ECDH key exchange.

WARNING: The code in this library is slow and trivially vulnerable to side channel attacks.

Overview (`bip-0374/secp256k1lab/README.md`)

secp256k1lab

An INSECURE implementation of the secp256k1 elliptic curve and related cryptographic schemes written in Python, intended for prototyping, experimentation and education.

Features:

  • Low-level secp256k1 field and group arithmetic.
  • Schnorr signing/verification and key generation according to BIP-340.
  • ECDH key exchange.

WARNING: The code in this library is slow and trivially vulnerable to side channel attacks.

Overview (`bip-0375/deps/secp256k1lab/README.md`)

secp256k1lab

An INSECURE implementation of the secp256k1 elliptic curve and related cryptographic schemes written in Python, intended for prototyping, experimentation and education.

Features:

  • Low-level secp256k1 field and group arithmetic.
  • Schnorr signing/verification and key generation according to BIP-340.
  • ECDH key exchange.

WARNING: The code in this library is slow and trivially vulnerable to side channel attacks.

--- METRICS ---

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →