consensus/engine/chain/block/block.go

package block

import (
	"context"
	"time"

	"github.com/luxfi/ids"
)

// Block is a block in the chain
type Block interface {
	ID() ids.ID
	Parent() ids.ID // Alias for ParentID for compatibility
	ParentID() ids.ID
	Height() uint64
	Timestamp() time.Time
	Status() uint8
	Verify(context.Context) error
	Accept(context.Context) error
	Reject(context.Context) error
	Bytes() []byte
}

// Epoch represents a P-Chain epoch for validator set coordination
type Epoch struct {
	PChainHeight uint64 `serialize:"true" json:"pChainHeight"`
	Number       uint64 `serialize:"true" json:"number"`
	StartTime    int64  `serialize:"true" json:"startTime"`
}

// SignedBlock extends Block with proposer and epoch information
type SignedBlock interface {
	Block

	// PChainHeight returns the P-Chain height when this block was proposed
	PChainHeight() uint64

	// PChainEpoch returns the P-Chain epoch information
	PChainEpoch() Epoch

	// Timestamp returns the block timestamp
	Timestamp() time.Time

	// Proposer returns the ID of the node that proposed this block.
	// If no node signed this block, ids.EmptyNodeID will be returned.
	Proposer() ids.NodeID
}

// ChainVM defines the interface for a blockchain VM
type ChainVM interface {
	// Initialize initializes the VM
	Initialize(
		ctx context.Context,
		chainCtx interface{},
		db interface{},
		genesisBytes []byte,
		upgradeBytes []byte,
		configBytes []byte,
		msgChan interface{},
		fxs []interface{},
		appSender interface{},
	) error

	// BuildBlock builds a new block
	BuildBlock(context.Context) (Block, error)

	// ParseBlock parses a block from bytes
	ParseBlock(context.Context, []byte) (Block, error)

	// GetBlock gets a block by ID
	GetBlock(context.Context, ids.ID) (Block, error)

	// Shutdown shuts down the VM
	Shutdown(context.Context) error

	// NewHTTPHandler returns a new HTTP handler for the VM
	NewHTTPHandler(context.Context) (interface{}, error)

	// SetState sets the VM state
	SetState(context.Context, uint32) error

	// Version returns the VM version
	Version(context.Context) (string, error)

	// Network callbacks - optional
	Connected(context.Context, ids.NodeID, interface{}) error
	Disconnected(context.Context, ids.NodeID) error
	HealthCheck(context.Context) (interface{}, error)

	// GetBlockIDAtHeight gets block ID at a specific height
	GetBlockIDAtHeight(context.Context, uint64) (ids.ID, error)

	// SetPreference sets the preferred block
	SetPreference(context.Context, ids.ID) error

	// LastAccepted returns the last accepted block
	LastAccepted(context.Context) (ids.ID, error)

	// WaitForEvent blocks until an event occurs that should trigger block building
	WaitForEvent(context.Context) (interface{}, error)
}

// StateSyncMode defines state sync modes
type StateSyncMode uint8

const (
	StateSyncSkipped StateSyncMode = iota
	StateSyncStatic
	StateSyncDynamic
)

// StateSyncableVM defines a VM that supports state sync
type StateSyncableVM interface {
	ChainVM

	// StateSyncEnabled returns whether state sync is enabled
	StateSyncEnabled(context.Context) (bool, error)

	// GetOngoingSyncStateSummary returns the ongoing sync state summary
	GetOngoingSyncStateSummary(context.Context) (StateSummary, error)

	// GetLastStateSummary returns the last state summary
	GetLastStateSummary(context.Context) (StateSummary, error)

	// ParseStateSummary parses a state summary
	ParseStateSummary(context.Context, []byte) (StateSummary, error)

	// GetStateSummary gets a state summary by height
	GetStateSummary(context.Context, uint64) (StateSummary, error)
}

// StateSummary represents a state summary
type StateSummary interface {
	ID() ids.ID
	Height() uint64
	Bytes() []byte
	Accept(context.Context) (StateSyncMode, error)
}

// BuildBlockWithContextVM extends ChainVM with context support
type BuildBlockWithContextVM interface {
	ChainVM
	BuildBlockWithContext(context.Context, *Context) (Block, error)
}

// Context provides context for building blocks
type Context struct {
	PChainHeight uint64
}

// WithVerifyContext provides verify context support
type WithVerifyContext interface {
	// VerifyWithContext verifies with context
	VerifyWithContext(context.Context, *Context) error

	// ShouldVerifyWithContext returns whether to verify with context
	ShouldVerifyWithContext(context.Context) (bool, error)
}

// GetAncestors retrieves ancestors of a block up to a maximum count
func GetAncestors(
	ctx context.Context,
	vm ChainVM,
	blkID ids.ID,
	maxBlocks int,
	maxBlocksSize int,
	maxBlocksRetrievalTime time.Duration,
) ([][]byte, error) {
	if maxBlocks <= 0 {
		return nil, nil
	}

	startTime := time.Now()
	ancestors := make([][]byte, 0, maxBlocks)
	totalSize := 0

	for len(ancestors) < maxBlocks && totalSize < maxBlocksSize {
		if time.Since(startTime) > maxBlocksRetrievalTime {
			break
		}

		blk, err := vm.GetBlock(ctx, blkID)
		if err != nil {
			break
		}

		blkBytes := blk.Bytes()
		totalSize += len(blkBytes)
		if totalSize > maxBlocksSize {
			break
		}

		ancestors = append(ancestors, blkBytes)
		blkID = blk.ParentID()
	}

	return ancestors, nil
}

// Network callbacks
type ChainVMWithNetwork interface {
	ChainVM
	Connected(ctx context.Context, nodeID ids.NodeID, version interface{}) error
	Disconnected(ctx context.Context, nodeID ids.NodeID) error
}

// HealthCheck interface
type ChainVMWithHealth interface {
	ChainVM
	HealthCheck(ctx context.Context) (interface{}, error)
}