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.ID from the block associated with the given DataAvailabilityHeader (DAH, but referred to as Root within this package).

This package also contains both implementations of the Availability interface: lightAvailability which samples for 16 shares of block data (enough to verify the block's availability on the network) and fullAvailability which samples for as many shares as necessary to fully reconstruct the block data.

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

Index

• Constants
• Variables
• func EnsureEmptySquareExists(ctx context.Context, dag format.DAGService) error
• func RandFullServiceWithSquare(t *testing.T, n int) (*Service, *Root)
• func RandLightServiceWithSquare(t *testing.T, n int) (*Service, *Root)
• type Availability
  • func NewBrokenAvailability() Availability
  • func NewFullAvailability(dag format.DAGService) Availability
  • func NewLightAvailability(get format.NodeGetter) Availability
• type DAGNet
  • func NewDAGNet(ctx context.Context, t *testing.T) *DAGNet
  • func (dn *DAGNet) CleanDAG() format.DAGService
  • func (dn *DAGNet) CleanService() *Service
  • func (dn *DAGNet) ConnectAll()
  • func (dn *DAGNet) RandDAG(n int) (format.DAGService, *Root)
  • func (dn *DAGNet) RandFullService(n int) (*Service, *Root)
  • func (dn *DAGNet) RandLightService(n int) (*Service, *Root)
• type Root
  • func FillDag(t *testing.T, dag format.DAGService, shares []Share) *Root
  • func RandFillDAG(t *testing.T, n int, dag format.DAGService) *Root
• type Sample
  • func SampleSquare(squareWidth int, num int) ([]Sample, error)
• type Service
  • func NewService(dag format.DAGService, avail Availability) *Service
  • func RandLightService() (*Service, format.DAGService)
  • func (s *Service) GetShare(ctx context.Context, dah *Root, row, col int) (Share, error)
  • func (s *Service) GetShares(ctx context.Context, root *Root) ([][]Share, error)
  • func (s *Service) GetSharesByNamespace(ctx context.Context, root *Root, nID namespace.ID) ([]Share, error)
  • func (s *Service) Start(context.Context) error
  • func (s *Service) Stop(context.Context) error
• type Share
  • func RandShares(t *testing.T, n int) []Share

Constants

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

var DefaultSampleAmount = 16

DefaultSampleAmount sets the default amount of samples to be sampled from the network by lightAvailability.

var ErrNotAvailable = errors.New("da: data not available")

ErrNotAvailable is returned whenever DA sampling fails.

var GetData = ipld.ShareData

GetData extracts data out of a Share.

var GetID = ipld.ShareID

GetID extracts namespace ID out of a Share.

Functions

func EnsureEmptySquareExists

func EnsureEmptySquareExists(ctx context.Context, dag format.DAGService) 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 RandFullServiceWithSquare

func RandFullServiceWithSquare(t *testing.T, n int) (*Service, *Root)

RandFullServiceWithSquare provides a share.Service filled with 'n' NMT trees of 'n' random shares, essentially storing a whole square.

func RandLightServiceWithSquare

func RandLightServiceWithSquare(t *testing.T, n int) (*Service, *Root)

RandLightServiceWithSquare provides a share.Service filled with 'n' NMT trees of 'n' random shares, essentially storing a whole 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
}

Availability defines interface for validation of Shares' availability.

func NewBrokenAvailability

func NewBrokenAvailability() Availability

func NewFullAvailability

func NewFullAvailability(dag format.DAGService) Availability

NewFullAvailability creates a new full Availability.

func NewLightAvailability

func NewLightAvailability(get format.NodeGetter) Availability

NewLightAvailability creates a new light Availability.

type DAGNet

type DAGNet struct {
	// contains filtered or unexported fields
}

func NewDAGNet

func NewDAGNet(ctx context.Context, t *testing.T) *DAGNet

func (*DAGNet) CleanDAG

func (dn *DAGNet) CleanDAG() format.DAGService

func (*DAGNet) CleanService

func (dn *DAGNet) CleanService() *Service

func (*DAGNet) ConnectAll

func (dn *DAGNet) ConnectAll()

func (*DAGNet) RandDAG

func (dn *DAGNet) RandDAG(n int) (format.DAGService, *Root)

func (*DAGNet) RandFullService

func (dn *DAGNet) RandFullService(n int) (*Service, *Root)

func (*DAGNet) RandLightService

func (dn *DAGNet) RandLightService(n int) (*Service, *Root)

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 FillDag

func FillDag(t *testing.T, dag format.DAGService, shares []Share) *Root

func RandFillDAG

func RandFillDAG(t *testing.T, n int, dag format.DAGService) *Root

type Sample

type Sample struct {
	Row, Col int
}

Sample is a point in 2D space over square.

func SampleSquare

func SampleSquare(squareWidth int, num int) ([]Sample, error)

SampleSquare randomly picks *num* unique points from the given *width* square and returns them as samples.

type Service

type Service struct {
	Availability
	// contains filtered or unexported fields
}

Service provides access to any data square or block share on the network.

All Get methods provided on Service follow the following flow:

• Check local storage for the requested Share.
• If exists
• Load from disk
• Return
• If not
• Find provider on the network
• Fetch the Share from the provider
• Store the Share
• Return

TODO(@Wondertan): Simple thread safety for Start and Stop would not hurt.

func NewService

func NewService(dag format.DAGService, avail Availability) *Service

NewService creates new basic share.Service.

func RandLightService

func RandLightService() (*Service, format.DAGService)

RandLightService provides an unfilled share.Service with corresponding format.DAGService than can be filled by the test.

func (*Service) GetShare

func (s *Service) GetShare(ctx context.Context, dah *Root, row, col int) (Share, error)

func (*Service) GetShares

func (s *Service) GetShares(ctx context.Context, root *Root) ([][]Share, error)

func (*Service) GetSharesByNamespace

func (s *Service) GetSharesByNamespace(ctx context.Context, root *Root, nID namespace.ID) ([]Share, error)

func (*Service) Start

func (s *Service) Start(context.Context) error

func (*Service) Stop

func (s *Service) Stop(context.Context) error

type Share

type Share = ipld.Share

Share is a fixed-size data chunk associated with a namespace ID, whose data will be erasure-coded and committed to in Namespace Merkle trees.

func RandShares

func RandShares(t *testing.T, n int) []Share

RandShares provides 'n' randomized shares prefixed with random namespaces.