Class BSV::Transaction::Beef ¶

Inherits: Object

Background Evaluation Extended Format (BEEF) for SPV-ready transaction bundles. Encodes one or more transactions together with their merkle proofs (BUMPs), enabling recipients to verify inclusion without querying a block explorer.

Supports BRC-62 (V1), BRC-96 (V2), and BRC-95 (Atomic BEEF) formats.

@example Parse a BEEF bundle and find a transaction

beef = BSV::Transaction::Beef.from_hex(beef_hex)
tx = beef.find_transaction(txid_bytes)

Constants¶

Version constants¶

ATOMIC_BEEF ¶

BRC-96

BEEF_V1 ¶

Version magic bytes as LE uint32 (matching pack('V') / unpack1('V')). Stream bytes: 01 00 BE EF / 02 00 BE EF / 01 01 01 01

BEEF_V2 ¶

BRC-62

Transaction format flags¶

FORMAT_RAW_TX ¶

Raw transaction without a merkle proof.

FORMAT_RAW_TX_AND_BUMP ¶

Raw transaction with an associated BUMP index.

FORMAT_TXID_ONLY ¶

Only the transaction ID (no raw data).

Attributes¶

bumps [R] ¶

• @return [Array] merkle proofs (BUMPs) referenced by transactions

subject_txid [R] ¶

• @return [String, nil] 32-byte subject txid (Atomic BEEF only)

transactions [R] ¶

• @return [Array] the transactions in dependency order

version [R] ¶

• @return [Integer] BEEF version constant

Public Class Methods¶

from_binary(data) ¶

Deserialise a BEEF bundle from binary data.

Supports V1 (BRC-62), V2 (BRC-96), and Atomic (BRC-95) formats. After parsing, input source transactions are wired automatically. - @param data [String] raw BEEF binary - @raise [ArgumentError] - @return [Beef] the parsed BEEF bundle

from_hex(hex) ¶

Deserialise a BEEF bundle from a hex string. - @param hex [String] hex-encoded BEEF data - @return [Beef] the parsed BEEF bundle

Public Instance Methods¶

find_atomic_transaction(txid) ¶

Find a transaction and recursively wire its ancestry (source transactions and merkle paths) for atomic proof validation. - @param txid [String] 32-byte txid in display byte order - @return [Transaction, nil] the transaction with full proof tree, or nil

find_bump(txid) ¶

Find the merkle path (BUMP) for a transaction by its txid. - @param txid [String] 32-byte txid in display byte order - @return [MerklePath, nil] the merkle path, or nil if not found

find_transaction(txid) ¶

Find a transaction in the bundle by its transaction ID. - @param txid [String] 32-byte txid in display byte order - @return [Transaction, nil] the matching transaction, or nil

find_transaction_for_signing(txid) ¶

Find a transaction with all source_transactions wired for signing. - @param txid [String] 32-byte txid in display byte order - @return [Transaction, nil] the transaction with wired inputs, or nil

initialize(version: = BEEF_V2, bumps: = [], transactions: = []) ¶

• @param version [Integer] BEEF version constant (default: BEEF_V2)
• @param bumps [Array] merkle proofs
• @param transactions [Array] transaction entries
• @return [Beef] a new instance of Beef

make_txid_only(txid) ¶

Convert a transaction entry to TXID-only format. - @param txid [String] 32-byte txid in display byte order - @return [BeefTx, nil] the converted entry, or nil if not found

merge(other) ¶

Merge all BUMPs and transactions from another BEEF bundle.

BUMP indices are remapped during merge. - @param other [Beef] the BEEF bundle to merge from - @return [self]

merge_bump(merkle_path) ¶

Add or deduplicate a merkle path (BUMP) in this BEEF bundle.

If an existing BUMP shares the same block_height and merkle root, it is combined (via MerklePath#combine) and the existing index is returned. Otherwise the BUMP is appended. - @param merkle_path [MerklePath] the BUMP to merge - @return [Integer] the index of the (possibly merged) BUMP

merge_raw_tx(raw_bytes, bump_index: = nil) ¶

Add a transaction from raw binary data. - @param raw_bytes [String] raw transaction binary - @param bump_index [Integer, nil] optional BUMP index - @return [BeefTx] the new BeefTx entry

merge_transaction(tx) ¶

Add a transaction to this BEEF bundle.

Recursively merges the transaction's ancestors (via source_transaction references on inputs) and their merkle paths. Duplicate transactions (same txid) are not re-added. - @param tx [Transaction] the transaction to merge - @return [BeefTx] the (possibly existing) BeefTx entry

sort_transactions!() ¶

Sort transactions in topological (dependency) order in place.

After sorting, every transaction's input ancestors appear before it in the array. This is required for correct BEEF serialisation. - @return [self]

to_atomic_binary(subject_txid) ¶

Serialise as Atomic BEEF (BRC-95), wrapping V2 data with a subject txid. - @param subject_txid [String] 32-byte subject transaction ID - @return [String] raw Atomic BEEF binary

to_atomic_hex(subject_txid) ¶

Serialise as Atomic BEEF (BRC-95) hex string. - @param subject_txid [String] 32-byte subject transaction ID - @return [String] hex-encoded Atomic BEEF

to_binary() ¶

Serialise the BEEF bundle to V2 (BRC-96) binary format. - @return [String] raw BEEF binary

to_hex() ¶

Serialise the BEEF bundle to a V2 hex string. - @return [String] hex-encoded BEEF data

valid?(allow_txid_only: = false) ¶

Check structural validity of the BEEF bundle.

A valid BEEF has every transaction either: * proven (has a BUMP / merkle_path), or * all its inputs reference transactions that are themselves valid within this bundle. - @param allow_txid_only [Boolean] whether TXID-only entries count as valid (default: false) - @return [Boolean] true if structurally valid