Welcome

Initialisation#

New() creates the pool, initialises every subpool, and starts the event loop:

1
func New(gasTip uint64, chain BlockChain, subpools []SubPool) (*TxPool, error) {
2
    head := chain.CurrentBlock()
3

4
    statedb, err := chain.StateAt(head.Root)
5
    if err != nil {
6
        statedb, err = chain.StateAt(types.EmptyRootHash)
7
    }
8
    if err != nil {
9
        return nil, err
10
    }
11
    pool := &TxPool{
12
        subpools: subpools,
13
        chain:    chain,
14
        state:    statedb,
15
        quit:     make(chan chan error),
16
        term:     make(chan struct{}),
17
        sync:     make(chan chan error),
18
    }
19
    reserver := NewReservationTracker()
20
    for i, subpool := range subpools {
21
        if err := subpool.Init(gasTip, head, reserver.NewHandle(i)); err != nil {
22
            for j := i - 1; j >= 0; j-- {
23
                subpools[j].Close()
24
            }
25
            return nil, err
26
        }
27
    }
28
    go pool.loop(head)
29
    return pool, nil
30
}

Key points:

• The current block head is captured once so all subpools start from the same state, even if the chain advances during initialisation.
• A ReservationTracker is created and each subpool gets its own Reserver handle. This ensures that a given sender address is tracked by exactly one subpool at a time — if LegacyPool holds an account, BlobPool cannot accept transactions from that same sender.
• If any subpool fails to initialise, previously initialised subpools are closed in reverse order.

The Event Loop#

The coordinator’s loop() goroutine listens for ChainHeadEvent notifications and triggers resets on all subpools when the chain head changes:

1
// core/txpool/txpool.go  (simplified)
2

3
func (p *TxPool) loop(head *types.Header) {
4
    defer close(p.term)
5

6
    newHeadCh  := make(chan core.ChainHeadEvent)
7
    newHeadSub := p.chain.SubscribeChainHeadEvent(newHeadCh)
8
    defer newHeadSub.Unsubscribe()
9

10
    var (
11
        oldHead = head
12
        newHead = oldHead
13
    )
14
    resetBusy := make(chan struct{}, 1)
15
    resetDone := make(chan *types.Header)
16
    // ...
17

18
    for errc == nil {
19
        if newHead != oldHead || resetForced {
20
            select {
21
            case resetBusy <- struct{}{}:
22
                // Update the coordinator's state snapshot
23
                if statedb, err := p.chain.StateAt(newHead.Root); err == nil {
24
                    p.stateLock.Lock()
25
                    p.state = statedb
26
                    p.stateLock.Unlock()
27
                }
28
                // Reset all subpools in a background goroutine
29
                go func(oldHead, newHead *types.Header) {
30
                    for _, subpool := range p.subpools {
31
                        subpool.Reset(oldHead, newHead)
32
                    }
33
                    resetDone <- newHead
34
                }(oldHead, newHead)
35
            default:
36
                // A reset is already running; will retry on next iteration
37
            }
38
        }
39
        select {
40
        case event := <-newHeadCh:
41
            newHead = event.Header
42
        case head := <-resetDone:
43
            oldHead = head
44
            <-resetBusy
45
        case errc = <-p.quit:
46
            // break out on next iteration
47
        }
48
    }
49
}

The pattern here is worth noting:

• At most one reset runs concurrently. The resetBusy channel (capacity 1) acts as a semaphore. If a reset is already in progress, new chain head events are simply recorded — newHead is updated — and the next reset will process them.
• The coordinator updates its own state snapshot before kicking off subpool resets, so Nonce() calls reflect the latest head immediately.

Routing Transactions to Subpools#

When Add() receives a batch of transactions, it splits them across subpools using each subpool’s Filter() method:

1
func (p *TxPool) Add(txs []*types.Transaction, sync bool) []error {
2
    txsets := make([][]*types.Transaction, len(p.subpools))
3
    splits := make([]int, len(txs))
4

5
    for i, tx := range txs {
6
        splits[i] = -1
7
        for j, subpool := range p.subpools {
8
            if subpool.Filter(tx) {
9
                txsets[j] = append(txsets[j], tx)
10
                splits[i] = j
11
                break
12
            }
13
        }
14
    }
15
    // Add split batches to each subpool
16
    errsets := make([][]error, len(p.subpools))
17
    for i := 0; i < len(p.subpools); i++ {
18
        errsets[i] = p.subpools[i].Add(txsets[i], sync)
19
    }
20
    // Reassemble errors in original order
21
    errs := make([]error, len(txs))
22
    for i, split := range splits {
23
        if split == -1 {
24
            errs[i] = fmt.Errorf("%w: received type %d", core.ErrTxTypeNotSupported, txs[i].Type())
25
            continue
26
        }
27
        errs[i] = errsets[split][0]
28
        errsets[split] = errsets[split][1:]
29
    }
30
    return errs
31
}

• Each transaction is routed to the first subpool whose Filter() returns true. LegacyPool.Filter() accepts types 0 (Legacy), 1 (AccessList), 2 (DynamicFee), and 4 (SetCode). BlobPool.Filter() accepts only type 3 (BlobTx).
• The splits array tracks which subpool each transaction went to, allowing the coordinator to stitch the per-subpool error slices back into the original batch order.
• If no subpool accepts a transaction, it gets ErrTxTypeNotSupported.

Merging Pending Transactions#

The miner calls Pending() to get all executable transactions. The coordinator merges results from every subpool:

1
func (p *TxPool) Pending(filter PendingFilter) map[common.Address][]*LazyTransaction {
2
    txs := make(map[common.Address][]*LazyTransaction)
3
    for _, subpool := range p.subpools {
4
        for addr, set := range subpool.Pending(filter) {
5
            txs[addr] = set
6
        }
7
    }
8
    return txs
9
}

Because the Reserver mechanism guarantees each address belongs to at most one subpool, the merge is a simple union — there are no conflicting entries for the same address.

The LazyTransaction wrapper (defined in core/txpool/subpool.go) carries just the metadata the miner needs for ordering — GasFeeCap, GasTipCap, Gas, BlobGas — without materialising the full transaction object. The full *types.Transaction is resolved on demand via Resolve().

Account Reservation#

The Reserver interface prevents two subpools from tracking the same sender address simultaneously:

1
type Reserver interface {
2
    Hold(addr common.Address) error
3
    Release(addr common.Address) error
4
    Has(address common.Address) bool
5
}

When a subpool receives a transaction from a new sender, it calls Hold(addr). If another subpool already holds that address, Hold returns an error and the transaction is rejected. When all transactions from an account are evicted, the subpool calls Release(addr).

This is essential for correctness: if the same sender had transactions in both LegacyPool and BlobPool, nonce tracking and balance accounting would be inconsistent.

Phase 1: Stateless Validation#

ValidateTransaction() checks everything that does not require reading the blockchain state:

1
func ValidateTransaction(tx *types.Transaction, head *types.Header,
2
    signer types.Signer, opts *ValidationOptions) error {
3
    // 1. Transaction type accepted by this pool?
4
    if opts.Accept&(1<<tx.Type()) == 0 {
5
        return fmt.Errorf("%w: tx type %v not supported", core.ErrTxTypeNotSupported, tx.Type())
6
    }
7
    // 2. Blob count within limit?
8
    if blobCount := len(tx.BlobHashes()); blobCount > opts.MaxBlobCount { ... }
9

10
    // 3. Transaction size within limit?
11
    if tx.Size() > opts.MaxSize { ... }
12

13
    // 4. Fork-specific type checks
14
    if !rules.IsBerlin  && tx.Type() != types.LegacyTxType { ... }
15
    if !rules.IsLondon  && tx.Type() == types.DynamicFeeTxType { ... }
16
    if !rules.IsCancun  && tx.Type() == types.BlobTxType { ... }
17
    if !rules.IsPrague  && tx.Type() == types.SetCodeTxType { ... }
18

19
    // 5. Init code size limit (Shanghai)
20
    if rules.IsShanghai && tx.To() == nil && len(tx.Data()) > params.MaxInitCodeSize { ... }
21

22
    // 6. Max transaction gas limit (Osaka)
23
    if rules.IsOsaka && tx.Gas() > params.MaxTxGas { ... }
24

25
    // 7. No negative value
26
    if tx.Value().Sign() < 0 { ... }
27

28
    // 8. Gas within block limit
29
    if head.GasLimit < tx.Gas() { ... }
30

31
    // 9. Fee caps are sane (not astronomically large)
32
    if tx.GasFeeCap().BitLen() > 256 { ... }
33
    if tx.GasTipCap().BitLen() > 256 { ... }
34

35
    // 10. Fee cap >= tip cap
36
    if tx.GasFeeCapIntCmp(tx.GasTipCap()) < 0 { ... }
37

38
    // 11. Signature valid, sender recoverable
39
    if _, err := types.Sender(signer, tx); err != nil { ... }
40

41
    // 12. Nonce not at max (EIP-2681)
42
    if tx.Nonce()+1 < tx.Nonce() { ... }
43

44
    // 13. Enough gas to cover intrinsic cost
45
    intrGas, _ := core.IntrinsicGas(tx.Data(), tx.AccessList(),
46
        tx.SetCodeAuthorizations(), tx.To() == nil, true,
47
        rules.IsIstanbul, rules.IsShanghai)
48
    if tx.Gas() < intrGas { ... }
49

50
    // 14. Floor data gas (Prague)
51
    // 15. Minimum tip for this pool
52
    // 16. Blob-specific checks (if blob tx)
53
    // ...
54
}

The ValidationOptions struct controls per-pool differences:

For blob transactions, additional checks run in validateBlobTx(): the sidecar must be present, there must be at least one blob, the blob count must not exceed BlobTxMaxBlobs, the blob fee cap must meet the protocol minimum, blob/commitment/proof counts must match, and KZG proofs must verify. The proof verification is dispatched based on the sidecar’s Version field: version 0 (legacy) uses per-blob KZG proofs, while version 1 (Osaka) uses cell proofs (EIP-7594).

Phase 2: Stateful Validation#

ValidateTransactionWithState() checks properties that require the current state:

1
func ValidateTransactionWithState(tx *types.Transaction, signer types.Signer,
2
    opts *ValidationOptionsWithState) error {
3
    from, _ := types.Sender(signer, tx)
4

5
    // 1. Nonce must not be stale
6
    next := opts.State.GetNonce(from)
7
    if next > tx.Nonce() {
8
        return fmt.Errorf("%w: next nonce %v, tx nonce %v", core.ErrNonceTooLow, next, tx.Nonce())
9
    }
10
    // 2. No nonce gap (if pool enforces ordering)
11
    if opts.FirstNonceGap != nil {
12
        if gap := opts.FirstNonceGap(from); gap < tx.Nonce() {
13
            return fmt.Errorf("%w: tx nonce %v, gapped nonce %v", core.ErrNonceTooHigh, ...)
14
        }
15
    }
16
    // 3. Balance covers this transaction's cost
17
    balance := opts.State.GetBalance(from).ToBig()
18
    cost    := tx.Cost()
19
    if balance.Cmp(cost) < 0 { ... }
20

21
    // 4. Balance covers all queued transactions + this one (overdraft check)
22
    spent := opts.ExistingExpenditure(from)
23
    if prev := opts.ExistingCost(from, tx.Nonce()); prev != nil {
24
        // Replacement: check balance covers (total_spent + bump)
25
        bump := new(big.Int).Sub(cost, prev)
26
        need := new(big.Int).Add(spent, bump)
27
        if balance.Cmp(need) < 0 { ... }
28
    } else {
29
        // New nonce: check balance covers (total_spent + this_cost)
30
        need := new(big.Int).Add(spent, cost)
31
        if balance.Cmp(need) < 0 { ... }
32

33
        // Also check account slot limits
34
        if opts.UsedAndLeftSlots != nil {
35
            if used, left := opts.UsedAndLeftSlots(from); left <= 0 { ... }
36
        }
37
    }
38
    return nil
39
}

The ValidationOptionsWithState callbacks let each subpool plug in its own accounting. For example, LegacyPool provides ExistingExpenditure that sums the totalcost of the pending list, and ExistingCost that looks up a specific nonce’s transaction cost. Notably, LegacyPool sets FirstNonceGap to nil — it deliberately allows nonce gaps in the queue, only enforcing continuity in the pending set.

Configuration#

The pool’s behaviour is governed by Config with these defaults:

1
var DefaultConfig = Config{
2
    PriceLimit: 1,          // 1 Wei minimum gas tip
3
    PriceBump:  10,         // 10% price bump required for replacement
4
    AccountSlots: 16,       // Max pending txs per account
5
    GlobalSlots:  5120,     // Max pending txs across all accounts
6
    AccountQueue: 64,       // Max queued txs per account
7
    GlobalQueue:  1024,     // Max queued txs across all accounts
8
    Lifetime: 3 * time.Hour, // Max time a queued tx can survive
9
}

