core

Evolve Core Package

The core package is the zero-dependency foundation of Evolve. It provides the essential interfaces and types that enable modular builds of different application formats (e.g., sequencer, full node, light client) while preventing circular dependencies.

Purpose

The primary goal of the core package is to define common contracts (interfaces) for key components within Evolve, such as execution, sequencing, and data availability (DA). By having all other Evolve modules depend solely on core, we decouple their implementations. This allows each component to be compiled independently and avoids circular import issues, which can arise when components directly depend on each other.

Key Interfaces

The core package defines several crucial interfaces that standardize interactions between different parts of a Evolve node. Here are the main ones:

Execution

The Executor interface defines how the execution layer processes transactions and manages state transitions.

// core/execution/execution.go

// Executor defines the interface for the execution layer.
type Executor interface {
	// InitChain initializes the chain based on the genesis information.
	InitChain(ctx context.Context, genesisTime time.Time, initialHeight uint64, chainID string) (stateRoot []byte, maxBytes uint64, err error)
	// GetTxs retrieves transactions from the mempool.
	GetTxs(ctx context.Context) ([][]byte, error)
	// ExecuteTxs executes a block of transactions against the current state.
	ExecuteTxs(ctx context.Context, txs [][]byte, blockHeight uint64, timestamp time.Time, prevStateRoot []byte) (updatedStateRoot []byte, maxBytes uint64, err error)
	// SetFinal marks a block height as final.
	SetFinal(ctx context.Context, blockHeight uint64) error
}

Sequencing

The Sequencer interface outlines the responsibilities of the component that orders and batches transactions.

// core/sequencer/sequencing.go

// Sequencer defines the interface for the sequencing layer.
type Sequencer interface {
	// SubmitBatchTxs submits batch transactions to the sequencer.
	SubmitBatchTxs(ctx context.Context, req SubmitBatchTxsRequest) (*SubmitBatchTxsResponse, error)
	// GetNextBatch retrieves the next batch of transactions from the sequencer.
	GetNextBatch(ctx context.Context, req GetNextBatchRequest) (*GetNextBatchResponse, error)
	// VerifyBatch verifies a batch of transactions.
	VerifyBatch(ctx context.Context, req VerifyBatchRequest) (*VerifyBatchResponse, error)
}

Contributing

The core package is central to Evolve's architecture. Modifications here can have wide-ranging effects. Please adhere to the following guidelines when contributing:

• Compatibility: Prioritize backward compatibility. Changes to existing interfaces should be made carefully.
• ADRs for Significant Changes: For substantial changes, especially to interfaces, please propose them via an Architecture Decision Record (ADR). The ADR should detail the proposed changes and the reasoning behind them.
• Zero Dependencies: This package must remain dependency-free. Do not add any external modules to the core/go.mod file. Its strength lies in its simplicity and lack of external entanglements.