share

package
v0.5.0-cka Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2022 License: Apache-2.0 Imports: 24 Imported by: 15

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

View Source
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
)
View Source
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

View Source
var (

	// DefaultRSMT2DCodec sets the default rsmt2d.Codec for shares.
	DefaultRSMT2DCodec = appconsts.DefaultCodec
)
View Source
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

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 ProtoToProof

func ProtoToProof(protoProof *pb.MerkleProof) nmt.Proof

func RandEDS

func RandEDS(t *testing.T, size int) *rsmt2d.ExtendedDataSquare

RandEDS generates EDS filled with the random data with the given size for original square.

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 ErrByzantine

type ErrByzantine struct {
	Index  uint32
	Shares []*ShareWithProof
	Axis   rsmt2d.Axis
}

ErrByzantine is a thrown when recovered data square is not correct (merkle proofs do not match parity erasure-coding data).

It is converted from rsmt2d.ByzantineRow/Col + Merkle Proof for each share.

func NewErrByzantine

func NewErrByzantine(
	ctx context.Context,
	bGetter blockservice.BlockGetter,
	dah *da.DataAvailabilityHeader,
	errByz *rsmt2d.ErrByzantineData,
) *ErrByzantine

NewErrByzantine creates new ErrByzantine from rsmt2d error. If error happens during proof collection, it terminates the process with os.Exit(1).

func (*ErrByzantine) Error

func (e *ErrByzantine) Error() string

type Root

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 *testing.T, total int) []Share

RandShares generate 'total' amount of shares filled with random data.

type ShareWithProof

type ShareWithProof struct {
	// Share is a full data including namespace
	Share
	// Proof is a Merkle Proof of current share
	Proof *nmt.Proof
}

ShareWithProof contains data with corresponding Merkle Proof

func GetProofsForShares

func GetProofsForShares(
	ctx context.Context,
	bGetter blockservice.BlockGetter,
	root cid.Cid,
	shares [][]byte,
) ([]*ShareWithProof, error)

GetProofsForShares fetches Merkle proofs for the given shares and returns the result as an array of ShareWithProof.

func NewShareWithProof

func NewShareWithProof(index int, share Share, pathToLeaf []cid.Cid) *ShareWithProof

NewShareWithProof takes the given leaf and its path, starting from the tree root, and computes the nmt.Proof for it.

func ProtoToShare

func ProtoToShare(protoShares []*pb.Share) []*ShareWithProof

func (*ShareWithProof) ShareWithProofToProto

func (s *ShareWithProof) ShareWithProofToProto() *pb.Share

func (*ShareWithProof) Validate

func (s *ShareWithProof) Validate(root cid.Cid) bool

Validate validates inclusion of the share under the given root CID.

Directories

Path Synopsis
availability
light
TODO(@Wondertan): Instead of doing sampling over the coordinates do a random walk over NMT trees.
TODO(@Wondertan): Instead of doing sampling over the coordinates do a random walk over NMT trees.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL