share

Documentation

Overview

Package share contains logic related to the retrieval and random sampling of shares of block data.

Though this package contains several useful methods for getting specific shares and/or sampling them at random, a particularly useful method is GetSharesByNamespace which retrieves all shares of block data of the given namespace.ID from the block associated with the given DataAvailabilityHeader (DAH, but referred to as Root within this package).

This package also contains declaration of the Availability interface. Implementations of the interface (light, full) are located in the availability sub-folder. Light Availability implementation samples for 16 shares of block data (enough to verify the block's availability on the network). Full Availability implementation samples for as many shares as necessary to fully reconstruct the block data.

Index

• Constants
• Variables
• func AddShares(ctx context.Context, shares []Share, adder blockservice.BlockService) (*rsmt2d.ExtendedDataSquare, error)
• func Data(s Share) []byte
• func EnsureEmptySquareExists(ctx context.Context, bServ blockservice.BlockService) error
• func EqualEDS(a *rsmt2d.ExtendedDataSquare, b *rsmt2d.ExtendedDataSquare) bool
• func GetShares(ctx context.Context, bGetter blockservice.BlockGetter, root cid.Cid, ...)
• func ID(s Share) namespace.ID
• func ImportShares(ctx context.Context, shares [][]byte, adder blockservice.BlockService) (*rsmt2d.ExtendedDataSquare, error)
• func RandEDS(t require.TestingT, size int) *rsmt2d.ExtendedDataSquare
• type Availability
• type Root
• type Share
  • func ExtractEDS(eds *rsmt2d.ExtendedDataSquare) []Share
  • func ExtractODS(eds *rsmt2d.ExtendedDataSquare) []Share
  • func GetShare(ctx context.Context, bGetter blockservice.BlockGetter, rootCid cid.Cid, ...) (Share, error)
  • func GetSharesByNamespace(ctx context.Context, bGetter blockservice.BlockGetter, root cid.Cid, ...) ([]Share, error)
  • func RandShares(t require.TestingT, total int) []Share

Constants

const (
	// MaxSquareSize is currently the maximum size supported for unerasured data in rsmt2d.ExtendedDataSquare.
	MaxSquareSize = appconsts.MaxSquareSize
	// NamespaceSize is a system-wide size for NMT namespaces.
	NamespaceSize = appconsts.NamespaceSize
	// Size is a system-wide size of a share, including both data and namespace ID
	Size = appconsts.ShareSize
)

const AvailabilityTimeout = 20 * time.Minute

AvailabilityTimeout specifies timeout for DA validation during which data have to be found on the network, otherwise ErrNotAvailable is fired. TODO: https://github.com/celestiaorg/celestia-node/issues/10

Variables

var (

	// DefaultRSMT2DCodec sets the default rsmt2d.Codec for shares.
	DefaultRSMT2DCodec = appconsts.DefaultCodec
)

var ErrNotAvailable = errors.New("share: data not available")

ErrNotAvailable is returned whenever DA sampling fails.

Functions

func AddShares

func AddShares(
	ctx context.Context,
	shares []Share,
	adder blockservice.BlockService,
) (*rsmt2d.ExtendedDataSquare, error)

AddShares erasures and extends shares to blockservice.BlockService using the provided ipld.NodeAdder.

func Data

func Data(s Share) []byte

Data gets data from the share.

func EnsureEmptySquareExists

func EnsureEmptySquareExists(ctx context.Context, bServ blockservice.BlockService) error

EnsureEmptySquareExists checks if the given DAG contains an empty block data square. If it does not, it stores an empty block. This optimization exists to prevent redundant storing of empty block data so that it is only stored once and returned upon request for a block with an empty data square. Ref: header/header.go#L56

func EqualEDS

func EqualEDS(a *rsmt2d.ExtendedDataSquare, b *rsmt2d.ExtendedDataSquare) bool

EqualEDS check whether two given EDSes are equal. TODO(Wondertan): Move to rsmt2d TODO(Wondertan): Propose use of int by default instead of uint for the sake convenience and Golang practices

func GetShares

func GetShares(ctx context.Context, bGetter blockservice.BlockGetter, root cid.Cid, shares int, put func(int, Share))

GetShares walks the tree of a given root and puts shares into the given 'put' func. Does not return any error, and returns/unblocks only on success (got all shares) or on context cancellation.

func ID

func ID(s Share) namespace.ID

ID gets the namespace ID from the share.

func ImportShares

func ImportShares(
	ctx context.Context,
	shares [][]byte,
	adder blockservice.BlockService) (*rsmt2d.ExtendedDataSquare, error)

ImportShares imports flattend chunks of data into Extended Data square and saves it in blockservice.BlockService

func RandEDS

func RandEDS(t require.TestingT, size int) *rsmt2d.ExtendedDataSquare

RandEDS generates EDS filled with the random data with the given size for original square. It uses require.TestingT to be able to take both a *testing.T and a *testing.B.

Types

type Availability

type Availability interface {
	// SharesAvailable subjectively validates if Shares committed to the given Root are available on the Network.
	SharesAvailable(context.Context, *Root) error
	// ProbabilityOfAvailability calculates the probability of the data square
	// being available based on the number of samples collected.
	// TODO(@Wondertan): Merge with SharesAvailable method, eventually
	ProbabilityOfAvailability() float64
}

Availability defines interface for validation of Shares' availability.

type Root

type Root = da.DataAvailabilityHeader

Root represents root commitment to multiple Shares. In practice, it is a commitment to all the Data in a square.

type Share

type Share = []byte

Share contains the raw share data without the corresponding namespace. NOTE: Alias for the byte is chosen to keep maximal compatibility, especially with rsmt2d. Ideally, we should define reusable type elsewhere and make everyone(Core, rsmt2d, ipld) to rely on it.

func ExtractEDS

func ExtractEDS(eds *rsmt2d.ExtendedDataSquare) []Share

ExtractEDS takes an EDS and extracts all shares from it in a flattened slice(row by row).

func ExtractODS

func ExtractODS(eds *rsmt2d.ExtendedDataSquare) []Share

ExtractODS returns the original shares of the given ExtendedDataSquare. This is a helper function for circumstances where AddShares must be used after the EDS has already been generated.

func GetShare

func GetShare(
	ctx context.Context,
	bGetter blockservice.BlockGetter,
	rootCid cid.Cid,
	leafIndex int,
	totalLeafs int,
) (Share, error)

GetShare fetches and returns the data for leaf `leafIndex` of root `rootCid`.

func GetSharesByNamespace

func GetSharesByNamespace(
	ctx context.Context,
	bGetter blockservice.BlockGetter,
	root cid.Cid,
	nID namespace.ID,
	maxShares int,
) ([]Share, error)

GetSharesByNamespace walks the tree of a given root and returns its shares within the given namespace.ID. If a share could not be retrieved, err is not nil, and the returned array contains nil shares in place of the shares it was unable to retrieve.

func RandShares

func RandShares(t require.TestingT, total int) []Share

RandShares generate 'total' amount of shares filled with random data. It uses require.TestingT to be able to take both a *testing.T and a *testing.B.