Documentation ¶
Overview ¶
Package shares provides primitives for splitting block data into shares and parsing shares back into block data.
Compact vs. Sparse ¶
There are two types of shares:
- Compact
- Sparse
Compact shares can contain data from one or more unit (transactions or intermediate state roots). Sparse shares can contain data from zero or one blob. Compact shares and sparse shares are encoded differently. The motivation behind the distinction is that transactions and intermediate state roots are expected to have small lengths so they are encoded in compact shares to minimize the number of shares needed to store them. On the other hand, blobs are expected to be larger and have the desideratum that clients should be able to create proofs of blob inclusion. This desiradum is infeasible if client A's blob is encoded into a share with another client B's blob that is unknown to A. It follows that client A's blob is encoded into a share such that the contents can be determined by client A without any additional information. See message layout rational or adr-006-non-interactive-defaults for more details.
Universal Prefix ¶
Both types of shares have a universal prefix. The first 1 byte of a share contains the namespace version. The next 32 bytes contain the namespace ID. The next one byte contains an InfoByte that contains the share version and a sequence start indicator. If the sequence start indicator is `1` (i.e. this is the first share of a sequence) then the next 4 bytes contain a big endian uint32 of the sequence length.
For the first share of a sequence:
| namespace_version | namespace_id | info_byte | sequence_length | sequence_data | | 1 byte | 32 bytes | 1 byte | 4 bytes | remaining bytes of share |
For continuation share of a sequence:
| namespace_version | namespace_id | info_byte | sequence_data | | 1 byte | 32 bytes | 1 byte | remaining bytes of share |
The remaining bytes depend on the share type.
Compact Share Schema ¶
The four bytes after the universal prefix are reserved for the location in the share of the first unit of data that starts in this share.
For the first compact share:
| namespace_version | namespace_id | info_byte | sequence_length | location_of_first_unit | transactions or intermediate state roots | | 1 byte | 32 bytes | 1 byte | 4 bytes | 4 bytes | remaining bytes of share |
For continuation compact share:
| namespace_version | namespace_id | info_byte | location_of_first_unit | transactions or intermediate state roots | | 1 byte | 32 bytes | 1 byte | 4 bytes | remaining bytes of share |
Notes
- All shares in a reserved namespace belong to one sequence.
- Each unit (transaction or intermediate state root) in data is prefixed with a varint of the length of the unit.
Sparse Share Schema ¶
The remaining bytes contain blob data.
Index ¶
- func CompactSharesNeeded(sequenceLen int) (sharesNeeded int)
- func DelimLen(size uint64) int
- func MarshalDelimitedTx(tx coretypes.Tx) ([]byte, error)
- func NewReservedBytes(byteIndex uint32) ([]byte, error)
- func ParseDelimiter(input []byte) (inputWithoutLenDelimiter []byte, unitLen uint64, err error)
- func ParseReservedBytes(reservedBytes []byte) (uint32, error)
- func SparseSharesNeeded(sequenceLen uint32) (sharesNeeded int)
- func ToBytes(shares []Share) (bytes [][]byte)
- func TxsFromBytes(txs [][]byte) coretypes.Txs
- func TxsToBytes(txs coretypes.Txs) [][]byte
- type Builder
- func (b *Builder) AddData(rawData []byte) (rawDataLeftOver []byte)
- func (b *Builder) AvailableBytes() int
- func (b *Builder) Build() (*Share, error)
- func (b *Builder) FlipSequenceStart()
- func (b *Builder) ImportRawShare(rawBytes []byte) *Builder
- func (b *Builder) Init() (*Builder, error)
- func (b *Builder) IsEmptyShare() bool
- func (b *Builder) MaybeWriteReservedBytes() error
- func (b *Builder) WriteSequenceLen(sequenceLen uint32) error
- func (b *Builder) ZeroPadIfNecessary() (bytesOfPadding int)
- type CompactShareSplitter
- type InfoByte
- type Share
- func (s *Share) DoesSupportVersions(supportedShareVersions []uint8) error
- func (s *Share) InfoByte() (InfoByte, error)
- func (s Share) IsCompactShare() (bool, error)
- func (s *Share) IsPadding() (bool, error)
- func (s *Share) IsSequenceStart() (bool, error)
- func (s *Share) Len() int
- func (s *Share) Namespace() (appns.Namespace, error)
- func (s *Share) RawData() (rawData []byte, err error)
- func (s *Share) SequenceLen() (sequenceLen uint32, err error)
- func (s *Share) ToBytes() []byte
- func (s *Share) Validate() error
- func (s *Share) Version() (uint8, error)
- type ShareRange
- type ShareSequence
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CompactSharesNeeded ¶
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 MarshalDelimitedTx ¶
MarshalDelimitedTx prefixes a transaction with the length of the transaction encoded as a varint.
func NewReservedBytes ¶
NewReservedBytes returns a byte slice of length appconsts.CompactShareReservedBytes that contains the byteIndex of the first unit that starts in a compact share.
func ParseDelimiter ¶
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 ¶
ParseReservedBytes parses a byte slice of length appconsts.CompactShareReservedBytes into a byteIndex.
func SparseSharesNeeded ¶
SparseSharesNeeded returns the number of shares needed to store a sequence of length sequenceLen.
func TxsFromBytes ¶
func TxsToBytes ¶
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
func NewBuilder ¶
Init() needs to be called right after this method
func NewEmptyBuilder ¶
func NewEmptyBuilder() *Builder
func (*Builder) AvailableBytes ¶
func (*Builder) FlipSequenceStart ¶
func (b *Builder) FlipSequenceStart()
FlipSequenceStart flips the sequence start indicator of the share provided
func (*Builder) ImportRawShare ¶
func (*Builder) IsEmptyShare ¶
IsEmptyShare returns true if no data has been written to the share
func (*Builder) MaybeWriteReservedBytes ¶
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 ¶
writeSequenceLen writes the sequence length to the first share.
func (*Builder) ZeroPadIfNecessary ¶
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() (shareCount 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(shareRangeOffset int) ([]Share, map[coretypes.TxKey]ShareRange, error)
Export finalizes and returns the underlying compact shares and a map of shareRanges. 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).
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 ParseInfoByte ¶
func (InfoByte) IsSequenceStart ¶
IsSequenceStart returns whether this share is the start of a sequence.
type Share ¶
type Share struct {
// contains filtered or unexported fields
}
Share contains the raw share data (including namespace ID).
func (*Share) DoesSupportVersions ¶
func (Share) IsCompactShare ¶
IsCompactShare returns true if this is a compact share.
func (*Share) IsSequenceStart ¶
IsSequenceStart returns true if this is the first share in a sequence.
func (*Share) RawData ¶
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) SequenceLen ¶
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).
type ShareRange ¶
type ShareSequence ¶
type ShareSequence struct {}
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 (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)