share

package
v0.11.0-rc12 Latest Latest
Warning

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

 Go to latest Published: Sep 7, 2023 License: Apache-2.0 Imports: 14 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 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 NamespaceSize = appns.NamespaceSize

NamespaceSize is a system-wide size for NMT namespaces.

View Source 
const (
	// Size is a system-wide size of a share, including both data and namespace GetNamespace
	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")
	// ErrOutOfBounds is used to indicate that a passed row or column index is out of bounds of the
	// square size.
	ErrOutOfBounds = errors.New("share: row or column index is larger than square size")
)
View Source 
var (
	// MaxPrimaryReservedNamespace is the highest primary reserved namespace.
	// Namespaces lower than this are reserved for protocol use.
	MaxPrimaryReservedNamespace = Namespace(appns.MaxPrimaryReservedNamespace.Bytes())
	// MinSecondaryReservedNamespace is the lowest secondary reserved namespace
	// reserved for protocol use. Namespaces higher than this are reserved for
	// protocol use.
	MinSecondaryReservedNamespace   = Namespace(appns.MinSecondaryReservedNamespace.Bytes())
	ParitySharesNamespace           = Namespace(appns.ParitySharesNamespace.Bytes())
	TailPaddingNamespace            = Namespace(appns.TailPaddingNamespace.Bytes())
	PrimaryReservedPaddingNamespace = Namespace(appns.PrimaryReservedPaddingNamespace.Bytes())
	TxNamespace                     = Namespace(appns.TxNamespace.Bytes())
	PayForBlobNamespace             = Namespace(appns.PayForBlobNamespace.Bytes())
	ISRNamespace                    = Namespace(appns.IntermediateStateRootsNamespace.Bytes())
)

Various reserved namespaces.

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.

View Source 
var (
	// MaxSquareSize is currently the maximum size supported for unerasured data in
	// rsmt2d.ExtendedDataSquare.
	MaxSquareSize = appconsts.SquareSizeUpperBound(appconsts.LatestVersion)
)

Functions

func EmptyExtendedDataSquare added in v0.6.2 

func EmptyExtendedDataSquare() *rsmt2d.ExtendedDataSquare

EmptyExtendedDataSquare returns the EDS of the empty block data square.

func GetData added in v0.11.0 

func GetData(s Share) []byte

GetData slices out data of the Share.

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 MustDataHashFromString added in v0.11.0 

func MustDataHashFromString(datahash string) DataHash

MustDataHashFromString converts a hex string to a valid datahash.

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.
	// Inclusion of returned data could be verified using Verify method on NamespacedShares.
	// If no shares are found for target namespace non-inclusion could be also verified by calling
	// Verify method.
	GetSharesByNamespace(context.Context, *Root, Namespace) (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 Namespace added in v0.11.0 

type Namespace []byte

Namespace represents namespace of a Share. Consists of version byte and namespace ID.

func GetNamespace added in v0.11.0 

func GetNamespace(s Share) Namespace

GetNamespace slices Namespace out of the Share.

func NamespaceFromBytes added in v0.11.0 

func NamespaceFromBytes(b []byte) (Namespace, error)

NamespaceFromBytes converts bytes into Namespace and validates it.

func NewBlobNamespaceV0 added in v0.11.0 

func NewBlobNamespaceV0(id []byte) (Namespace, error)

NewBlobNamespaceV0 takes a variable size byte slice and creates a valid version 0 Blob Namespace. The byte slice must be <= 10 bytes. If it is less than 10 bytes, it will be left padded to size 10 with 0s. Use predefined namespaces above, if non-blob namespace is needed.

func (Namespace) Equals added in v0.11.0 

func (n Namespace) Equals(target Namespace) bool

Equals compares two Namespaces.

func (Namespace) ID added in v0.11.0 

func (n Namespace) ID() namespace.ID

ID reports ID of the Namespace.

func (Namespace) IsAboveMax added in v0.11.0 

func (n Namespace) IsAboveMax(nodeHash []byte) bool

IsAboveMax checks if the namespace is above the maximum namespace of the given hash.

func (Namespace) IsBelowMin added in v0.11.0 

func (n Namespace) IsBelowMin(nodeHash []byte) bool

IsBelowMin checks if the target namespace is below the minimum namespace of the given hash.

func (Namespace) IsGreater added in v0.11.0 

func (n Namespace) IsGreater(target Namespace) bool

IsGreater reports if the Namespace is greater than the target.

func (Namespace) IsGreaterOrEqualThan added in v0.11.0 

func (n Namespace) IsGreaterOrEqualThan(target Namespace) bool

IsGreaterOrEqualThan reports if the Namespace is greater or equal than the target.

func (Namespace) IsLess added in v0.11.0 

func (n Namespace) IsLess(target Namespace) bool

IsLess reports if the Namespace is less than the target.

func (Namespace) IsLessOrEqual added in v0.11.0 

func (n Namespace) IsLessOrEqual(target Namespace) bool

IsLessOrEqual reports if the Namespace is less than the target.

func (Namespace) IsOutsideRange added in v0.11.0 

func (n Namespace) IsOutsideRange(leftNodeHash, rightNodeHash []byte) bool

IsOutsideRange checks if the namespace is outside the min-max range of the given hashes.

func (Namespace) Len added in v0.11.0 

func (n Namespace) Len() int

Len reports the total length of the namespace.

func (Namespace) Repeat added in v0.11.0 

func (n Namespace) Repeat(t int) []Namespace

Repeat copies the Namespace t times.

func (Namespace) String added in v0.11.0 

func (n Namespace) String() string

String stringifies the Namespace.

func (Namespace) ToAppNamespace added in v0.11.0 

func (n Namespace) ToAppNamespace() appns.Namespace

ToAppNamespace converts the Namespace to App's definition of Namespace. TODO: Unify types between node and app

func (Namespace) ToNMT added in v0.11.0 

func (n Namespace) ToNMT() namespace.ID

ToNMT converts the whole Namespace(both Version and ID parts) into NMT's namespace.ID NOTE: Once https://github.com/celestiaorg/nmt/issues/206 is closed Namespace should become NNT's type.

func (Namespace) Validate added in v0.11.0 

func (n Namespace) Validate() error

Validate checks if the namespace is correct.

func (Namespace) ValidateForBlob added in v0.11.0 

func (n Namespace) ValidateForBlob() error

ValidateForBlob checks if the Namespace is valid blob namespace.

func (Namespace) ValidateForData added in v0.11.0 

func (n Namespace) ValidateForData() error

ValidateForData checks if the Namespace is of real/useful data.

func (Namespace) Version added in v0.11.0 

func (n Namespace) Version() byte

Version reports version of the Namespace.

type NamespacedRow added in v0.6.2 

type NamespacedRow struct {
	Shares []Share    `json:"shares"`
	Proof  *nmt.Proof `json:"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, namespace Namespace) 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 the empty block EDS.

func NewRoot added in v0.11.0 

func NewRoot(eds *rsmt2d.ExtendedDataSquare) (*Root, error)

NewRoot generates Root(DataAvailabilityHeader) using the provided extended data 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 EmptyBlockShares added in v0.11.0 

func EmptyBlockShares() []Share

EmptyBlockShares returns the shares of the empty block.

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