package repository

import (
	"context"

	"github.com/genex/chain-indexer/internal/domain/entity"
)

// BlockRepository defines the contract for block persistence.
// Infrastructure layer must provide the concrete implementation.
type BlockRepository interface {
	// SaveBlock persists a block. If a block at the same height exists, it is overwritten.
	SaveBlock(ctx context.Context, block *entity.Block) error

	// FindByHeight retrieves a block by its height. Returns nil if not found.
	FindByHeight(ctx context.Context, height int64) (*entity.Block, error)

	// FindLatest returns the most recently indexed block. Returns nil if no blocks exist.
	FindLatest(ctx context.Context) (*entity.Block, error)

	// FindRange returns all blocks in the height range [fromHeight, toHeight] inclusive,
	// ordered by height ascending.
	FindRange(ctx context.Context, fromHeight, toHeight int64) ([]*entity.Block, error)

	// FindRecent returns the most recent N blocks, ordered by height descending.
	FindRecent(ctx context.Context, limit int) ([]*entity.Block, error)
}