Two size constants control individual transactions:

• txSlotSize = 32 KB — the unit of measurement for pool capacity. A transaction’s “slot count” is ceil(size / 32KB).
• txMaxSize = 4 * txSlotSize = 128 KB — the absolute maximum transaction size.

The Pending and Queue Maps#

The pool maintains two core data structures:

1
// core/txpool/legacypool/legacypool.go  (key fields)
2

3
type LegacyPool struct {
4
    pending      map[common.Address]*list  // Executable transactions (next nonce matches state)
5
    queue        *queue                    // Future transactions (nonce gaps exist)
6
    all          *lookup                   // Hash → transaction lookup for deduplication
7
    priced       *pricedList               // Price-sorted heap for eviction decisions
8
    pendingNonces *noncer                  // Virtual nonces tracking pending txs
9
    // ...
10
}

Pending (map[common.Address]*list) holds transactions that are immediately executable — their nonces form a contiguous sequence starting from the account’s current on-chain nonce. Each list is a nonce-sorted structure backed by a SortedMap (a map[uint64]*Transaction with a heap-based nonce index). Pending lists use strict mode (strict: true): removing a transaction at nonce N also invalidates all transactions at nonces > N, since they are no longer contiguous.

Queue (*queue, wrapping map[common.Address]*list) holds future transactions — those with nonce gaps. Queue lists use non-strict mode (strict: false): removing a transaction does not cascade. The queue also tracks a beats map of last-activity timestamps per account, used for eviction of stale entries.

all (*lookup) is a flat map[common.Hash]*Transaction for O(1) deduplication. It also tracks the total slot count used across both pending and queue.

priced (*pricedList) maintains two price-sorted heaps — an urgent heap (sorted by effective tip at current base fee) and a floating heap (sorted by fee cap). When the pool overflows, transactions are evicted from the cheaper heap. The two-heap design handles both congested periods (where effective tip matters most) and base fee peaks (where fee cap is the binding constraint).

The list and SortedMap Internals#

Each per-account list wraps a SortedMap:

1
type SortedMap struct {
2
    items   map[uint64]*types.Transaction // nonce → transaction
3
    index   *nonceHeap                    // min-heap of nonces
4
    cache   types.Transactions            // cached nonce-sorted slice
5
    cacheMu sync.Mutex
6
}
7

8
type list struct {
9
    strict    bool         // true for pending (contiguous nonces), false for queue
10
    txs       *SortedMap
11
    costcap   *uint256.Int // highest single-tx cost seen
12
    gascap    uint64       // highest single-tx gas limit seen
13
    totalcost *uint256.Int // sum of Cost() for all txs in the list
14
}

The SortedMap provides the key operations:

• Put(tx) — insert or replace a transaction by nonce. Invalidates the sorted cache.
• Forward(threshold) — remove all transactions with nonce < threshold. Used during demoteUnexecutables() to strip confirmed transactions.
• Ready(start) — extract a contiguous run of transactions starting at nonce start. Used during promoteExecutables() to pull queue entries into pending.
• Filter(fn) — remove all transactions matching a predicate. Used to drop transactions that exceed the account’s balance.
• Cap(threshold) — keep only threshold transactions, dropping the highest-nonce ones. Used during truncatePending().

Transaction Replacement#

When a transaction arrives with a nonce that already exists in the pool, it is a replacement attempt. list.Add() enforces a minimum price bump:

1
func (l *list) Add(tx *types.Transaction, priceBump uint64) (bool, *types.Transaction) {
2
    old := l.txs.Get(tx.Nonce())
3
    if old != nil {
4
        if old.GasFeeCapCmp(tx) >= 0 || old.GasTipCapCmp(tx) >= 0 {
5
            return false, nil
6
        }
7
        // Both fee cap and tip must exceed old * (100 + priceBump) / 100
8
        a := big.NewInt(100 + int64(priceBump))
9
        aFeeCap := new(big.Int).Mul(a, old.GasFeeCap())
10
        aTip := a.Mul(a, old.GasTipCap())
11

12
        b := big.NewInt(100)
13
        thresholdFeeCap := aFeeCap.Div(aFeeCap, b)
14
        thresholdTip := aTip.Div(aTip, b)
15

16
        if tx.GasFeeCapIntCmp(thresholdFeeCap) < 0 ||
17
           tx.GasTipCapIntCmp(thresholdTip) < 0 {
18
            return false, nil
19
        }
20
    }
21
    // Accept: update totalcost, insert into SortedMap
22
    // ...
23
}

