shares

package
v1.7.0-rc0 Latest Latest
Warning

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

 Go to latest Published: Mar 1, 2024 License: Apache-2.0 Imports: 11 Imported by: 3

README

Shares

See the specs for shares.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrIncorrectNumberOfIndexes = errors.New(
		"number of indexes is not identical to the number of blobs",
	)
	ErrUnexpectedFirstBlobShareIndex = errors.New(
		"the first blob started at an unexpected index",
	)
)

Functions

func AvailableBytesFromCompactShares added in v1.0.0 

func AvailableBytesFromCompactShares(n int) int

AvailableBytesFromCompactShares returns the maximum amount of bytes that could fit in `n` compact shares. Note that all compact shares are length prefixed. To account for this use `RawTxSize`.

func AvailableBytesFromSparseShares added in v1.0.0 

func AvailableBytesFromSparseShares(n int) int

AvailableBytesFromSparseShares returns the maximum amount of bytes that could fit in `n` sparse shares

func BlobMinSquareSize added in v1.0.0 

func BlobMinSquareSize(shareCount int) int

BlobMinSquareSize returns the minimum square size that can contain shareCount number of shares.

func BlobSharesUsedNonInteractiveDefaults added in v0.12.0 

func BlobSharesUsedNonInteractiveDefaults(cursor, subtreeRootThreshold int, blobShareLens ...int) (sharesUsed int, indexes []uint32)

BlobSharesUsedNonInteractiveDefaults returns the number of shares used by a given set of blobs share lengths. It follows the blob share commitment rules and returns the share indexes for each blob.

func CompactSharesNeeded added in v0.12.0 

func CompactSharesNeeded(sequenceLen int) (sharesNeeded int)

CompactSharesNeeded returns the number of compact shares needed to store a sequence of length sequenceLen. The parameter sequenceLen is the number of bytes of transactions or intermediate state roots in a sequence.

func DelimLen 

func DelimLen(size uint64) int

DelimLen calculates the length of the delimiter for a given unit size

func ExtractShareIndexes 

func ExtractShareIndexes(txs coretypes.Txs) []uint32

ExtractShareIndexes iterates over the transactions and extracts the share indexes from wrapped transactions. It returns nil if the transactions are from an old block that did not have share indexes in the wrapped txs.

func FitsInSquare 

func FitsInSquare(cursor, squareSize, subtreeRootThreshold int, blobShareLens ...int) (bool, int)

FitsInSquare uses the non interactive default rules to see if blobs of some lengths will fit in a square of squareSize starting at share index cursor. Returns whether the blobs fit in the square and the number of shares used by blobs. See ADR-013 and the blob share commitment rules.

../../specs/src/specs/data_square_layout.md#blob-share-commitment-rules

func IsPowerOfTwo added in v0.9.0 

func IsPowerOfTwo[I constraints.Integer](input I) bool

IsPowerOfTwo returns true if input is a power of two.

func MarshalDelimitedTx 

func MarshalDelimitedTx(tx coretypes.Tx) ([]byte, error)

MarshalDelimitedTx prefixes a transaction with the length of the transaction encoded as a varint.

func NewReservedBytes added in v0.8.0 

func NewReservedBytes(byteIndex uint32) ([]byte, error)

NewReservedBytes returns a byte slice of length appconsts.CompactShareReservedBytes that contains the byteIndex of the first unit that starts in a compact share.

func NextShareIndex added in v1.0.0 

func NextShareIndex(cursor, blobShareLen, subtreeRootThreshold int) int

NextShareIndex determines the next index in a square that can be used. It follows the blob share commitment rules defined in ADR-013. Assumes that all args are non negative, that squareSize is a power of two and that the blob can fit in the square. The cursor is expected to be the index after the end of the previous blob.

See https://github.com/celestiaorg/celestia-app/blob/main/specs/src/specs/data_square_layout.md for more information.

func ParseBlobs added in v0.12.0 

func ParseBlobs(shares []Share) ([]coretypes.Blob, error)

ParseBlobs collects all blobs from the shares provided

func ParseDelimiter 

func ParseDelimiter(input []byte) (inputWithoutLenDelimiter []byte, unitLen uint64, err error)

ParseDelimiter attempts to parse a varint length delimiter from the input provided. It returns the input without the len delimiter bytes, the length parsed from the varint optionally an error. Unit length delimiters are used in compact shares where units (i.e. a transaction) are prefixed with a length delimiter that is encoded as a varint. Input should not contain the namespace ID or info byte of a share.

func ParseReservedBytes added in v0.8.0 

func ParseReservedBytes(reservedBytes []byte) (uint32, error)

