parallel

Documentation

Overview

Package parallel defines interfaces for optional parallel block execution and GPU acceleration in the Lux EVM.

By default (no build tags), a sequential executor is used. When built with -tags parallel, the evmgpu Block-STM engine is linked. When built with -tags parallel,gpu, GPU-accelerated hashing and ecrecover are also enabled.

This package lives in lux/evm so that the state processor can call into it without importing evmgpu. The evmgpu package provides the real implementations that satisfy these interfaces.

Package parallel defines interfaces for optional parallel block execution and GPU acceleration in the Lux EVM.

No build tags required. GPU acceleration is auto-detected at init time:

• darwin + CGo: Metal GPU via gpu_bridge.go
• linux + CGo + CUDA: NVIDIA GPU (future)
• otherwise: CPU sequential (zero overhead)

The registration pattern allows platform-specific init() functions to register GPU backends without import cycles.

Index

• func RegisterExecutor(e BlockExecutor)
• func RegisterGPU(g GPUAccelerator)
• func RegisterTransactionExecutor(backend EVMBackend, e TransactionExecutor)
• func SetBackend(backend EVMBackend)
• type BlockExecutor
  • func DefaultExecutor() BlockExecutor
• type BlockSTMExecutor
  • func NewBlockSTMExecutor(workers int, applyFn TxApplyFunc) *BlockSTMExecutor
  • func (e *BlockSTMExecutor) ExecuteBlock(config *ethparams.ChainConfig, header *types.Header, txs types.Transactions, ...) ([]*types.Receipt, error)
• type EVMBackend
  • func ActiveBackend() EVMBackend
  • func AvailableBackends() []EVMBackend
• type GPUAccelerator
  • func DefaultGPU() GPUAccelerator
• type Metrics
• type TransactionExecutor
  • func DefaultTransactionExecutor() TransactionExecutor
• type TxApplyFunc

Functions

func RegisterExecutor

func RegisterExecutor(e BlockExecutor)

RegisterExecutor sets the parallel block executor.

func RegisterGPU

func RegisterGPU(g GPUAccelerator)

RegisterGPU sets the GPU accelerator.

func RegisterTransactionExecutor

func RegisterTransactionExecutor(backend EVMBackend, e TransactionExecutor)

RegisterTransactionExecutor registers a per-tx executor for a given backend. Call from init() in backend packages (e.g., revmbackend, cevmbackend).

func SetBackend

func SetBackend(backend EVMBackend)

SetBackend selects the active EVM backend. Use AutoEVM to select the best available.

Types

type BlockExecutor

type BlockExecutor interface {
	// ExecuteBlock processes all transactions in a block.
	// Returns receipts in original transaction order, or an error.
	// A nil return (nil, nil) means "not handled, fall through to sequential."
	ExecuteBlock(
		config *ethparams.ChainConfig,
		header *types.Header,
		txs types.Transactions,
		statedb *state.StateDB,
		vmCfg vm.Config,
	) ([]*types.Receipt, error)
}

BlockExecutor processes all transactions in a block. The default implementation delegates to sequential per-tx execution. The parallel implementation uses Block-STM speculative execution.

func DefaultExecutor

func DefaultExecutor() BlockExecutor

DefaultExecutor returns the registered parallel executor, or a no-op sequential fallback if none was registered.

type BlockSTMExecutor

type BlockSTMExecutor struct {
	// contains filtered or unexported fields
}

BlockSTMExecutor implements BlockExecutor using the Block-STM algorithm. It executes all transactions in a block speculatively in parallel, detects read-write conflicts, and re-executes conflicting transactions.

func NewBlockSTMExecutor

func NewBlockSTMExecutor(workers int, applyFn TxApplyFunc) *BlockSTMExecutor

NewBlockSTMExecutor creates a Block-STM executor. Pass 0 for workers to use runtime.NumCPU(). applyFn is the function that executes a single tx against a StateDB.

func (*BlockSTMExecutor) ExecuteBlock

func (e *BlockSTMExecutor) ExecuteBlock(
	config *ethparams.ChainConfig,
	header *types.Header,
	txs types.Transactions,
	statedb *state.StateDB,
	vmCfg vm.Config,
) ([]*types.Receipt, error)

