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 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 EmptyExtendedDataSquare() *rsmt2d.ExtendedDataSquare
• func GetData(s Share) []byte
• type Availability
• type DataHash
  • func MustDataHashFromString(datahash string) DataHash
  • func (dh DataHash) IsEmptyRoot() bool
  • func (dh DataHash) String() string
  • func (dh DataHash) Validate() error
• type Getter
• type Namespace
  • func GetNamespace(s Share) Namespace
  • func NamespaceFromBytes(b []byte) (Namespace, error)
  • func NewBlobNamespaceV0(id []byte) (Namespace, error)
  • func (n Namespace) Equals(target Namespace) bool
  • func (n Namespace) ID() namespace.ID
  • func (n Namespace) IsAboveMax(nodeHash []byte) bool
  • func (n Namespace) IsBelowMin(nodeHash []byte) bool
  • func (n Namespace) IsGreater(target Namespace) bool
  • func (n Namespace) IsGreaterOrEqualThan(target Namespace) bool
  • func (n Namespace) IsLess(target Namespace) bool
  • func (n Namespace) IsLessOrEqual(target Namespace) bool
  • func (n Namespace) IsOutsideRange(leftNodeHash, rightNodeHash []byte) bool
  • func (n Namespace) Len() int
  • func (n Namespace) Repeat(t int) []Namespace
  • func (n Namespace) String() string
  • func (n Namespace) ToAppNamespace() appns.Namespace
  • func (n Namespace) ToNMT() namespace.ID
  • func (n Namespace) Validate() error
  • func (n Namespace) ValidateForBlob() error
  • func (n Namespace) ValidateForData() error
  • func (n Namespace) Version() byte
• type NamespacedRow
• type NamespacedShares
  • func (ns NamespacedShares) Flatten() []Share
  • func (ns NamespacedShares) Verify(root *Root, namespace Namespace) error
• type Root
  • func EmptyRoot() *Root
  • func NewRoot(eds *rsmt2d.ExtendedDataSquare) (*Root, error)
• type Share
  • func EmptyBlockShares() []Share

Constants

const NamespaceSize = appns.NamespaceSize

NamespaceSize is a system-wide size for NMT namespaces.

const (
	// Size is a system-wide size of a share, including both data and namespace GetNamespace
	Size = appconsts.ShareSize
)

Variables

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

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.

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.

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

Functions

func EmptyExtendedDataSquare

func EmptyExtendedDataSquare() *rsmt2d.ExtendedDataSquare

EmptyExtendedDataSquare returns the EDS of the empty block data square.

func GetData

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

type DataHash []byte

DataHash is a representation of the Root hash.

func MustDataHashFromString

func MustDataHashFromString(datahash string) DataHash

MustDataHashFromString converts a hex string to a valid datahash.

func (DataHash) IsEmptyRoot

func (dh DataHash) IsEmptyRoot() bool

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

func (DataHash) String

func (dh DataHash) String() string

func (DataHash) Validate

func (dh DataHash) Validate() error

type Getter

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

type Namespace []byte

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

func GetNamespace

func GetNamespace(s Share) Namespace

GetNamespace slices Namespace out of the Share.

func NamespaceFromBytes

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

NamespaceFromBytes converts bytes into Namespace and validates it.

func NewBlobNamespaceV0

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

func (n Namespace) Equals(target Namespace) bool

Equals compares two Namespaces.

func (Namespace) ID

func (n Namespace) ID() namespace.ID

ID reports ID of the Namespace.

func (Namespace) IsAboveMax

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

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

func (Namespace) IsBelowMin

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

func (n Namespace) IsGreater(target Namespace) bool

IsGreater reports if the Namespace is greater than the target.

func (Namespace) IsGreaterOrEqualThan

func (n Namespace) IsGreaterOrEqualThan(target Namespace) bool

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

func (Namespace) IsLess

func (n Namespace) IsLess(target Namespace) bool

IsLess reports if the Namespace is less than the target.

func (Namespace) IsLessOrEqual

func (n Namespace) IsLessOrEqual(target Namespace) bool

IsLessOrEqual reports if the Namespace is less than the target.

func (Namespace) IsOutsideRange

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

func (n Namespace) Len() int

Len reports the total length of the namespace.

func (Namespace) Repeat

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

Repeat copies the Namespace t times.

func (Namespace) String

func (n Namespace) String() string

String stringifies the Namespace.

func (Namespace) ToAppNamespace

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

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

func (n Namespace) Validate() error

Validate checks if the namespace is correct.

func (Namespace) ValidateForBlob

func (n Namespace) ValidateForBlob() error

ValidateForBlob checks if the Namespace is valid blob namespace.

func (Namespace) ValidateForData

func (n Namespace) ValidateForData() error

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

func (Namespace) Version

func (n Namespace) Version() byte

Version reports version of the Namespace.

type NamespacedRow

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

type NamespacedShares []NamespacedRow

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

func (NamespacedShares) Flatten

func (ns NamespacedShares) Flatten() []Share

Flatten returns the concatenated slice of all NamespacedRow shares.

func (NamespacedShares) Verify

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

func EmptyRoot() *Root

EmptyRoot returns Root of the empty block EDS.

func NewRoot

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

func EmptyBlockShares() []Share

EmptyBlockShares returns the shares of the empty block.