With the default PriceBump of 10, both the fee cap and tip cap must be at least 10% higher than the existing transaction. This prevents spam replacements while allowing legitimate fee bumps.

The add() Pipeline#

When a new transaction passes validation, add() handles insertion:

1
// core/txpool/legacypool/legacypool.go  (simplified)
2

3
func (pool *LegacyPool) add(tx *types.Transaction) (replaced bool, err error) {
4
    hash := tx.Hash()
5

6
    // 1. Reject if already known
7
    if pool.all.Get(hash) != nil {
8
        return false, txpool.ErrAlreadyKnown
9
    }
10
    // 2. Stateful validation (nonce, balance, overdraft)
11
    if err := pool.validateTx(tx); err != nil {
12
        return false, err
13
    }
14
    from, _ := types.Sender(pool.signer, tx)
15

16
    // 3. Reserve the account if new to this subpool
17
    if !hasPending && !hasQueued {
18
        if err := pool.reserver.Hold(from); err != nil {
19
            return false, err
20
        }
21
    }
22
    // 4. If pool is full, evict underpriced transactions
23
    if pool.all.Slots()+numSlots(tx) > GlobalSlots+GlobalQueue {
24
        if pool.priced.Underpriced(tx) {
25
            return false, txpool.ErrUnderpriced
26
        }
27
        drop, success := pool.priced.Discard(overflow)
28
        if !success {
29
            return false, ErrTxPoolOverflow
30
        }
31
        for _, tx := range drop {
32
            pool.removeTx(tx.Hash(), false, ...)
33
        }
34
    }
35
    // 5. If replacing an existing pending tx, do it directly
36
    if list := pool.pending[from]; list != nil && list.Contains(tx.Nonce()) {
37
        inserted, old := list.Add(tx, pool.config.PriceBump)
38
        if !inserted {
39
            return false, txpool.ErrReplaceUnderpriced
40
        }
41
        // ...
42
        return old != nil, nil
43
    }
44
    // 6. Otherwise, enqueue for later promotion
45
    pool.enqueueTx(hash, tx, true)
46
    return false, nil
47
}

Step 4 is the eviction mechanism. When the combined size of pending + queue exceeds GlobalSlots + GlobalQueue (6144 transactions by default), the pool must make room. It checks whether the new transaction is cheaper than the cheapest existing one (Underpriced). If not, it calls Discard() on the pricedList to evict the cheapest remote transactions.

Step 5 is a fast path: if the sender already has a pending transaction at this nonce, we attempt a direct replacement without going through the queue. This is the common “speed up” or “cancel” flow where a user resubmits with a higher gas price.

Step 6 is the normal path: the transaction goes into the queue and will be promoted during the next reorg cycle.

The Reorg Cycle: promote and demote#

The LegacyPool runs a background scheduleReorgLoop() goroutine that batches and processes two types of requests:

1. Reset requests — triggered by ChainHeadEvent via the coordinator. These re-sync the pool’s state to a new chain head.
2. Promote requests — triggered after Add() to check if newly added transactions are immediately executable.

Both are processed in runReorg(), which runs with the pool lock held:

1
// core/txpool/legacypool/legacypool.go  (simplified)
2

3
func (pool *LegacyPool) runReorg(done chan struct{}, reset *txpoolResetRequest,
4
    dirtyAccounts *accountSet, events map[common.Address]*SortedMap) {
5
    // ...
6
    pool.mu.Lock()
7

8
    if reset != nil {
9
        pool.reset(reset.oldHead, reset.newHead)
10
        promoteAddrs = pool.queue.addresses() // promote all accounts after reset
11
    }
12
    // Move newly-executable txs from queue → pending
13
    promoted := pool.promoteExecutables(promoteAddrs)
14

15
    if reset != nil {
16
        // Remove txs that are no longer valid at the new head
17
        pool.demoteUnexecutables()
18

19
        // Update base fee for price sorting
20
        pendingBaseFee := eip1559.CalcBaseFee(pool.chainconfig, reset.newHead)
21
        pool.priced.SetBaseFee(pendingBaseFee)
22
    }
23
    // Enforce capacity limits
24
    pool.truncatePending()
25
    pool.truncateQueue()
26

27
    pool.mu.Unlock()
28

29
    // Broadcast new transaction events
30
    pool.txFeed.Send(core.NewTxsEvent{Txs: txs})
31
}

