Struct NsTable

pub struct NsTable {
    pub(crate) bytes: Vec<u8>,
}

Raw binary data for a namespace table.

Any sequence of bytes is a valid NsTable.

Binary format of a namespace table

Byte lengths for the different items that could appear in a namespace table are specified in local private constants NUM_NSS_BYTE_LEN, NS_OFFSET_BYTE_LEN, NS_ID_BYTE_LEN.

Number of entries in the namespace table

The first NUM_NSS_BYTE_LEN bytes of the namespace table indicate the number n of entries in the table as a little-endian unsigned integer. If the entire table length is smaller than NUM_NSS_BYTE_LEN then the missing bytes are zero-padded.

The bytes in the namespace table beyond the first NUM_NSS_BYTE_LEN bytes encode table entries. Each entry consumes exactly NS_ID_BYTE_LEN + NS_OFFSET_BYTE_LEN bytes.

The number n could be anything, including a number much larger than the number of entries that could fit in the namespace table. As such, the actual number of entries in the table is defined as the minimum of n and the maximum number of whole entries that could fit in the table.

See Self::in_bounds for clarification.

Namespace table entry

Namespace ID

The first NS_ID_BYTE_LEN bytes of each table entry indicate the [NamespaceId] for this namespace. Any table entry whose [NamespaceId] is a duplicate of a previous entry is ignored. A correct count of the number of unique (non-ignored) entries is given by NsTable::iter().count().

Namespace offset

The next NS_OFFSET_BYTE_LEN bytes of each table entry indicate the end-index of a namespace in the block payload bytes Payload. This end-index is a little-endian unsigned integer.

How to deduce a namespace’s byte range

In order to extract the payload bytes of a single namespace N from the block payload one needs both the start- and end-indices for N.

See Self::ns_range for clarification. What follows is a description of what’s implemented in Self::ns_range.

If N occupies the ith entry in the namespace table for i>0 then the start-index for N is defined as the end-index of the (i-1)th entry in the table.

Even if the (i-1)the entry would otherwise be ignored (due to a duplicate [NamespaceId] or any other reason), that entry’s end-index still defines the start-index of N. This rule guarantees that both start- and end-indices for any namespace N can be read from a constant-size byte range in the namespace table, and it eliminates the need to traverse an unbounded number of previous entries of the namespace table looking for a previous non-ignored entry.

The start-index of the 0th entry in the table is implicitly defined to be 0.

The start- and end-indices (declared_start, declared_end) declared in the namespace table could be anything. As such, the actual start- and end-indices (start, end) are defined so as to ensure that the byte range is well-defined and in-bounds for the block payload:

end = min(declared_end, block_payload_byte_length)
start = min(declared_start, end)

In a “honestly-prepared” namespace table the end-index of the final namespace equals the byte length of the block payload. (Otherwise the block payload might have bytes that are not included in any namespace.)

It is possible that a namespace table could indicate two distinct namespaces whose byte ranges overlap, though no “honestly-prepared” namespace table would do this.

TODO prefer NsTable to be a newtype like this

#[repr(transparent)]
#[derive(Clone, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
#[serde(transparent)]
pub struct NsTable(#[serde(with = "base64_bytes")] Vec<u8>);

but we need to maintain serialization compatibility. https://github.com/EspressoSystems/espresso-sequencer/issues/1575

Fields

bytes: Vec<u8>

Implementations

impl NsTable

pub fn find_ns_id(&self, ns_id: &NamespaceId) -> Option<NsIndex>

Search the namespace table for the ns_index belonging to ns_id.

pub fn len(&self) -> NumNss

Number of entries in the namespace table.

Defined as the maximum number of entries that could fit in the namespace table, ignoring what’s declared in the table header.

pub fn iter(&self) -> impl Iterator<Item = NsIndex> + '_

Iterator over all unique namespaces in the namespace table.

pub fn read_ns_id(&self, index: &NsIndex) -> Option<NamespaceId>

Read the namespace id from the indexth entry from the namespace table. Returns None if index is out of bounds.

TODO I want to restrict visibility to pub(crate) or lower but this method is currently used in nasty-client.

pub fn read_ns_id_unchecked(&self, index: &NsIndex) -> NamespaceId

Like Self::read_ns_id except index is not checked. Use Self::in_bounds as needed.

pub fn in_bounds(&self, index: &NsIndex) -> bool

Does the indexth entry exist in the namespace table?

pub fn from_bytes_unchecked(bytes: &[u8]) -> NsTable

Instantiate an NsTable from a byte slice.

pub fn validate( &self, payload_byte_len: &PayloadByteLen, ) -> Result<(), NsTableValidationError>

Are the bytes of this NsTable uncorrupted?

Checks

1. Byte length must hold a whole number of entries.
2. All offsets must increase monotonically. Offsets must be nonzero. Namespace IDs must be unique.
3. Header consistent with byte length. (Obsolete after https://github.com/EspressoSystems/espresso-sequencer/issues/1604.)
4. Final offset must equal payload_byte_len. (Obsolete after https://github.com/EspressoSystems/espresso-sequencer/issues/1604.) If the namespace table is empty then payload_byte_len must be 0.

pub fn ns_range( &self, index: &NsIndex, payload_byte_len: &PayloadByteLen, ) -> NsPayloadRange

Read subslice range for the indexth namespace from the namespace table.

fn read_num_nss(&self) -> usize

Read the number of namespaces declared in the namespace table. THIS QUANTITY IS NEVER USED. Instead use NsTable::len.

TODO Delete this method after https://github.com/EspressoSystems/espresso-sequencer/issues/1604

fn read_ns_offset_unchecked(&self, index: &NsIndex) -> usize

Read the namespace offset from the indexth entry from the namespace table.

fn validate_deserialization_invariants( &self, ) -> Result<(), NsTableValidationError>

Helper for NsTable::validate, used in our custom serde implementation.

Checks conditions 1-3 of NsTable::validate. Those conditions can be checked by looking only at the contents of the NsTable.

impl<'de> NsTable

pub fn deserialize<__D>(__deserializer: __D) -> Result<NsTable, __D::Error>

where __D: Deserializer<'de>,

impl NsTable

pub fn serialize<__S>( __self: &NsTable, __serializer: __S, ) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Trait Implementations

impl Clone for NsTable

fn clone(&self) -> NsTable

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Committable for NsTable

fn commit(&self) -> Commitment<Self>

Create a binding commitment to self.

fn tag() -> String

Tag that should be used when serializing commitments to this type.

impl Debug for NsTable

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for NsTable

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl EncodeBytes for NsTable

fn encode(&self) -> Arc<[u8]>

Encode &self

impl Hash for NsTable

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for NsTable

fn eq(&self, other: &NsTable) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for NsTable

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for NsTable

impl StructuralPartialEq for NsTable