feat: parallel package for precompile pre-processing

[ARR4N]

Why this should be merged

EVM parallel co-processors that interface with the regular transaction path via precompiles.

How this works

Introduces the parallel.Processor, which orchestrates a set of parallel.Handlers. Each Handler performs arbitrary, strongly typed processing of any sub-set of transactions in a block and makes its results available to a precompile and/or a post-block method for persisting state. Although stateful, Handlers can only read the pre-block and post-block state, which isolates them from conflicts with the regular transaction path.

There is deliberately no support for a precompile to "write" to a Handler, only to "read". This is because the transaction might still revert, which would also have to be communicated to the Handler, resulting in unnecessary complexity. Logs/events are the recommended approach for precompile -> Handler communication, to be read from the types.Receipts at the end of the block.

How this was tested

Integration tests covering:

1. Selection of transactions to process + end-to-end plumbing of data through a Handler.
2. Registration as a precompile, exercised with actual transaction processing, and demonstrating log + return-data correctness.

[powerslider]

If set() is called twice without an intervening getAndKeep(), the second call blocks forever (channel buffer size is 1). This would deadlock the entire block processing.

I did notice that the finishBlock method drains all eventuals to reset them for the next block, so reuse is required, which means guarding with a sync.Once is not an option.

What I would suggest as an optional improvement without changing the method's signature is:

func (e eventual[T]) set(v T) {
    select {
    case e.ch <- v:
    default:
        panic("eventual: set called on non-empty eventual (double-set without intervening getAndKeep)")
    }
}

I deem this as appropriate because:

• Double-set is always a programming error in the orchestration logic, never expected behavior.
• Failing fast with a clear message is better than a silent deadlock.
• The existing goleak.VerifyTestMain would catch any test that triggers this.

But I don't defend this strongly if there is another design consideration that would either treat it as a tradeoff or something else.

[ARR4N]

Double-set is always a programming error in the orchestration logic, never expected behavior.

Exactly, which means this must be detected in development. Is the goal of your suggested signature to make it easier to diagnose deadlocks?

[powerslider]

My understanding on bounds here is the following:

• This is bounded by the largest block ever processed, not truly unbounded.
• Each unused eventual is maybe ~100 bytes (struct + channel overhead), so 10,000 unused elements would roughly equal 1MB.
• You did mention that the reuse is intentional per the comment: We can reuse the channels already in the data and results slices.

Optionally we can play around with some slice trimming logic if we want to avoid potential memory pressure. Something like if w.totalTxsInBlock < cap(w.results)/4 && cap(w.results) > 1000, then we can trim excess capacity from w.data and w.results.

Having said that, maybe it's not worth doing unless we can prove with a benchmark test that this will be a noticeable issue, but just throwing this as a suggestion.

[ARR4N]

This is bounded by the largest block ever processed, not truly unbounded.

Correct

Having said that, maybe it's not worth doing unless we can prove with a benchmark test that this will be a noticeable issue, but just throwing this as a suggestion.

I'm leaning towards this. 10k transactions in a block is biiiig¹ and even then it's only 1MB.

Footnotes

1. 210M gas for regular transfers using params.TxGas (21k). ↩

[powerslider]

Mhm, I think that potentially there is a risk here that could halt block processing:

• If BeforeBlock panics, the goroutine dies silently, w.common is never set, and subsequent calls to w.common.getAndReplace() in shouldProcess() will block forever.
• Since shouldProcess is called synchronously in StartBlock's transaction loop, this causes StartBlock to hang indefinitely.
• Handler.BeforeBlock is user-provided code, making panics possible. A single handler panic would silently halt all block processing.

A proposed solution here would be to add a panic-recover that intercepts the panic and sets w.common to unblock the waiters.

Let me know your thoughts here.

[ARR4N]

If BeforeBlock panics, the goroutine dies silently

It won't be silent:

type anxious struct {
	Handler[struct{}, struct{}, struct{}, struct{}]
}

func (anxious) BeforeBlock(libevm.StateReader, *types.Header) (_ struct{}) { panic(99) }

func TestBuildBlockPanic(t *testing.T) {
	p := New(8, 8)
	t.Cleanup(p.Close)
	AddHandler(p, &anxious{})

	_, _, sdb := ethtest.NewEmptyStateDB(t)
	rules := params.MergedTestChainConfig.Rules(big.NewInt(0), true, 0)

	b := types.NewBlock(
		&types.Header{Number: big.NewInt(1)},
		types.Transactions{},
		nil, nil, trie.NewStackTrie(nil),
	)

	require.NoError(t, p.StartBlock(sdb, rules, b))
	p.FinishBlock(sdb, b, nil)
}

panic: 99

goroutine 3 [running]:
github.com/ava-labs/libevm/libevm/precompiles/parallel.anxious.BeforeBlock(...)