Package Relay

What Is Package Relay?

Package relay is a set of changes to Bitcoin's peer-to-peer transaction relay protocol that allows nodes to send, receive, and evaluate groups of related transactions together rather than one at a time. A "package" in this context is a set of transactions with dependency relationships: typically a parent transaction and one or more children that spend the parent's outputs.

Without package relay, Bitcoin nodes evaluate each transaction individually against mempool feerate thresholds. This creates a circular dependency problem: a low-fee parent is rejected before its fee-bumping child can be evaluated, and the child is rejected because its parent is unknown. Neither transaction enters the mempool despite the pair being economically rational for miners to include in a block.

Package relay resolves this by allowing nodes to consider the aggregate feerate of a transaction package. If a parent pays 0 sat/vB but its child pays 50 sat/vB, the package feerate may well exceed the mempool minimum, and both transactions are accepted. This aligns mempool policy with mining incentives: the mempool should accept any set of transactions that a rational miner would include in a block template.

How It Works

Package relay operates through changes at two layers: mempool validation (how packages are evaluated locally) and P2P relay (how packages propagate between nodes).

Mempool Package Validation

When a node receives a transaction package, it validates the entire set together rather than individually. The key steps are:

1. The node receives a child transaction whose parent is not in the mempool (an orphan transaction)
2. Instead of discarding the orphan, the node requests the missing parent from the sending peer
3. Once both transactions arrive, the node evaluates them as a package, computing a combined feerate across the parent and child
4. If the package feerate exceeds the mempool minimum, both transactions are accepted into the mempool

This validation also supports package replace-by-fee (package RBF): a new parent-child package can replace an existing conflicting transaction if the new package pays higher total fees and a higher feerate.

One-Parent-One-Child (1P1C) Relay

The first P2P relay mechanism shipped in Bitcoin Core 28.0 is called 1P1C relay. It supports the most common and most important topology: a single parent transaction paired with a single child that spends one of the parent's outputs.

1P1C relay works opportunistically through Bitcoin's existing transaction relay protocol. When a node receives a child transaction whose parent is missing, it tracks the orphan and requests the parent. Once the parent arrives, the node submits both as a package to its mempool. No new P2P messages are required for this mechanism: it piggybacks on existing orphan resolution logic.

As of Bitcoin Core 30.0 (released in 2025), 1P1C relay handles broader topologies: packages are accepted even when the child already has other unconfirmed parents in the mempool. This enables propagation of multi-parent-one-child and grandparent-parent-child structures.

The submitpackage RPC

Bitcoin Core provides a submitpackage RPC for directly submitting transaction packages to a node's mempool:

# Submit a parent-child package to the local mempool
bitcoin-cli submitpackage '["<parent_tx_hex>", "<child_tx_hex>"]'

# With fee safety limits
bitcoin-cli submitpackage '["<parent_hex>", "<child_hex>"]' 100 0

The RPC accepts an ordered list of serialized transactions and optional maxfeerate and maxburnamount arguments. It returns per-transaction results including txids, fees, and virtual size. This is useful for wallet software and Layer 2 implementations that need to submit presigned transaction packages directly.

BIP 331: Ancestor Package Relay Protocol

While 1P1C relay works opportunistically, BIP 331 (authored by Gloria Zhao) defines a formal P2P protocol for requesting and relaying ancestor packages. It introduces new message types:

• sendpackages: negotiated during the version handshake to signal package relay support
• ancpkginfo: communicates the complete ancestor package of a transaction as a list of witness transaction IDs
• getpkgtxns and pkgtxns: batch request and response for downloading multiple transactions in a single round trip

BIP 331 remains in draft status. The current phased approach prioritizes shipping practical improvements (1P1C relay, TRUC transactions) while the full protocol design matures.

Why Package Relay Matters for Layer 2

Package relay is not just a mempool optimization: it is a security requirement for the Lightning Network and other Layer 2 protocols. The core issue is that these protocols rely on presigned transactions that must confirm within specific timeframes to maintain safety guarantees.

The Presigned Transaction Problem

When two parties open a Lightning channel, they exchange signed commitment transactions that can be broadcast to close the channel unilaterally. These transactions are signed in advance, meaning the fee is locked at signing time. If network fees rise significantly between when a commitment transaction is signed and when it needs to be broadcast, the transaction may fall below the mempool minimum feerate and fail to propagate.

This is not merely an inconvenience. If a commitment transaction cannot confirm before critical timelocks expire, a malicious counterparty can steal funds by broadcasting an outdated channel state. The justice transaction mechanism that punishes cheating also depends on timely confirmation.

