share

package
v0.4.8-db Latest Latest
Warning

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

 Go to latest Published: Oct 13, 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 = consts.MaxSquareSize
	// NamespaceSize is a system-wide size for NMT namespaces.
	NamespaceSize = consts.NamespaceSize
	// Size is a system-wide size of a share, including both data and namespace ID
	Size = consts.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 = consts.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 

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 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 

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 *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.

Source Files

View all Source files

Directories

Path Synopsis
availability
cache
discovery
full
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.
test

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.