5

In bitcoin source code there is an entity named Package and I've seen them many places over the source code. I found this comment in src/policy/packages.h:

/** A package is an ordered list of transactions. The transactions cannot conflict with (spend the
 * same inputs as) one another. */
using Package = std::vector<CTransactionRef>;

Why they are useful?

1 Answer 1

6

You explicitly asked about the source code, but let me start by giving a broader explanation of the term "package".

When talking about a package, we generally refer to a set of connected transactions. For instance, a set of transactions {A; B; C} where C spends A and B is a package. A set of transactions {A; B; C; D} where B spends A, C spends B and D spends both A and C is also a package.

As you can see, this might get pretty convoluted. So why bother? In fact this "connection" between transactions is a dependency. From my first example above, C depends on A and B since it spends one of their outputs. This is a big deal because:

  1. C is not valid without both A and B. While this is straightforward when the transactions are confirmed, it is less so when they are not: if a node hears about C but does not know about either A or B it will not accept it in its mempool and relay it.
  2. An algorithm to create a block template ideally needs to take into account the feerate of the entire package. A and B may pay a low feerate, but C pay a larger one. Since C depends on A and B it therefore incentivizes their inclusion in a block. This is known as CPFP (Child Pays For Parent).

Therefore, packages are useful to reason about the feerate of a transaction with all its unconfirmed dependencies. Packages have existed for many years in Bitcoin Core and don't always take the form of this data type. For example, CalculateMemPoolAncestors() provides a CTxMemPool::setEntries containing the mempool entries corresponding to a transaction's ancestor set. Each entry keeps track of its dependency relationships with other mempool entries.

Packages have been discussed a lot recently along with the work on Package Relay, a protocol extension permitting to not only relay unconfirmed transactions individually but as packages. While the work on package relay is not new, it has been significantly undertaken lately due to giving better security guarantees to some Layer 2 protocols such as the Lightning Network.

The line you quote has to do with the implementation of packages in Bitcoin Core's mempool validation code. This (critical) part of the code has to do with the acceptance of new transactions in a node's mempool. The type declaration refers to a list of pointers to transactions, and is used in two cases.
First, when accepting a batch of transactions that may or may not be related to each other. It is currently only exposed through the testmempoolaccept RPC command.
Second, when accepting a package of a certain kind: a topologically sorted (parents appear before child) list of transactions that represent a single child with all its unconfirmed parents. It is in the current development branch only exposed through a brand new submitpackage RPC command. The intent is to eventually make it accessible from the P2P network, with the recently proposed Package Relay BIP.

This line defines Package as an alias for std::vector<CTransactionRef> without any other inherent requirements. This may seem surprising (since packages are supposed to contain related transactions) but was introduced to hold a list of candidate transactions for submission to the mempool that haven't been validated yet. To answer why we bothered defining an alias, the idea is if we later create a class, add member functions like Package::GetFeerate, add a constructor that enforces dependency requirements, cache data about transaction fees, etc., we don't need to change all of the places packages are used.

You can read more about the current Bitcoin Core mempool acceptance rules for packages in the doc/policy/packages.md document.

3
  • Thanks for you explanation. So nodes relay transactions in packages, right? not relaying single transactions. Commented Jul 1, 2022 at 17:50
  • 3
    No, they are relayed individually. The relay of packages is proposed, but not adopted, as explained in the answer above mentioning the recently proposed package relay BIP. Commented Jul 1, 2022 at 18:31
  • @PieterWuille understood, thanks. Commented Jul 2, 2022 at 15:36

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.