shares

package
v0.0.0-...-4ef5390 Latest Latest
Warning

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

Go to latest
Published: Sep 5, 2024 License: Apache-2.0 Imports: 11 Imported by: 0

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

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

func AvailableBytesFromSparseShares(n int) int

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

func BlobMinSquareSize

func BlobMinSquareSize(shareCount int) int

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

func BlobSharesUsedNonInteractiveDefaults

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

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

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

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

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

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

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

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

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

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

func RoundUpPowerOfTwo

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

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

func RoundUpPowerOfTwoStrict

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

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

func SparseSharesNeeded

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

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

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

func NewBuilder

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

Init() needs to be called right after this method

func NewEmptyBuilder

func NewEmptyBuilder() *Builder

func (*Builder) AddData

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

func (*Builder) AvailableBytes

func (b *Builder) AvailableBytes() int

func (*Builder) Build

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

func (*Builder) FlipSequenceStart

func (b *Builder) FlipSequenceStart()

FlipSequenceStart flips the sequence start indicator of the share provided

func (*Builder) ImportRawShare

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

func (*Builder) Init

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

func (*Builder) IsEmptyShare

func (b *Builder) IsEmptyShare() bool

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

func (*Builder) MaybeWriteReservedBytes

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

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

writeSequenceLen writes the sequence length to the first share.

func (*Builder) ZeroPadIfNecessary

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

type CompactShareCounter

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

func NewCompactShareCounter

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

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

func (c *CompactShareCounter) Remainder() int

func (*CompactShareCounter) Revert

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

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

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

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

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

func EmptyRange() Range

func GetShareRangeForNamespace

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

func NewRange(start, end int) Range

func (*Range) Add

func (r *Range) Add(value int)

func (Range) IsEmpty

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

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

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

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

func ReservedPaddingShares(n int) []Share

ReservedPaddingShare returns n reserved padding shares.

func SplitBlobs

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

SplitBlobs splits the provided blobs into shares.

func TailPaddingShare

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

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

func (*Share) InfoByte

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

func (Share) IsCompactShare

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

IsCompactShare returns true if this is a compact share.

func (*Share) IsPadding

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

IsPadding returns whether this *share is padding or not.

func (*Share) IsSequenceStart

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

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

func (*Share) Len

func (s *Share) Len() int

func (*Share) Namespace

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

func (*Share) RawData

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

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

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

func (*Share) SequenceLen

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

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

func (*Share) Validate

func (s *Share) Validate() error

func (*Share) Version

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

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

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

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL