feat: integration of parallel.Processor with EVM.Call

Author: ARR4N

core/vm/evm.go

@@ -187,7 +187,7 @@ func (evm *EVM) Interpreter() *EVMInterpreter {
 // parameters. It also handles any necessary value transfer required and takes
 // the necessary steps to create accounts and reverses the state in case of an
 // execution error or failed value transfer.
-func (evm *EVM) Call(caller ContractRef, addr common.Address, input []byte, gas uint64, value *uint256.Int) (ret []byte, leftOverGas uint64, err error) {
+func (evm *EVM) call(caller ContractRef, addr common.Address, input []byte, gas uint64, value *uint256.Int) (ret []byte, leftOverGas uint64, err error) {
 	// Fail if we're trying to execute above the call depth limit
 	if evm.depth > int(params.CallCreateDepth) {
 		return nil, gas, ErrDepth

core/vm/evm.libevm.go

@@ -20,6 +20,7 @@ import (
 	"github.com/ava-labs/libevm/common"
 	"github.com/ava-labs/libevm/libevm"
 	"github.com/ava-labs/libevm/log"
+	"github.com/holiman/uint256"
 )
 
 // canCreateContract is a convenience wrapper for calling the
@@ -52,6 +53,29 @@ func (evm *EVM) canCreateContract(caller ContractRef, contractToCreate common.Ad
 	return gas, err
 }
 
+// Call executes the contract associated with the addr with the given input as
+// parameters. It also handles any necessary value transfer required and takes
+// the necessary steps to create accounts and reverses the state in case of an
+// execution error or failed value transfer.
+func (evm *EVM) Call(caller ContractRef, addr common.Address, input []byte, gas uint64, value *uint256.Int) (ret []byte, leftOverGas uint64, err error) {
+	gas, err = evm.spendPreprocessingGas(gas)
+	if err != nil {
+		return nil, gas, err
+	}
+	return evm.call(caller, addr, input, gas, value)
+}
+
+func (evm *EVM) spendPreprocessingGas(gas uint64) (uint64, error) {
+	if evm.depth > 0 || !libevmHooks.Registered() {
+		return gas, nil
+	}
+	c := libevmHooks.Get().PreprocessingGasCharge(evm.StateDB.TxHash())
+	if c > gas {
+		return 0, ErrOutOfGas
+	}
+	return gas - c, nil
+}
+
 // InvalidateExecution sets the error that will be returned by
 // [EVM.ExecutionInvalidated] for the length of the current transaction; i.e.
 // until [EVM.Reset] is called. This is honoured by state-transition logic to

core/vm/evm.libevm_test.go

@@ -22,6 +22,7 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
+	"github.com/ava-labs/libevm/common"
 	"github.com/ava-labs/libevm/params"
 )
 
@@ -46,6 +47,8 @@ func (o *evmArgOverrider) OverrideEVMResetArgs(r params.Rules, _ *EVMResetArgs)
 	}
 }
 
+func (o *evmArgOverrider) PreprocessingGasCharge(common.Hash) uint64 { return 0 }
+
 func (o *evmArgOverrider) register(t *testing.T) {
 	t.Helper()
 	TestOnlyClearRegisteredHooks()

core/vm/hooks.libevm.go

@@ -17,6 +17,7 @@
 package vm
 
 import (
+	"github.com/ava-labs/libevm/common"
 	"github.com/ava-labs/libevm/libevm/register"
 	"github.com/ava-labs/libevm/params"
 )
@@ -40,6 +41,14 @@ var libevmHooks register.AtMostOnce[Hooks]
 type Hooks interface {
 	OverrideNewEVMArgs(*NewEVMArgs) *NewEVMArgs
 	OverrideEVMResetArgs(params.Rules, *EVMResetArgs) *EVMResetArgs
+	Preprocessor
+}
+
+// A Preprocessor performs computation on a transaction before the
+// [EVMInterpreter] is invoked and reports its gas charge for spending at the
+// beginning of [EVM.Call].
+type Preprocessor interface {
+	PreprocessingGasCharge(tx common.Hash) uint64
 }
 
 // NewEVMArgs are the arguments received by [NewEVM], available for override

core/vm/interface.go

@@ -82,6 +82,8 @@ type StateDB interface {
 
 	AddLog(*types.Log)
 	AddPreimage(common.Hash, []byte)
+
+	StateDBRemainder
 }
 
 // CallContext provides a basic interface for the EVM calling conventions. The EVM

core/vm/interface.libevm.go

@@ -0,0 +1,27 @@
+// Copyright 2025 the libevm authors.
+//
+// The libevm additions to go-ethereum are free software: you can redistribute
+// them and/or modify them under the terms of the GNU Lesser General Public License
+// as published by the Free Software Foundation, either version 3 of the License,
+// or (at your option) any later version.
+//
+// The libevm additions are distributed in the hope that they will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
+// General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with the go-ethereum library. If not, see
+// <http://www.gnu.org/licenses/>.
+
+package vm
+
+import "github.com/ava-labs/libevm/common"
+
+// StateDBRemainder defines methods not included in the geth definition of
+// [StateDB] but present on the concrete type and exposed for libevm
+// functionality.
+type StateDBRemainder interface {
+	TxHash() common.Hash
+	TxIndex() int
+}

libevm/precompiles/parallel/parallel.go

@@ -22,8 +22,10 @@ import (
 	"fmt"
 	"sync"
 
+	"github.com/ava-labs/libevm/common"
 	"github.com/ava-labs/libevm/core"
 	"github.com/ava-labs/libevm/core/types"
+	"github.com/ava-labs/libevm/core/vm"
 )
 
 // A Handler is responsible for processing [types.Transactions] in an
@@ -47,21 +49,28 @@ type Processor[R any] struct {
 	handler Handler[R]
 	workers sync.WaitGroup
 	work    chan *job
-	results [](chan *R)
+	results [](chan result[R])
+	txGas   map[common.Hash]uint64
 }
 
 type job struct {
 	index int
 	tx    *types.Transaction
 }
 
+type result[T any] struct {
+	tx  common.Hash
+	val *T
+}
+
 // New constructs a new [Processor] with the specified number of concurrent
 // workers. [Processor.Close] must be called after the final call to
 // [Processor.FinishBlock] to avoid leaking goroutines.
 func New[R any](h Handler[R], workers int) *Processor[R] {
 	p := &Processor[R]{
 		handler: h,
 		work:    make(chan *job),
+		txGas:   make(map[common.Hash]uint64),
 	}
 
 	workers = max(workers, 1)
@@ -81,7 +90,10 @@ func (p *Processor[R]) worker() {
 		}
 
 		r := p.handler.Process(w.index, w.tx)
-		p.results[w.index] <- &r
+		p.results[w.index] <- result[R]{
+			tx:  w.tx.Hash(),
+			val: &r,
+		}
 	}
 }
 
@@ -101,7 +113,7 @@ func (p *Processor[R]) StartBlock(b *types.Block) error {
 	// We can reuse the channels already in the results slice because they're
 	// emptied by [Processor.FinishBlock].
 	for i, n := len(p.results), len(txs); i < n; i++ {
-		p.results = append(p.results, make(chan *R, 1))
+		p.results = append(p.results, make(chan result[R], 1))
 	}
 
 	for i, tx := range txs {
@@ -116,7 +128,10 @@ func (p *Processor[R]) StartBlock(b *types.Block) error {
 			})
 
 		default:
-			p.results[i] <- nil
+			p.results[i] <- result[R]{
+				tx:  tx.Hash(),
+				val: nil,
+			}
 		}
 	}
 
