BSV blockchainBSV blockchain

How transactions and fees work

Read a BSV blockchain transaction part by part, see how it spends earlier outputs, and know where its fee comes from. The model is the same whether a wallet builds the transaction for your app or your code builds it with @bsv/sdk.

What a transaction contains

A transaction has four parts, serialized in this order, as BRC-12 specifies:

PartWhat it holds
VersionA 4-byte version number
InputsOne entry per output being spent, with the source transaction ID, the output index, an unlocking scriptThe part of an input that meets the condition set by the locking script of the output it spends and a sequence number
OutputsOne entry per new output, with an amount in satoshisThe smallest unit of BitcoinSV (BSV). 100,000,000 satoshis make 1 BSV and a locking scriptThe part of a transaction output that sets the condition to spend it
Lock timeWhen not zero, the earliest time or block height at which the transaction can go in a block, if at least one input has a sequence number below 0xFFFFFFFF

@bsv/sdk sets every sequence number to 0xFFFFFFFF by default, so a lock time has no effect until you lower one.

The scripts hold the rules. The locking script of an output sets the condition to spend it, and the unlocking script of the input that spends it meets that condition.

The transaction ID is the double SHA-256 hash of the whole serialized transaction. A change to any part gives a different transaction ID.

How inputs spend outputs

Ownership on the BSV blockchain is a set of outputs, not an account balance. An output that nobody has spent yet is a UTXOUnspent transaction output, and a later transaction spends it with an input that points to it:

  1. 1Earlier transaction

    Creates output 0 with an amount and a locking script. Nobody has spent it, so it is a UTXO

  2. 2Your transaction

    An input names that output by transaction ID and index 0, and its unlocking script meets the condition. New outputs follow

  3. 3Later transaction

    Spends one of your new outputs the same way. Each output can be spent once, and in full

An input spends the whole output it points to. Miners check that no input spends an output that was already spent, so the same satoshis cannot be spent twice.

What the signature covers

For a P2PKHPay to Public Key Hash, an output that only the key behind one address can spend output, the condition is a valid signature from the key behind an address. The unlocking script carries that signature and the public key. A signature hash flag at the end of the signature sets which parts of the transaction it covers:

  • SIGHASH_ALL covers every input and every output. It is the default of the P2PKH template in @bsv/sdk.
  • SIGHASH_NONE covers the inputs and no output.
  • SIGHASH_SINGLE covers the inputs and the output at the same index as the signed input.
  • SIGHASH_ANYONECANPAY, combined with one of the three, covers only the signed input, so others can add inputs.

@bsv/sdk always adds SIGHASH_FORKID to the flag, so your code only picks the scope.

A change to a covered part after signing makes the signature invalid. You choose a flag only when your code signs with @bsv/sdk, for example when several parties sign one transaction.

How the fee is computed

No part of a transaction states the fee. It is the satoshis of the inputs minus the satoshis of the outputs, and it goes to the miner who includes the transaction in a block. Whoever builds the transaction sets the fee by what the outputs leave out. To see this on a real transaction, read Understand how your transaction worked.

The fee follows from the size of the transaction in bytes and a rate in satoshis per kilobyte. The fee model of @bsv/sdk rounds up, so the miner gets the extra satoshi:

fee = ceil(size / 1000 × rate)

The size counts every byte of the serialized transaction:

  • 8 bytes for the version and the lock time together
  • 40 bytes per input for the source transaction ID, the output index and the sequence number, plus its unlocking script
  • 8 bytes per output for the amount, plus its locking script
  • A length prefix before each list and each script, 1 byte for fewer than 253 items or bytes

The fee is computed before signing, when the signatures do not exist yet, so the SDK takes the length of each unlocking script from the estimate of its template.

In @bsv/sdk, tx.fee() applies a fee model:

  • With no argument, it uses LivePolicy, which reads the rate from the policy of GorillaPool’s ARC, keeps it for 5 minutes, and uses 100 satoshis per kilobyte if the request fails and no rate is kept.
  • new SatoshisPerKilobyte(rate) sets a fixed rate, and a number sets the fee itself.
  • What is left after the outputs and the fee goes to the outputs marked change: true. If nothing is left, those outputs are removed, and if the inputs do not cover the outputs and the fee, fee() throws an error.

This page was written against @bsv/sdk 4.0.1.

Who sets the rate

Two sides set the rate. Each broadcast endpoint publishes the lowest rate it accepts, as miningFee in its policy, and refuses a transaction that pays less. The rate differs by network and by endpoint, and Broadcast transactions with BSV Broadcaster shows how to read it.

The side that builds the transaction picks the rate it pays, at or above that minimum. When your app asks a wallet for a transaction, the wallet picks it, so the app does not set a fee. When your code builds the transaction with @bsv/sdk, the fee model you pass to tx.fee() picks it.

From signed to confirmed

A transaction is final only once it is in a block. It gets there in four steps:

Signed

The wallet, or your code, fills each unlocking script. With SIGHASH_ALL, the inputs, the outputs and so the fee are now fixed.

Broadcast

BSV Broadcaster checks the transaction and delivers it to the network. A wallet broadcasts the transactions it creates, so an app that uses WalletClient does not call a broadcaster.

Seen by miners

Miners validate the transaction. BSV Broadcaster reports SEEN_ON_NETWORK once a miner has it, which is safe to treat as zero confirmation.

Mined

A miner includes the transaction in a block. The transaction now has a Merkle path, a BUMPBSV Unified Merkle Path (BRC-74): a compact proof that a transaction is in a block, that an app can check against block headers without asking a node.

A blockchain transaction cannot be reversed, so check the outputs and the amounts before the transaction is signed.

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