share

type API struct {
	Internal struct {
		SharesAvailable func(ctx context.Context, height uint64) error `perm:"read"`
		GetShare        func(
			ctx context.Context,
			height uint64,
			row, col int,
		) (libshare.Share, error) `perm:"read"`
		GetSamples func(
			ctx context.Context,
			height uint64,
			indices []shwap.SampleCoords,
		) ([]shwap.Sample, error) `perm:"read"`
		GetEDS func(
			ctx context.Context,
			height uint64,
		) (*rsmt2d.ExtendedDataSquare, error) `perm:"read"`
		GetRow func(
			context.Context,
			uint64,
			int,
		) (shwap.Row, error) `perm:"read"`
		GetNamespaceData func(
			ctx context.Context,
			height uint64,
			namespace libshare.Namespace,
		) (shwap.NamespaceData, error) `perm:"read"`
		GetRange func(
			ctx context.Context,
			height uint64,
			start, end int,
		) (*GetRangeResult, error) `perm:"read"`
	}
}

type Config struct {
	// EDSStoreParams sets eds store configuration parameters
	EDSStoreParams      *store.Parameters
	BlockStoreCacheSize uint

	UseShareExchange bool
	UseBitswap       bool

	// Shrex sets client and server configuration parameters of the shrex protocol
	ShrexClient *shrex.ClientParams
	ShrexServer *shrex.ServerParams
	// PeerManagerParams sets peer-manager configuration parameters
	PeerManagerParams *peers.Parameters

	LightAvailability *light.Parameters `toml:",omitempty"`
	Discovery         *discovery.Parameters
}

type GetRangeResult struct {
	// Shares contains the data shares retrieved from the specified range.
	Shares []libshare.Share
	// Proof proves that shares were included in the data root.
	Proof *types.ShareProof
}

type Module interface {
	// SharesAvailable performs a subjective validation to check if the shares committed to
	// the ExtendedHeader at the specified height are available and retrievable from the network.
	// Returns an error if the shares are not available or if validation fails.
	SharesAvailable(ctx context.Context, height uint64) error

	// GetShare retrieves a specific share from the Extended Data Square (EDS) at the given height
	// using its row and column coordinates. Returns the share data or an error if retrieval fails.
	GetShare(ctx context.Context, height uint64, rowIdx, colIdx int) (libshare.Share, error)

	// GetSamples retrieves multiple shares from the Extended Data Square (EDS) specified by the header
	// at the given sample coordinates. Returns an array of samples containing the requested shares
	// or an error if retrieval fails.
	GetSamples(ctx context.Context, height uint64, indices []shwap.SampleCoords) ([]shwap.Sample, error)

	// GetEDS retrieves the complete Extended Data Square (EDS) for the specified height.
	// The EDS contains all shares organized in a 2D matrix format with erasure coding.
	// Returns the full EDS or an error if retrieval fails.
	GetEDS(ctx context.Context, height uint64) (*rsmt2d.ExtendedDataSquare, error)

	// GetRow retrieves all shares from a specific row in the Extended Data Square (EDS)
	// at the given height. Returns the complete row of shares or an error if retrieval fails.
	GetRow(ctx context.Context, height uint64, rowIdx int) (shwap.Row, error)

	// GetNamespaceData retrieves all shares that belong to the specified namespace within
	// the Extended Data Square (EDS) at the given height. The shares are returned in a
	// row-by-row order, maintaining the original layout if the namespace spans multiple rows.
	// Returns the namespace data or an error if retrieval fails.
	GetNamespaceData(
		ctx context.Context,
		height uint64,
		namespace libshare.Namespace,
	) (shwap.NamespaceData, error)

	// GetRange retrieves a range of the *original* shares and their corresponding proofs within a specific
	// namespace in the Extended Data Square (EDS) at the given height. The range is defined
	// by start and end indexes. Returns the range data with proof to the data root or an error if retrieval fails.
	GetRange(
		ctx context.Context,
		height uint64,
		start, end int,
	) (*GetRangeResult, error)
}

type Window time.Duration