share

package
v0.11.0-rc0 Latest Latest
Warning

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

 Go to latest Published: May 30, 2023 License: Apache-2.0 Imports: 22 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
)

Variables

View Source 
var (
	// ErrNotFound is used to indicate that requested data could not be found.
	ErrNotFound = errors.New("share: data not found")
	// ErrNamespaceNotFound is returned by GetSharesByNamespace when data for requested root does
	// not include any shares from the given namespace
	ErrNamespaceNotFound = errors.New("share: namespace not found in data")
)
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 EmptyExtendedDataSquare added in v0.6.2 

func EmptyExtendedDataSquare() *rsmt2d.ExtendedDataSquare

EmptyExtendedDataSquare returns the EDS of the empty block data square.

func EnsureEmptySquareExists 

func EnsureEmptySquareExists(ctx context.Context, bServ blockservice.BlockService) (*rsmt2d.ExtendedDataSquare, 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/constructors.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 flattened chunks of data into Extended Data square and saves it in blockservice.BlockService

func NewNamespaceV0 

func NewNamespaceV0(subNId []byte) (namespace.ID, error)

NewNamespaceV0 takes variable size byte slice anc creates version 0 Namespace ID. The bytes slice must be <= 10 bytes.

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(context.Context) float64
}

Availability defines interface for validation of Shares' availability.

type DataHash added in v0.5.0 

type DataHash []byte

DataHash is a representation of the Root hash.

func (DataHash) IsEmptyRoot added in v0.7.0 

func (dh DataHash) IsEmptyRoot() bool

IsEmptyRoot check whether DataHash corresponds to the root of an empty block EDS.

func (DataHash) String added in v0.5.0 

func (dh DataHash) String() string

func (DataHash) Validate added in v0.5.0 

func (dh DataHash) Validate() error

type Getter added in v0.6.2 

type Getter interface {
	// GetShare gets a Share by coordinates in EDS.
	GetShare(ctx context.Context, root *Root, row, col int) (Share, error)

	// GetEDS gets the full EDS identified by the given root.
	GetEDS(context.Context, *Root) (*rsmt2d.ExtendedDataSquare, error)

	// GetSharesByNamespace gets all shares from an EDS within the given namespace.
	// Shares are returned in a row-by-row order if the namespace spans multiple rows.
	GetSharesByNamespace(context.Context, *Root, namespace.ID) (NamespacedShares, error)
}

Getter interface provides a set of accessors for shares by the Root. Automatically verifies integrity of shares(exceptions possible depending on the implementation).

type NamespacedRow added in v0.6.2 

type NamespacedRow struct {
	Shares []Share
	Proof  *nmt.Proof
}

NamespacedRow represents all shares with proofs within a specific namespace of a single EDS row.

type NamespacedShares added in v0.6.2 

type NamespacedShares []NamespacedRow

NamespacedShares represents all shares with proofs within a specific namespace of an EDS.

func (NamespacedShares) Flatten added in v0.6.2 

func (ns NamespacedShares) Flatten() []Share

Flatten returns the concatenated slice of all NamespacedRow shares.

func (NamespacedShares) Verify added in v0.6.2 

func (ns NamespacedShares) Verify(root *Root, nID namespace.ID) error

Verify validates NamespacedShares by checking every row with nmt inclusion proof.

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.

func EmptyRoot added in v0.7.0 

func EmptyRoot() *Root

EmptyRoot returns Root of an empty EDS.

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, *nmt.Proof, 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.

Source Files

View all Source files

Directories

Path Synopsis
availability
cache
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.
mocks
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.
test
eds
byzantine
byzantine/pb
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.
p2p
discovery
peers
shrexeds
shrexeds/pb
shrexnd
shrexnd/pb
shrexsub
shrexsub/pb

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.