BSV blockchainBSV blockchain

BEEF (BRC-62)

BEEFBackground Evaluation Extended Format (BRC-62) is the binary format the BSV blockchain uses to send a transaction together with the proof that the outputs it spends exist in the chain. An app or wallet that receives a BEEF checks that proof against block headers it already has, instead of asking a node about the transaction. This check is called SPVSimplified Payment Verification (BRC-67).

How an app verifies a transaction without a node

A receiver verifies a BEEF in three checks, and the first one proves that a transaction is in a block.

The proof

The diagram shows a block of eight transactions. Select one and press Play to see the hashes a receiver needs to prove it is in the block, which a BEEF carries in a BUMPBSV Unified Merkle Path (BRC-74). Then set the root in the block header to Differs and play again.

Select a transaction, then press Play
The root in the block header
Block headerMerkle roottx 0tx 1tx 2tx 3tx 4tx 5tx 6tx 7H 0-1H 2-3H 4-5H 6-7H 0-3H 4-7root

tx 5 is selected. To prove it, the BUMP keeps only the three hashes marked in amber, out of the eight transactions in this block.

0 of 5.

A block header commits to every transaction in its block through the Merkle root, so a Merkle pathThe chain of hashes that links one transaction to the Merkle root of its block from a transaction up to that root proves it is in the block. The receiver needs the headers to check it, not the blocks. A block of 4,096 transactions would need 12 hashes, not 4,096.

The three checks

An app that receives a BEEF runs three checks, in this order:

Compute the roots

The app computes one Merkle root for each BUMP in the BEEF.

Check the headers

The app asks a chain trackerThe part of the SDK that checks a Merkle root against the block headers of a network whether each root belongs to the block at the height in its BUMP. If one does not, the BEEF is rejected and nothing else is checked.

Check the transactions without a proof

For each of these, the app confirms that its inputs spend outputs of transactions it has already verified, that every script evaluates to true, and that the satoshisThe smallest unit of BitcoinSV (BSV). 100,000,000 satoshis make 1 BSV in cover the satoshis out plus the fee.

A BEEF shows that the transaction spends outputs that exist in a block and that its scripts pass. It does not show that nobody spent those outputs in another transaction. BRC-62 names this limit and describes the format as intended for micropayments, where the risk is low.

What is inside a BEEF

A BEEF is a list of Merkle paths, called BUMPs, followed by a list of transactions.

Layout and order

The diagram shows one BEEF that carries a single payment, as the chain the receiver checks and as the bytes that carry it. Select any part to see what it is and where it sits in the other row.

Select a part of the BEEF, in either row

What the receiver checks

What the BEEF carries, in byte order

The chain on top is what the receiver checks, and the bytes below are what the BEEF carries. The same color marks the same part in both rows.

The Merkle paths come first and each transaction comes after the ones it spends, so a receiver can start verifying from the first bytes, before the whole BEEF has arrived.

Merkle paths

Each BUMP records the height of the block, which tells the receiver which header to compare against. It then records, level by level, only the hashes needed to reach the Merkle root, the ones marked in amber in the tree under The proof.

One BUMP can hold the paths of several transactions in the same block and share the hashes they have in common. A BEEF with two mined ancestors from the same block therefore carries one BUMP, not two.

Ancestors

Each input of a transaction spends an output of an earlier transaction, so verifying the transaction means following its inputs back. A BEEF carries those earlier transactions up to the first ones that have a Merkle path. A mined ancestor brings its BUMP and none of its own parents. A transaction that spends unconfirmed outputs brings those parents as well, until every branch ends at a mined transaction.

A BEEF whose oldest transactions have no Merkle path has nothing to anchor to, and it does not verify.

BEEF forms and where each one is used

Three forms of BEEF are in use. They share the same Merkle paths and transactions and differ in the prefix and in what they allow, and each interface picks one of them.

The three forms

FormBRCStarts withWhat it is
BEEF V1BRC-620100beefThe Merkle paths first, then the transactions in order, each with a flag for its BUMP
BEEF V2BRC-960200beefA format byte before each transaction: 00 for a raw transaction, 01 for a raw transaction with a BUMP index and 02 for a transaction ID only. A BEEF can hold several separate transaction trees
Atomic BEEFBRC-9501010101, then the ID of the subject transactionA complete BEEF whose transactions are all in the ancestry of the subject transaction. Nothing unrelated is allowed

An entry with only a transaction ID stands for a transaction the receiver already verified. In @bsv/sdk it counts only when you pass true as the allowTxidOnly argument of isValid or verify, for example beef.verify(tracker, true). Without it, the BEEF does not verify.

In an Atomic BEEF, @bsv/sdk writes the transaction ID in the prefix in the byte order of the serialized transaction, which is the reverse of the ID as an explorer shows it.

Where each form is used

A wallet makes and reads BEEFs for the app, so an app rarely builds one itself. Each interface below uses one form:

WhereForm
tx in the result of createAction, and tx in internalizeAction, in BRC-100The standard interface between an app and a walletAtomic BEEF
inputBEEF in createActionBEEF
The request body when you submit a transaction to an overlay serviceBuilt from topic managers, which decide what is admitted, and lookup services, which query what was admitted., in BRC-22BEEF
A payment between two parties, in BRC-29Atomic BEEF
The x-bsv-beef header of an HTTP 402 payment, in BRC-121, encoded as base64Atomic BEEF

Read and make a BEEF with the SDK

The examples were written against @bsv/sdk 4.0.1 and run on testnet.

Read and verify a BEEF

To read a BEEF and check it against the block headers of testnet:

import { Beef, Utils, WhatsOnChain } from '@bsv/sdk'

const beefHex = 'BEEF_HEX' // replace with a testnet BEEF as hex, for example from a wallet or a request

const beef = Beef.fromBinary(Utils.toArray(beefHex, 'hex'))
const isValid = await beef.verify(new WhatsOnChain('test'))
console.log(isValid)

For a BEEF whose Merkle roots match the testnet headers, it prints:

true
  • Beef.fromBinary reads V1, V2 and Atomic BEEF. Compare beef.version with BEEF_V1 and BEEF_V2 to tell which version it is.
  • verify returns false when a root does not match a header and when the BEEF has no Merkle path to anchor to. It covers the first two checks above and the link between each transaction and its inputs. It does not evaluate scripts or compare satoshis, so true is not proof that a payment is valid.
  • To run the third check too, read the transaction and call Transaction.fromHexBEEF(beefHex).verify(new WhatsOnChain('test')). It evaluates the scripts and returns true when they pass. It checks the fee only when you pass a fee model as the second argument.
  • WhatsOnChain is a chain tracker backed by the WhatsOnChain service. Any object with isValidRootForHeight and currentHeight methods works in its place, for example one backed by your own header store.

A chain tracker belongs to one network. new WhatsOnChain() defaults to Mainnet, so a testnet BEEF checked with it fails. Pass 'test' on testnet and 'main' on Mainnet.

Make a BEEF

To make a BEEF from a transaction that is signed, has its inputs’ source transactions set, and has a merklePath on the oldest ancestors:

import { Transaction, Utils } from '@bsv/sdk'

// replace with a testnet BEEF as hex. In your own app, tx is a signed
// transaction with sourceTransaction on each input
const tx = Transaction.fromHexBEEF('BEEF_HEX')

const beefHex = tx.toHexBEEF()
const atomicBeef = tx.toAtomicBEEF()

console.log(beefHex.slice(0, 8))
console.log(Utils.toHex(atomicBeef.slice(0, 4)))

It prints the start of each form:

0100beef
01010101
  • toHexBEEF returns a V1 BEEF as hex, and toAtomicBEEF returns an Atomic BEEF as an array of bytes, with tx as the subject transaction.
  • A transaction that you read with Transaction.fromAtomicBEEF, Transaction.fromHexBEEF or Transaction.fromBEEF already has its ancestors attached. toHexBEEF rebuilds a V1 BEEF from them, so a V1 input comes back unchanged, while an Atomic or V2 input comes back as V1, without the Atomic prefix and subject transaction ID. Use toAtomicBEEF when the receiver expects Atomic BEEF.
  • A new Beef() that you fill by hand is V2 by default. Pass BEEF_V1 to the constructor when the receiver expects V1.

To learn more about verifying transactions on the BSV blockchain, review these articles: