<p>You explicitly asked about the source code, but let me start by giving a broader explanation of the term &quot;package&quot;.</p>
<p>When talking about a package, we generally refer to a set of connected transactions. For instance, a set of transactions <code>{A; B; C}</code> where <code>C</code> spends <code>A</code> and <code>B</code> is a package. A set of transactions <code>{A; B; C; D}</code> where <code>B</code> spends <code>A</code>, <code>C</code> spends <code>B</code> and <code>D</code> spends both <code>A</code> and <code>C</code> is also a package.</p>
<p>As you can see, this might get pretty convoluted. So why bother? In fact this &quot;connection&quot; between transactions is a dependency. From my first example above, <code>C</code> depends on <code>A</code> and <code>B</code> since it spends one of their outputs. This is a big deal because:</p>
<ol>
<li><code>C</code> is not valid without both <code>A</code> and <code>B</code>. While this is straightforward when the transactions are confirmed, it is less so when they are not: if a node hears about <code>C</code> but does not know about either <code>A</code> or <code>B</code> it will not accept it in its mempool and relay it.</li>
<li>An algorithm to create a block template ideally needs to take into account the feerate of the entire package. <code>A</code> and <code>B</code> may  pay a low feerate, but <code>C</code> pay a larger one. Since <code>C</code> depends on <code>A</code> and <code>B</code> it therefore incentivizes their inclusion in a block. This is known as CPFP (Child Pays For Parent).</li>
</ol>
<p>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, <code>CalculateMemPoolAncestors()</code> provides a <code>CTxMemPool::setEntries</code> containing the mempool entries corresponding to a transaction's ancestor set. Each entry keeps track of its dependency relationships with other mempool entries.</p>
<p>Packages have been discussed a lot recently along with the work on <a href="https://bitcoinops.org/en/topics/package-relay/" rel="nofollow noreferrer">Package Relay</a>, 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.</p>
<p>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.<br />
First, when accepting a batch of transactions that may or may not be related to each other. It is currently only exposed through the <code>testmempoolaccept</code> RPC command.<br />
Second, when accepting a package of a certain kind: a topologically sorted (parents appear before child) list of transactions that represent a <strong>single</strong> child with all its unconfirmed parents. It is in the current development branch only exposed through a brand new <code>submitpackage</code> RPC command. The intent is to eventually make it accessible from the P2P network, with the recently proposed <a href="https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2022-May/020493.html" rel="nofollow noreferrer">Package Relay BIP</a>.</p>
<p>This line defines <code>Package</code> as an alias for <code>std::vector&lt;CTransactionRef&gt;</code> 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 <em>haven't been validated yet</em>. To answer why we bothered defining an alias, the idea is if we later create a class, add member functions like <code>Package::GetFeerate</code>, 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.</p>
<p>You can read more about the current Bitcoin Core mempool acceptance rules for packages in the <a href="https://github.com/bitcoin/bitcoin/blob/53b1a2426c58f709b5cc0281ef67c0d29fc78a93/doc/policy/packages.md" rel="nofollow noreferrer"><code>doc/policy/packages.md</code></a> document.</p>

CC BY-SA 4.0
2022-07-01T17:50:20.897Z
Thanks for you explanation. So nodes relay transactions in packages, right? not relaying single transactions.
Amir reza Riahi
CC BY-SA 4.0
2022-07-01T18:31:46.477Z
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.
Pieter Wuille
CC BY-SA 4.0
2022-07-02T15:36:11.780Z
@PieterWuille understood, thanks.
Amir reza Riahi
CC BY-SA 4.0
2022-07-01T17:21:14.840Z
2022-07-15T13:01:53.943Z
2022-07-15T13:01:53.943Z
Antoine Poinsot
<p>In bitcoin source code there is an entity named <code>Package</code> and I've seen them many places over the source code. I found this comment in <code>src/policy/packages.h</code>:</p>
<pre><code>/** A package is an ordered list of transactions. The transactions cannot conflict with (spend the
 * same inputs as) one another. */
using Package = std::vector&lt;CTransactionRef&gt;;
</code></pre>
<p>Why they are useful?</p>

<transactions><bitcoin-core-development><package-relay>
What are packages in bitcoin core and what is their use case?
Amir reza Riahi
# What are packages in bitcoin core and what is their use case?

(Asked by: username_0 on 2022-07-01)

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?

**Tags:** transactions, bitcoin-core-development, package-relay


---

## 1 answers

### Answer by username_1 on 2022-07-01. Score: 6 | Accepted answer

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](https://bitcoinops.org/en/topics/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](https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2022-May/020493.html).

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`](https://github.com/bitcoin/bitcoin/blob/53b1a2426c58f709b5cc0281ef67c0d29fc78a93/doc/policy/packages.md) document.

> **Comments:**
> **username_0**: Thanks for you explanation. So nodes relay transactions in packages, right? not relaying single transactions.  
> **username_2**: 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.  
> **username_0**: @username_2 understood, thanks.  

---