Anchor Outputs and CPFP

The Lightning Network adopted anchor outputs as a partial solution: small outputs (typically 330 sats) attached to commitment transactions that either party can spend in a child transaction with a high fee. This child transaction pays for the parent commitment transaction through CPFP.

However, without package relay, this CPFP strategy has a fatal flaw: if the commitment transaction's feerate falls below the mempool minimum, nodes reject it before ever seeing the fee-bumping child. Package relay closes this gap by ensuring the parent and child are evaluated together.

TRUC Transactions and Zero-Fee Commitments

Topologically Restricted Until Confirmation (TRUC) transactions, defined in BIP 431, work hand-in-hand with package relay. TRUC transactions (nVersion=3) enforce a strict one-parent-one-child topology while unconfirmed and allow the parent to pay zero fees when accompanied by a fee-paying child.

This combination enables Lightning implementations to set commitment transaction fees to zero at signing time, eliminating the need for the update_fee message that currently causes unnecessary force closes during fee spikes. Each party can independently choose the right fee at broadcast time by constructing an appropriate child transaction.

Pinning Attack Prevention

Without package relay, a malicious channel counterparty can execute pinning attacks: crafting transactions that exploit per-transaction mempool evaluation to block an honest party's transactions from confirming. Common attack vectors include:

• Exhausting descendant transaction limits so the honest party cannot attach a CPFP child
• Broadcasting a conflicting low-fee transaction that occupies mempool space without confirming
• Exploiting channel jamming dynamics to delay HTLC resolution past timeout deadlines

Package relay combined with TRUC transactions and sibling eviction allows honest participants to replace attacker-pinned transactions by submitting a valid parent-child package with adequate fees.

Use Cases

Lightning Channel Management

The primary use case for package relay is enabling reliable fee-bumping of Lightning commitment transactions. Channel operators can set commitment fees conservatively at signing time, knowing they can always bump fees at broadcast time through CPFP with package relay. This makes Lightning channels more resilient during fee market volatility.

Wallet Fee Bumping

Standard Bitcoin wallets benefit from package relay when sending transactions during periods of rapidly rising fees. A wallet can broadcast a transaction at a moderate feerate and later attach a high-fee child transaction to accelerate confirmation, even if the original transaction has dropped below the mempool minimum in the interim.

Batch Transaction Processing

Exchanges and payment processors that batch withdrawals into single transactions can use package relay for more flexible fee estimation. Instead of overpaying fees upfront to ensure confirmation, they can broadcast at a lower feerate and bump with a child transaction if the batch does not confirm quickly enough.

Presigned Contract Protocols

Any protocol that uses presigned transactions benefits from package relay: discreet log contracts, atomic swaps, channel factories, and vault constructions all rely on transactions whose fees cannot be adjusted after signing. Package relay ensures these transactions can always reach miners through CPFP, regardless of future fee conditions.

Implementation Timeline

Package relay has been implemented in Bitcoin Core through a phased rollout spanning multiple releases:

Future work includes full ancestor package relay (BIP 331 P2P protocol) and sender-initiated package relay for arbitrary package topologies.

Risks and Considerations

DoS Attack Surface

Accepting transaction packages increases the potential for denial-of-service attacks against nodes. An attacker could flood nodes with invalid packages that consume validation resources before being rejected. Bitcoin Core mitigates this through strict topology limits (1P1C only for P2P relay), orphanage size caps, and weight-based eviction of orphan transactions.

Incremental Rollout

Package relay requires widespread network adoption to be reliable. If only a fraction of nodes support package relay, transaction packages may fail to propagate to miners. The opportunistic 1P1C approach mitigates this by working within the existing relay protocol, but full BIP 331 relay will require a critical mass of upgraded nodes.

Topology Restrictions

Current P2P package relay only supports one-parent-one-child packages. More complex topologies (multiple parents, deeper chains) can be submitted via the submitpackage RPC but do not yet propagate across the network. Protocols requiring multi-parent packages must wait for future Bitcoin Core releases or rely on direct miner submission.

Interaction with Mempool Policies

Package relay interacts with multiple mempool policy mechanisms: RBF, descendant limits, and the upcoming cluster mempool redesign (expected in Bitcoin Core 31.0). These interactions create complex edge cases around package eviction, replacement, and prioritization that wallet developers and Layer 2 protocol designers must carefully account for. The Bitcoin Optech project provides ongoing coverage of these evolving policies.

This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.