@@ -138,7 +153,7 @@ func (p *Processor[R]) FinishBlock(b *types.Block) {
 		// Every result channel is guaranteed to have some value in its buffer
 		// because [Processor.BeforeBlock] either sends a nil *R or it
 		// dispatches a job that will send a non-nil *R.
-		<-p.results[i]
+		delete(p.txGas, (<-p.results[i]).tx)
 	}
 }
 
@@ -147,27 +162,38 @@ func (p *Processor[R]) FinishBlock(b *types.Block) {
 // [Handler]. The returned boolean will be false if no processing occurred,
 // either because the [Handler] indicated as such or because the transaction
 // supplied insufficient gas.
+//
+// Multiple calls to Result with the same argument are allowed. Callers MUST NOT
+// charge the gas price for preprocessing as this is handled by
+// [Processor.PreprocessingGasCharge] if registered as a [vm.Preprocessor].
+// The same value will be returned by each call with the same argument, such
+// that if R is a pointer then modifications will persist between calls.
 func (p *Processor[R]) Result(i int) (R, bool) {
 	ch := p.results[i]
-	r := <-ch
+	r := (<-ch)
 	defer func() {
 		ch <- r
 	}()
 
-	if r == nil {
+	if r.val == nil {
 		// TODO(arr4n) if we're here then the implementoor might have a bug in
 		// their [Handler], so logging a warning is probably a good idea.
 		var zero R
 		return zero, false
 	}
-	return *r, true
+	return *r.val, true
 }
 
-func (p *Processor[R]) shouldProcess(tx *types.Transaction) (bool, error) {
+func (p *Processor[R]) shouldProcess(tx *types.Transaction) (ok bool, err error) {
 	cost, ok := p.handler.Gas(tx)
 	if !ok {
 		return false, nil
 	}
+	defer func() {
+		if ok && err == nil {
+			p.txGas[tx.Hash()] = cost
+		}
+	}()
 
 	spent, err := core.IntrinsicGas(
 		tx.Data(),
@@ -186,3 +212,11 @@ func (p *Processor[R]) shouldProcess(tx *types.Transaction) (bool, error) {
 	left := tx.Gas() - spent
 	return left >= cost, nil
 }
+
+var _ vm.Preprocessor = (*Processor[struct{}])(nil)
+
+// PreprocessingGasCharge implements the [vm.Preprocessor] interface and MUST be
+// registered via [vm.RegisterHooks] to ensure proper gas accounting.
+func (p *Processor[R]) PreprocessingGasCharge(tx common.Hash) uint64 {
+	return p.txGas[tx]
+}