ParseReservedBytes parses a byte slice of length appconsts.CompactShareReservedBytes into a byteIndex.

func ParseTxs 

func ParseTxs(shares []Share) (coretypes.Txs, error)

ParseTxs collects all of the transactions from the shares provided

func RawTxSize added in v1.0.0 

func RawTxSize(desiredSize int) int

RawTxSize returns the raw tx size that can be used to construct a tx of desiredSize bytes. This function is useful in tests to account for the length delimiter that is prefixed to a tx when it is converted into a compact share

func RoundDownPowerOfTwo added in v0.9.0 

func RoundDownPowerOfTwo[I constraints.Integer](input I) (I, error)

RoundDownPowerOfTwo returns the next power of two less than or equal to input.

func RoundUpPowerOfTwo added in v0.9.0 

func RoundUpPowerOfTwo[I constraints.Integer](input I) I

RoundUpPowerOfTwo returns the next power of two greater than or equal to input.

func RoundUpPowerOfTwoStrict added in v0.9.0 

func RoundUpPowerOfTwoStrict[I constraints.Integer](input I) I

RoundUpPowerOfTwo returns the next power of two that is strictly greater than input.

func SparseSharesNeeded added in v0.12.0 

func SparseSharesNeeded(sequenceLen uint32) (sharesNeeded int)

SparseSharesNeeded returns the number of shares needed to store a sequence of length sequenceLen.

func SplitTxs 

func SplitTxs(txs coretypes.Txs) (txShares []Share, pfbShares []Share, shareRanges map[coretypes.TxKey]Range, err error)

func SubTreeWidth added in v1.0.0 

func SubTreeWidth(shareCount, subtreeRootThreshold int) int

SubTreeWidth determines the maximum number of leaves per subtree in the share commitment over a given blob. The input should be the total number of shares used by that blob. The reasoning behind this algorithm is discussed in depth in ADR013 (celestia-app/docs/architecture/adr-013-non-interative-default-rules-for-zero-padding).

func ToBytes 

func ToBytes(shares []Share) (bytes [][]byte)

Types

type Builder added in v1.0.0 

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

func NewBuilder added in v1.0.0 

func NewBuilder(ns appns.Namespace, shareVersion uint8, isFirstShare bool) *Builder

Init() needs to be called right after this method

func NewEmptyBuilder added in v1.0.0 

func NewEmptyBuilder() *Builder

func (*Builder) AddData added in v1.0.0 

func (b *Builder) AddData(rawData []byte) (rawDataLeftOver []byte)

func (*Builder) AvailableBytes added in v1.0.0 

func (b *Builder) AvailableBytes() int

func (*Builder) Build added in v1.0.0 

func (b *Builder) Build() (*Share, error)

func (*Builder) FlipSequenceStart added in v1.0.0 

func (b *Builder) FlipSequenceStart()

FlipSequenceStart flips the sequence start indicator of the share provided

func (*Builder) ImportRawShare added in v1.0.0 

func (b *Builder) ImportRawShare(rawBytes []byte) *Builder

func (*Builder) Init added in v1.0.0 

func (b *Builder) Init() (*Builder, error)

func (*Builder) IsEmptyShare added in v1.0.0 

func (b *Builder) IsEmptyShare() bool

IsEmptyShare returns true if no data has been written to the share

func (*Builder) MaybeWriteReservedBytes added in v1.0.0 

func (b *Builder) MaybeWriteReservedBytes() error

MaybeWriteReservedBytes will be a no-op if the reserved bytes have already been populated. If the reserved bytes are empty, it will write the location of the next unit of data to the reserved bytes.

func (*Builder) WriteSequenceLen added in v1.0.0 

func (b *Builder) WriteSequenceLen(sequenceLen uint32) error

writeSequenceLen writes the sequence length to the first share.

func (*Builder) ZeroPadIfNecessary added in v1.0.0 

func (b *Builder) ZeroPadIfNecessary() (bytesOfPadding int)

type CompactShareCounter added in v1.0.0 

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

func NewCompactShareCounter added in v1.0.0 

func NewCompactShareCounter() *CompactShareCounter

NewCompactShareCounter creates a new instance of a counter which calculates the amount of compact shares a set of data will be split into.

func (*CompactShareCounter) Add added in v1.0.0 

func (c *CompactShareCounter) Add(dataLen int) int

Add adds the length of the data to the counter and returns the amount of shares the counter has been increased by.

func (*CompactShareCounter) Remainder added in v1.0.0 

func (c *CompactShareCounter) Remainder() int

func (*CompactShareCounter) Revert added in v1.0.0 

func (c *CompactShareCounter) Revert()

Revert reverts the last Add operation. This can be called multiple times but only works the first time after an add operation.

func (*CompactShareCounter) Size added in v1.0.0 

func (c *CompactShareCounter) Size() int

Size returns the amount of shares the compact share counter has counted.

type CompactShareSplitter 

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

CompactShareSplitter will write raw data compactly across a progressively increasing set of shares. It is used to lazily split block data such as transactions or intermediate state roots into shares.

func NewCompactShareSplitter 

func NewCompactShareSplitter(ns appns.Namespace, shareVersion uint8) *CompactShareSplitter

NewCompactShareSplitter returns a CompactShareSplitter using the provided namespace and shareVersion.

func (*CompactShareSplitter) Count 

func (css *CompactShareSplitter) Count() int

Count returns the number of shares that would be made if `Export` was invoked on this compact share splitter.

func (*CompactShareSplitter) Export 

func (css *CompactShareSplitter) Export() ([]Share, error)

Export returns the underlying compact shares

func (*CompactShareSplitter) ShareRanges added in v1.0.0 

func (css *CompactShareSplitter) ShareRanges(shareRangeOffset int) map[coretypes.TxKey]Range

ShareRanges returns a map of share ranges to the corresponding tx keys. All share ranges in the map of shareRanges will be offset (i.e. incremented) by the shareRangeOffset provided. shareRangeOffset should be 0 for the first compact share sequence in the data square (transactions) but should be some non-zero number for subsequent compact share sequences (e.g. pfb txs).

func (*CompactShareSplitter) WriteTx 

func (css *CompactShareSplitter) WriteTx(tx coretypes.Tx) error

WriteTx adds the delimited data for the provided tx to the underlying compact share splitter.

type InfoByte 

type InfoByte byte

InfoByte is a byte with the following structure: the first 7 bits are reserved for version information in big endian form (initially `0000000`). The last bit is a "sequence start indicator", that is `1` if this is the first share of a sequence and `0` if this is a continuation share.

func NewInfoByte 

func NewInfoByte(version uint8, isSequenceStart bool) (InfoByte, error)

func ParseInfoByte 

func ParseInfoByte(i byte) (InfoByte, error)

func (InfoByte) IsSequenceStart added in v0.8.0 

func (i InfoByte) IsSequenceStart() bool

IsSequenceStart returns whether this share is the start of a sequence.

func (InfoByte) Version 

func (i InfoByte) Version() uint8

Version returns the version encoded in this InfoByte. Version is expected to be between 0 and appconsts.MaxShareVersion (inclusive).

type Range added in v1.0.0 

type Range struct {
	// Start is the index of the first share occupied by this range.
	Start int
	// End is the next index after the last share occupied by this range.
	End int
}

Range is an end exclusive set of share indexes.

func EmptyRange added in v1.0.0 

func EmptyRange() Range

func GetShareRangeForNamespace added in v1.0.0 

func GetShareRangeForNamespace(shares []Share, ns namespace.Namespace) (Range, error)

GetShareRangeForNamespace returns all shares that belong to a given namespace. It will return an empty range if the namespace could not be found. This assumes that the slice of shares are lexicographically sorted by namespace. Ranges here are always end exlusive.

func NewRange added in v1.0.0 

func NewRange(start, end int) Range

func (*Range) Add added in v1.0.0 

func (r *Range) Add(value int)

func (Range) IsEmpty added in v1.0.0 

func (r Range) IsEmpty() bool

type Share 

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

Share contains the raw share data (including namespace ID).

func FromBytes 

func FromBytes(bytes [][]byte) (shares []Share, err error)

func NamespacePaddingShare added in v0.12.0 

func NamespacePaddingShare(ns appns.Namespace, shareVersion uint8) (Share, error)

NamespacePaddingShare returns a share that acts as padding. Namespace padding shares follow a blob so that the next blob may start at an index that conforms to blob share commitment rules. The ns and shareVersion parameters provided should be the namespace and shareVersion of the blob that precedes this padding in the data square.

func NamespacePaddingShares added in v0.12.0 

func NamespacePaddingShares(ns appns.Namespace, shareVersion uint8, n int) ([]Share, error)

NamespacePaddingShares returns n namespace padding shares.

func NewShare 

func NewShare(data []byte) (*Share, error)

func ReservedPaddingShare added in v0.12.0 

func ReservedPaddingShare() Share

ReservedPaddingShare returns a share that acts as padding. Reserved padding shares follow all significant shares in the reserved namespace so that the first blob can start at an index that conforms to non-interactive default rules.

func ReservedPaddingShares added in v0.12.0 

func ReservedPaddingShares(n int) []Share

ReservedPaddingShare returns n reserved padding shares.

func SplitBlobs added in v0.12.0 

func SplitBlobs(blobs ...coretypes.Blob) ([]Share, error)

SplitBlobs splits the provided blobs into shares.

func TailPaddingShare added in v0.12.0 

func TailPaddingShare() Share

TailPaddingShare is a share that is used to pad a data square to the desired square size. Tail padding shares follow the last blob share in the data square.

func TailPaddingShares 

func TailPaddingShares(n int) []Share

TailPaddingShares returns n tail padding shares.

func (*Share) DoesSupportVersions added in v1.0.0 

func (s *Share) DoesSupportVersions(supportedShareVersions []uint8) error

func (*Share) InfoByte 

func (s *Share) InfoByte() (InfoByte, error)

func (Share) IsCompactShare added in v0.12.0 

func (s Share) IsCompactShare() (bool, error)

IsCompactShare returns true if this is a compact share.

func (*Share) IsPadding added in v0.12.0 

func (s *Share) IsPadding() (bool, error)

IsPadding returns whether this *share is padding or not.

func (*Share) IsSequenceStart added in v0.12.0 

func (s *Share) IsSequenceStart() (bool, error)

IsSequenceStart returns true if this is the first share in a sequence.

func (*Share) Len added in v1.0.0 

func (s *Share) Len() int

func (*Share) Namespace added in v1.0.0 

func (s *Share) Namespace() (appns.Namespace, error)

func (*Share) RawData added in v0.11.1 

func (s *Share) RawData() (rawData []byte, err error)

RawData returns the raw share data. The raw share data does not contain the namespace ID, info byte, sequence length, or reserved bytes.

func (*Share) RawDataUsingReserved added in v1.0.0 

func (s *Share) RawDataUsingReserved() (rawData []byte, err error)

RawDataWithReserved returns the raw share data while taking reserved bytes into account.

func (*Share) SequenceLen added in v0.11.1 

func (s *Share) SequenceLen() (sequenceLen uint32, err error)

SequenceLen returns the sequence length of this *share and optionally an error. It returns 0, nil if this is a continuation share (i.e. doesn't contain a sequence length).

func (*Share) ToBytes added in v0.12.0 

func (s *Share) ToBytes() []byte

func (*Share) Validate added in v1.0.0 

func (s *Share) Validate() error

func (*Share) Version added in v0.12.0 

func (s *Share) Version() (uint8, error)

type ShareSequence 

type ShareSequence struct {
	Namespace appns.Namespace
	Shares    []Share
}

ShareSequence represents a contiguous sequence of shares that are part of the same namespace and blob. For compact shares, one share sequence exists per reserved namespace. For sparse shares, one share sequence exists per blob.

func ParseShares 

func ParseShares(shares []Share, ignorePadding bool) ([]ShareSequence, error)

ParseShares parses the shares provided and returns a list of ShareSequences. If ignorePadding is true then the returned ShareSequences will not contain any padding sequences.

func (ShareSequence) RawData added in v0.12.0 

func (s ShareSequence) RawData() (data []byte, err error)

RawData returns the raw share data of this share sequence. The raw data does not contain the namespace ID, info byte, sequence length, or reserved bytes.

func (ShareSequence) SequenceLen added in v0.12.0 

func (s ShareSequence) SequenceLen() (uint32, error)

type SparseShareSplitter 

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

SparseShareSplitter lazily splits blobs into shares that will eventually be included in a data square. It also has methods to help progressively count how many shares the blobs written take up.

func NewSparseShareSplitter 

func NewSparseShareSplitter() *SparseShareSplitter

func (*SparseShareSplitter) Count 

func (sss *SparseShareSplitter) Count() int

Count returns the current number of shares that will be made if exporting.

func (*SparseShareSplitter) Export 

func (sss *SparseShareSplitter) Export() []Share

Export finalizes and returns the underlying shares.

func (*SparseShareSplitter) Write 

func (sss *SparseShareSplitter) Write(blob coretypes.Blob) error

Write writes the provided blob to this sparse share splitter. It returns an error or nil if no error is encountered.

func (*SparseShareSplitter) WriteNamespacePaddingShares added in v1.0.0 

func (sss *SparseShareSplitter) WriteNamespacePaddingShares(count int) error

WriteNamespacePaddingShares adds padding shares with the namespace of the last written share. This is useful to follow the non-interactive default rules. This function assumes that at least one share has already been written.

Source Files

View all Source files

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.