execution

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

type ExecPruner interface {
	// PruneExec should delete execution metadata for all heights up to and
	// including the given height. Implementations should be idempotent and track
	// their own progress so that repeated calls with the same or decreasing
	// heights are cheap no-ops.
	//
	// VI: xoá metadata ở mọi height <= height truyền vào. PHẢI idempotent —
	// gọi lại với cùng height (hoặc nhỏ hơn) không tốn thêm tài nguyên.
	PruneExec(ctx context.Context, height uint64) error
}

type ExecutionInfo struct {
	// MaxGas is the maximum gas allowed for transactions in a block.
	// For non-gas-based execution layers, this should be 0.
	//
	// VI: gas tối đa cho 1 block; 0 = không giới hạn (cho lớp không dùng gas/block).
	MaxGas uint64
}

type Executor interface {
	// InitChain initializes a new blockchain instance with genesis parameters.
	// Requirements:
	// - Must generate initial state root representing empty/genesis state
	// - Must validate and store genesis parameters for future reference
	// - Must ensure idempotency (repeated calls with identical parameters should return same results)
	// - Must return error if genesis parameters are invalid
	//
	// Parameters:
	// - ctx: Context for timeout/cancellation control
	// - genesisTime: timestamp marking chain start time in UTC
	// - initialHeight: First block height (must be > 0)
	// - chainID: Unique identifier string for the blockchain
	//
	// Returns:
	// - stateRoot: Hash representing initial state
	// - err: Any initialization errors
	//
	// VI: gọi 1 lần khi khởi tạo chain (block 0). Phải:
	// - sinh state root ban đầu (đại diện state "rỗng" / genesis),
	// - lưu tham số genesis cho lần truy vấn sau,
	// - idempotent: gọi lại với cùng tham số → trả cùng kết quả,
	// - báo lỗi nếu tham số sai. cosmos-exec cài hàm này trong
	//   apps/cosmos-exec/executor/executor.go.
	InitChain(ctx context.Context, genesisTime time.Time, initialHeight uint64, chainID string) (stateRoot []byte, err error)

	// GetTxs fetches available transactions from the execution layer's mempool.
	// Requirements:
	// - Must return currently valid transactions only
	// - Must handle empty mempool case gracefully
	// - Must respect context cancellation/timeout
	// - Should perform basic transaction validation
	// - Should not remove transactions from mempool
	// - May remove invalid transactions from mempool
	//
	// Parameters:
	// - ctx: Context for timeout/cancellation control
	//
	// Returns:
	// - [][]byte: Slice of valid transactions
	// - error: Any errors during transaction retrieval
	//
	// VI: lấy danh sách tx đang chờ trong mempool của execution layer để
	// đưa vào block kế tiếp. Phải:
	// - chỉ trả tx HỢP LỆ hiện tại,
	// - mempool rỗng → trả slice rỗng (không panic, không lỗi),
	// - tôn trọng ctx (huỷ/timeout),
	// - KHÔNG nên tự xoá tx khỏi mempool (trừ tx rõ ràng sai).
	GetTxs(ctx context.Context) ([][]byte, error)

	// ExecuteTxs processes transactions to produce a new block state.
	// Requirements:
	// - Must validate state transition against previous state root
	// - Must handle empty transaction list
	// - Must handle gracefully gibberish transactions
	// - Must maintain deterministic execution
	// - Must respect context cancellation/timeout
	// - The rest of the rules are defined by the specific execution layer
	//
	// Parameters:
	// - ctx: Context for timeout/cancellation control
	// - txs: Ordered list of transactions to execute
	// - blockHeight: Height of block being created (must be > 0)
	// - timestamp: Block creation time in UTC
	// - prevStateRoot: Previous block's state root hash
	//
	// Returns:
	// - updatedStateRoot: New state root after executing transactions
	// - err: Any execution errors
	//
	// VI: thực thi 1 block tx, trả state root mới. Phải:
	// - kiểm tra prevStateRoot khớp với state hiện tại (chống fork),
	// - xử lý gọn list tx rỗng / tx rác,
	// - DETERMINISTIC: cùng input phải ra cùng output trên mọi node
	//   (nếu khác → fork). cosmos-exec gọi app.FinalizeBlock + Commit để
	//   đảm bảo điều này.
	ExecuteTxs(ctx context.Context, txs [][]byte, blockHeight uint64, timestamp time.Time, prevStateRoot []byte) (updatedStateRoot []byte, err error)

	// SetFinal marks a block as finalized at the specified height.
	// Requirements:
	// - Must verify block exists at specified height
	// - Must be idempotent
	// - Must maintain finality guarantees (no reverting finalized blocks)
	// - Must respect context cancellation/timeout
	// - Should clean up any temporary state/resources
	//
	// Parameters:
	// - ctx: Context for timeout/cancellation control
	// - blockHeight: Height of block to finalize
	//
	// Returns:
	// - error: Any errors during finalization
	//
	// VI: ev-node gọi khi DA đã xác nhận block → đánh dấu "không thể đảo ngược".
	// Phải:
	// - kiểm tra block ở height đó có thật,
	// - idempotent (gọi lại OK),
	// - KHÔNG được rollback block đã finalize sau điểm này,
	// - giải phóng state tạm liên quan tới block đó.
	SetFinal(ctx context.Context, blockHeight uint64) error

	// GetExecutionInfo returns current execution layer parameters.
	//
	// Parameters:
	// - ctx: Context for timeout/cancellation control
	//
	// Returns:
	// - info: Current execution parameters
	// - error: Any errors during retrieval
	//
	// VI: trả tham số runtime của lớp thực thi (vd: gas tối đa 1 block).
	// ev-node dùng để biết giới hạn khi đóng block. cosmos-exec hiện trả
	// MaxGas=0 (không giới hạn — phù hợp app không tính theo gas/block).
	GetExecutionInfo(ctx context.Context) (ExecutionInfo, error)

	// FilterTxs validates force-included transactions and applies gas and size filtering for all passed txs.
	//
	// The function marks transaction with a filter status. The sequencer knows how to proceed with it:
	// - Transactions passing all filters constraints and that can be included (FilterOK)
	// - Invalid/unparseable force-included transactions (gibberish) (FilterRemove)
	// - Any transactions that would exceed the cumulative gas limit (FilterPostpone)
	//
	// For non-gas-based execution layers (maxGas=0) should not filter by gas.
	//
	// Parameters:
	// - ctx: Context for timeout/cancellation control
	// - txs: All transactions (force-included + mempool)
	// - maxBytes: Maximum cumulative size allowed (0 means no size limit)
	// - maxGas: Maximum cumulative gas allowed (0 means no gas limit)
	// - hasForceIncludedTransaction: Boolean wether force included txs are present
	//
	// Returns:
	// - result: The filter status of all txs. The len(txs) == len(result).
	// - err: Any errors during filtering (not validation errors, which result in filtering)
	//
	// VI: lọc tx (force-include + mempool) trước khi sequencer đóng block.
	// Trả slice trạng thái CÙNG ĐỘ DÀI với txs — mỗi tx có 1 trong 3 trạng thái:
	// FilterOK (giữ), FilterRemove (vứt vì hỏng), FilterPostpone (hoãn block sau
	// vì vượt giới hạn). maxBytes/maxGas = 0 nghĩa là không giới hạn theo loại đó.
	FilterTxs(ctx context.Context, txs [][]byte, maxBytes, maxGas uint64, hasForceIncludedTransaction bool) ([]FilterStatus, error)
}

type FilterStatus int

type HeightProvider interface {
	// GetLatestHeight returns the current block height of the execution layer.
	// This is useful for detecting desynchronization between ev-node and the execution layer
	// after crashes or restarts.
	//
	// Parameters:
	// - ctx: Context for timeout/cancellation control
	//
	// Returns:
	// - height: Current block height of the execution layer
	// - error: Any errors during height retrieval
	//
	// VI: trả chiều cao block cao nhất đã thực thi xong. Dùng để khôi phục
	// đồng bộ giữa ev-node và execution layer sau restart/crash.
	GetLatestHeight(ctx context.Context) (uint64, error)
}

type Rollbackable interface {
	// Rollback resets the execution layer head to the specified height.
	// VI: đưa head về targetHeight (đồng nghĩa "đảo block > targetHeight").
	Rollback(ctx context.Context, targetHeight uint64) error
}