1
// core/txpool/legacypool/legacypool.go  (simplified)
2

3
func (pool *LegacyPool) reset(oldHead, newHead *types.Header) {
4
    // If a reorg occurred (oldHead is not parent of newHead):
5
    //   Walk back both chains to the common ancestor
6
    //   Collect transactions from discarded blocks
7
    //   Subtract transactions from newly-included blocks
8
    //   Reinject the difference back into the pool
9

10
    // Update state to new head
11
    statedb, _ := pool.chain.StateAt(newHead.Root)
12
    pool.currentHead.Store(newHead)
13
    pool.currentState = statedb
14
    pool.pendingNonces = newNoncer(statedb)
15
}

1
// core/txpool/legacypool/legacypool.go  (simplified)
2

3
func (pool *LegacyPool) demoteUnexecutables() {
4
    gasLimit := pool.currentHead.Load().GasLimit
5
    for addr, list := range pool.pending {
6
        nonce := pool.currentState.GetNonce(addr)
7

8
        // Drop confirmed transactions (nonce < state nonce)
9
        olds := list.Forward(nonce)
10

11
        // Drop transactions that exceed balance or gas limit
12
        drops, invalids := list.Filter(pool.currentState.GetBalance(addr), gasLimit)
13

14
        // Move invalidated txs back to queue
15
        for _, tx := range invalids {
16
            pool.enqueueTx(tx.Hash(), tx, false)
17
        }
18
        // If a nonce gap appeared, demote everything
19
        if list.Len() > 0 && list.txs.Get(nonce) == nil {
20
            gapped := list.Cap(0)
21
            for _, tx := range gapped {
22
                pool.enqueueTx(tx.Hash(), tx, false)
23
            }
24
        }
25
        if list.Empty() {
26
            delete(pool.pending, addr)
27
            if _, ok := pool.queue.get(addr); !ok {
28
                pool.reserver.Release(addr)
29
            }
30
        }
31
    }
32
}

Capacity Management#

After every reorg, two truncation functions enforce global limits:

truncatePending() enforces GlobalSlots (5120). It identifies “spammer” accounts — those with more than AccountSlots (16) pending transactions — and iteratively removes the highest-nonce transaction from the account with the most pending transactions, equalising counts across all spammers. This fair-share approach prevents a single account from monopolising the pending set.

truncateQueue() enforces GlobalQueue (1024). The queue’s internal eviction is based on the beats timestamp: accounts are sorted by last-activity time and the oldest (least recently active) accounts’ transactions are dropped first until the global limit is satisfied. Per-account queue limits (AccountQueue = 64) are enforced separately, during promoteExecutables().

Additionally, the loop() goroutine runs a periodic eviction ticker (every minute) that removes queued transactions that have been sitting for longer than Lifetime (3 hours).

EIP-7702 SetCode Transaction Restrictions#

The LegacyPool enforces special rules for accounts involved in EIP-7702 delegation (see Chapter 02):

• Delegated accounts (those whose code hash indicates a delegation designator, or those with a pending authorization) are limited to at most one in-flight executable transaction. This prevents stacking multiple transactions on a delegated account, since the delegation could be revoked at any time.
• Authority accounts named in a SetCode transaction’s authorization list are checked against the Reserver — if the authority is already tracked by another subpool, the transaction is rejected.

Why a Separate Pool?#

The BlobPool exists because blob transactions have properties that conflict with LegacyPool’s assumptions:

1. Size — a single blob transaction with 6 blobs can be ~768 KB. Keeping thousands of these in memory is impractical. The BlobPool stores transaction data on disk using a persistent key-value store (billy.Database), keeping only lightweight blobTxMeta structs in memory.

2. Low churn — block blob-space is limited (a few blob transactions per block). The BlobPool exploits this by persisting transactions to disk immediately, solving the “lost transactions on restart” problem that plagues LegacyPool.

3. No nonce gaps — blob transactions are meant for rollups that submit sequentially. The BlobPool disallows nonce gaps entirely, unlike LegacyPool’s queue.

4. Aggressive replacement pricing — since propagating replacement blobs is expensive, the BlobPool requires much higher fee bumps than LegacyPool’s 10%.

5. Per-account limits — at most maxTxsPerAccount (16) blob transactions per sender, versus LegacyPool’s 64 in queue + 16 in pending.

BlobPool Structure#

1
// core/txpool/blobpool/blobpool.go  (key fields)
2

3
type BlobPool struct {
4
    store  billy.Database               // On-disk persistent storage
5
    stored uint64                       // Total bytes on disk
6
    limbo  *limbo                       // Included-but-not-finalised blob storage
7

8
    lookup *lookup                          // hash → storage mapping
9
    index  map[common.Address][]*blobTxMeta // Per-account tx metadata, sorted by nonce
10
    spent  map[common.Address]*uint256.Int  // Cumulative cost per account
11
    evict  *evictHeap                       // Priority queue for eviction
12
    // ...
13
}

• store — the billy.Database is a size-class-based persistent store. Transactions are written to disk on Add() and deleted when they are finalised. The Datacap config (currently ~2.5 GB, with a TODO to raise to 10 GB) limits total on-disk usage.
• limbo — a secondary persistent store for blob transactions that have been included in a block but not yet finalised. This is necessary because blob data is not part of the execution chain — a reorg could require re-pooling “lost” blobs. Once a block is finalised, its blobs are purged from limbo.
• index — per-account metadata slices, sorted by nonce. Each blobTxMeta is a few hundred bytes (hash, versioned hashes, nonce, fee caps, gas, eviction priorities), versus hundreds of KB for the full transaction with blobs. This keeps the in-memory footprint manageable.
• evict — a priority heap that determines which account’s transactions to drop when the pool reaches capacity.

The blobTxMeta and Eviction Priority#

Each blob transaction in memory is represented by a compact metadata struct:

1
type blobTxMeta struct {
2
    hash    common.Hash
3
    vhashes []common.Hash // Blob versioned hashes
4
    version byte          // Sidecar version (0 = legacy, 1 = Osaka cell proofs)
5

6
    id      uint64       // Storage ID in billy.Database
7
    size    uint64       // RLP-encoded size including blobs
8
    nonce   uint64
9
    costCap *uint256.Int // tx.Cost()
10
    execTipCap  *uint256.Int
11
    execFeeCap  *uint256.Int
12
    blobFeeCap  *uint256.Int
13
    execGas     uint64
14
    blobGas     uint64
15

16
    basefeeJumps float64 // log1.125(execFeeCap) - log1.125(currentBaseFee)
17
    blobfeeJumps float64 // log1.125(blobFeeCap) - log1.125(currentBlobFee)
18

19
    evictionExecTip      *uint256.Int // worst tip across all prior nonces
20
    evictionExecFeeJumps float64      // worst base fee jumps across all prior nonces
21
    evictionBlobFeeJumps float64      // worst blob fee jumps across all prior nonces
22
    // ...
23
}

The eviction algorithm is notably sophisticated. Blob transactions have three independent price dimensions (execution tip, execution fee cap, blob fee cap), making a simple total ordering impossible. The BlobPool reduces this dimensionality through several steps:

1. Fee jumps — convert absolute fees to “jumps”, the number of 1.125x fee adjustments between the current network fee and the transaction’s cap. This normalises across different fee magnitudes.
2. Priority per dimension — for each fee dimension (base fee, blob fee), compute the difference between the transaction’s jumps and the current network fee’s jumps, then compress with sign(diff) * log2(abs(diff)). This reduces noise at high values.
3. Combine dimensions — take min(basePriority, blobPriority). The binding constraint (whichever fee is closest to exceeding the cap) determines the priority. Positive values (fees well below caps) are clamped to 0 to prevent pool wars.
4. Tip as tiebreaker — within the same priority bucket, the execution tip breaks ties.
5. Worst-across-nonces — track the worst priority values across all of an account’s nonce sequence. A cheap transaction at nonce 5 degrades the priority of the expensive transaction at nonce 10, since nonce 5 must execute first.

When the pool exceeds Datacap, the account with the worst eviction priority has its highest-nonce transaction dropped. The highest nonce is chosen because it is the furthest from execution, and dropping the lowest nonce would create a gap (which is forbidden).

Filter#

The BlobPool’s Filter() is simple — it accepts only type 3 (blob) transactions:

1
func (p *BlobPool) Filter(tx *types.Transaction) bool {
2
    return tx.Type() == types.BlobTxType
3
}