ExecuteBlock processes all transactions in the block using Block-STM.

Returns (nil, nil) when:

• The block has fewer than 2 transactions (no benefit from parallelism).
• No apply function was configured.

type EVMBackend

type EVMBackend string

EVMBackend identifies which EVM implementation to use.

const (
	// GoEVM is the default Go EVM from luxfi/geth (geth interpreter).
	GoEVM EVMBackend = "gevm"

	// RustEVM uses revm (Rust EVM) via FFI for execution.
	// Native Block-STM parallel execution, memory-safe.
	RustEVM EVMBackend = "revm"

	// CppEVM is the Lux C++ EVM via CGo.
	// Fastest single-threaded interpreter, SIMD opcodes, GPU kernel dispatch.
	CppEVM EVMBackend = "cevm"

	// AutoEVM selects the best available backend at runtime.
	AutoEVM EVMBackend = "auto"
)

func ActiveBackend

func ActiveBackend() EVMBackend

ActiveBackend returns the currently selected EVM backend.

func AvailableBackends

func AvailableBackends() []EVMBackend

AvailableBackends returns all registered backend names.

type GPUAccelerator

type GPUAccelerator interface {
	// Available reports whether a GPU backend is detected.
	Available() bool

	// BatchEcrecover recovers sender addresses for a batch of transactions.
	// Returns a map from tx hash to recovered sender address.
	BatchEcrecover(txs []*types.Transaction) (map[common.Hash]common.Address, error)

	// BatchKeccak hashes multiple inputs on GPU.
	BatchKeccak(inputs [][]byte) ([]common.Hash, error)
}

GPUAccelerator provides optional GPU-offloaded crypto operations. The default implementation returns Available() == false.

func DefaultGPU

func DefaultGPU() GPUAccelerator

DefaultGPU returns the registered GPU accelerator, or a no-op if none was registered.

type Metrics

type Metrics struct {
	BlocksProcessed atomic.Int64
	TxsProcessed    atomic.Int64
	TxsReExecuted   atomic.Int64
}

Metrics exposes Block-STM conflict statistics for observability.

var DefaultMetrics Metrics

DefaultMetrics is the global Block-STM metrics instance.

type TransactionExecutor

type TransactionExecutor interface {
	// Backend returns which EVM implementation this executor uses.
	Backend() EVMBackend

	// ExecuteTransaction runs a single transaction against the state.
	// Returns the execution result or error.
	ExecuteTransaction(
		config *ethparams.ChainConfig,
		header *types.Header,
		tx *types.Transaction,
		statedb *state.StateDB,
		vmCfg vm.Config,
		gasPool uint64,
	) (*types.Receipt, error)

	// SupportsParallel returns true if this backend can execute
	// transactions in parallel (e.g., Block-STM in revm, GPU in cevm).
	SupportsParallel() bool

	// SupportsGPU returns true if this backend can offload computation
	// to GPU (e.g., evmone with CUDA/Metal kernel dispatch).
	SupportsGPU() bool
}

TransactionExecutor processes a single transaction against a state. This is the per-tx abstraction point for swappable EVM backends.

Backends implement this to replace the default Go EVM interpreter:

• GoEVM: delegates to geth's vm.EVM.Call()/Create() (default)
• RustEVM: calls revm via FFI (faster single-thread, native Block-STM)
• CppEVM: calls evmone via CGo (fastest interpreter, GPU offload)

The StateDB interface is the bridge — all backends read/write state through the same Go StateDB, ensuring consensus compatibility.

func DefaultTransactionExecutor

func DefaultTransactionExecutor() TransactionExecutor

DefaultTransactionExecutor returns the tx executor for the active backend.

type TxApplyFunc

type TxApplyFunc func(
	config *ethparams.ChainConfig,
	header *types.Header,
	tx *types.Transaction,
	statedb *state.StateDB,
	vmCfg vm.Config,
	txIndex int,
) (*types.Receipt, error)

TxApplyFunc executes a single transaction against the given state and returns the receipt. This is the injection point that breaks the circular dependency between core and parallel: core.applyTransaction satisfies this signature.

The function must call statedb.SetTxContext before execution.