ssz package

Subpackages

Submodules

ssz.abc module

class ssz.abc.HashableStructureAPI(*args, **kwds)

Bases: ABC, Generic[TElement]

abstract property chunks: PVector[Hash32]

abstract property elements: PVector[TElement]

abstract evolver() → HashableStructureEvolverAPI[TStructure, TElement]

abstract classmethod from_iterable_and_sedes(iterable: Iterable[TElement], sedes: BaseProperCompositeSedes, max_length: int | None)

abstract property hash_tree: HashTree

abstract property hash_tree_root: Hash32

abstract mset(*args: int | TElement) → TStructure

abstract property raw_root: Hash32

abstract set(index: int, value: TElement) → TStructure

abstract transform(*transformations)

class ssz.abc.HashableStructureEvolverAPI(hashable_structure: TStructure)

Bases: ABC, Generic[TStructure, TElement]

abstract is_dirty() → bool

abstract persistent() → TStructure

abstract set(index: int, element: TElement) → None

class ssz.abc.ResizableHashableStructureAPI(*args, **kwds)

Bases: HashableStructureAPI[TElement]

abstract append(value: TElement) → TStructure

abstract evolver() → ResizableHashableStructureEvolverAPI[TStructure, TElement]

abstract extend(values: Iterable[TElement]) → TStructure

class ssz.abc.ResizableHashableStructureEvolverAPI(hashable_structure: TStructure)

Bases: HashableStructureEvolverAPI[TStructure, TElement]

abstract append(element: TElement) → None

abstract extend(iterable: Iterable[TElement]) → None

ssz.codec module

ssz.codec.decode(ssz, sedes): Decode a SSZ encoded object.

ssz.codec.encode(value, sedes=None): Encode object in SSZ format. sedes needs to be explicitly mentioned for encode/decode of integers(as of now). sedes parameter could be given as a string or as the actual sedes object itself.

ssz.constants module

ssz.exceptions module

exception ssz.exceptions.DeserializationError

Bases: SSZException

Exception raised if deserialization fails.

exception ssz.exceptions.SSZException

Bases: Exception

Base class for exceptions raised by this package.

exception ssz.exceptions.SerializationError

Bases: SSZException

Exception raised if serialization fails.

ssz.hash module

ssz.hash.hash_eth2(data: bytes) → Hash32: Return SHA-256 hashed result. Note: it’s a placeholder and we aim to migrate to a S[T/N]ARK-friendly hash function in a future Ethereum 2.0 deployment phase.

ssz.hash_tree module

class ssz.hash_tree.HashTree(raw_hash_tree: PVector[PVector[Hash32]], chunk_count: int | None = None)

Bases: PVector[Hash32]

append(value: Hash32) → HashTree

property chunks: PVector[Hash32]

classmethod compute(chunks: Iterable[Hash32], chunk_count: int | None = None) → HashTree

count(value) → integer -- return number of occurrences of value

delete(index: int, stop: int | None = None) → HashTree

evolver()

extend(value: Iterable[Hash32]) → HashTree

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

mset(*args: int | Hash32) → HashTree

remove(value: Hash32) → HashTree

property root: Hash32

set(index: int, value: Hash32) → HashTree

transform(*transformations)

class ssz.hash_tree.HashTreeEvolver(hash_tree: HashTree)

Bases: object

append(value: Hash32) → None

delete(index, stop=None)

extend(values: Iterable[Hash32]) → None

is_dirty() → bool

persistent() → HashTree

remove(value)

set(index: Integral, value: Hash32) → None

ssz.hash_tree.append_chunk_to_tree(hash_tree: PVector[PVector[Hash32]], chunk: Hash32) → PVector[PVector[Hash32]]

ssz.hash_tree.compute_hash_tree(chunks: Iterable[Hash32], chunk_count: int | None = None) → PVector[PVector[Hash32]]

ssz.hash_tree.generate_chunk_tree_padding(unpadded_chunk_tree: PVector[Hash32], chunk_count: int | None) → Generator[Hash32, None, None]

ssz.hash_tree.generate_hash_tree_layers(chunks: PVector[Hash32]) → Generator[PVector[Hash32], None, None]

ssz.hash_tree.get_num_layers(num_chunks: int, chunk_count: int | None) → int

ssz.hash_tree.hash_layer(child_layer: PVector[Hash32], layer_index: int) → PVector[Hash32]

ssz.hash_tree.pad_hash_tree(unpadded_chunk_tree: PVector[PVector[Hash32]], chunk_count: int | None = None) → PVector[PVector[Hash32]]

ssz.hash_tree.recompute_hash_in_tree(hash_tree: PVector[PVector[Hash32]], layer_index: int, hash_index: int) → PVector[PVector[Hash32]]

ssz.hash_tree.set_chunk_in_tree(hash_tree: PVector[PVector[Hash32]], index: int, chunk: Hash32) → PVector[PVector[Hash32]]

ssz.hash_tree.validate_chunk_count(chunk_count: int | None) → None

ssz.hash_tree.validate_raw_hash_tree(raw_hash_tree: PVector[PVector[Hash32]], chunk_count: int | None = None) → None

ssz.hashable_container module

class ssz.hashable_container.FieldDescriptor(name: str)

Bases: object

Descriptor translating from __getattr__ to __getitem__ calls for a given attribute.

ssz.hashable_container.GenericMetaHashableContainer: alias of MetaHashableContainer

ssz.hashable_container.GenericMetaSignedHashableContainer: alias of MetaSignedHashableContainer

class ssz.hashable_container.HashableContainer(*args, **kwargs)

Bases: BaseHashableStructure[TElement]

Base class for hashable containers.

classmethod create(**field_kwargs: Dict[str, Any])

evolver() → HashableContainerEvolver[TStructure, TElement]

property hash_tree_root: Hash32

normalize_item_index(index: str | int) → int

class ssz.hashable_container.HashableContainerEvolver(hashable_structure: TStructure)

Bases: HashableStructureEvolver[TStructure, TElement]

Base class for evolvers for hashable containers.

Subclasses (created dynamically by MetaHashableContainer when creating the corresponding HashableContainer) should add settable field descriptors for all fields.

class ssz.hashable_container.Meta(fields, field_names, field_names_to_element_indices, container_sedes, evolver_class)

Bases: tuple

container_sedes: Container: Alias for field number 3

evolver_class: Type[HashableContainerEvolver]: Alias for field number 4

field_names: Tuple[str, ...]: Alias for field number 1

field_names_to_element_indices: Dict[str, int]: Alias for field number 2

fields: Tuple[Tuple[str, BaseSedes], ...]: Alias for field number 0

classmethod from_fields(fields: Tuple[Tuple[str, BaseSedes], ...], container: Container, name: str) → Meta

class ssz.hashable_container.MetaHashableContainer(name: str, bases: Tuple[Type, ...], namespace: Dict[str, Any])

Bases: ABCMeta

Metaclass which creates HashableContainers.

deserialize(data)

get_fixed_size()

get_hash_tree_root(value)

get_hash_tree_root_and_leaves(value, cache)

get_key(value)

get_sedes_id()

property is_fixed_sized

serialize(value)

class ssz.hashable_container.MetaSignedHashableContainer(name, bases, namespace): Bases: MetaHashableContainer

class ssz.hashable_container.SettableFieldDescriptor(name: str)

Bases: FieldDescriptor

Settable variant of FieldDescriptor for evolver.

class ssz.hashable_container.SignedHashableContainer(*args, **kwargs)

Bases: HashableContainer[TElement]

property signing_root: Hash32

ssz.hashable_container.get_field_sedes_from_fields(fields: Sequence[Tuple[str, BaseSedes]]) → Generator[BaseSedes, None, None]

ssz.hashable_container.get_meta_from_bases(bases: Tuple[Type, ...]) → Meta | None

Return the meta object defined by one of the given base classes.

Returns None if no base defines a meta object. Raises a TypeError if more than one do.

ssz.hashable_container.hashablify_field_kwargs(field_kwargs: Dict[str, Any], fields: Sequence[Tuple[str, BaseSedes]]) → Generator[Tuple[str, Any], None, None]

ssz.hashable_container.hashablify_value(value: Any, sedes: BaseSedes) → Any

ssz.hashable_list module

class ssz.hashable_list.HashableList(elements: PVector[TElement], hash_tree: HashTree, sedes: BaseProperCompositeSedes, max_length: int | None = None)

Bases: BaseResizableHashableStructure[TElement], Sequence[TElement]

classmethod from_iterable(iterable: Iterable[TElement], sedes: List[TElement, TElement])

property hash_tree_root: Hash32

ssz.hashable_structure module

class ssz.hashable_structure.BaseHashableStructure(elements: PVector[TElement], hash_tree: HashTree, sedes: BaseProperCompositeSedes, max_length: int | None = None)

Bases: HashableStructureAPI[TElement]

property chunks: PVector[Hash32]

property elements: PVector[TElement]

evolver() → HashableStructureEvolverAPI[TStructure, TElement]

classmethod from_iterable_and_sedes(iterable: Iterable[TElement], sedes: BaseProperCompositeSedes, max_length: int | None = None)

property hash_tree: HashTree

property max_length: int | None

mset(*args: int | TElement) → TStructure

property raw_root: Hash32

property sedes: BaseProperCompositeSedes

set(index: int, value: TElement) → TStructure

transform(*transformations)

class ssz.hashable_structure.BaseResizableHashableStructure(elements: PVector[TElement], hash_tree: HashTree, sedes: BaseProperCompositeSedes, max_length: int | None = None)

Bases: BaseHashableStructure, ResizableHashableStructureAPI[TElement]

append(value: TElement) → TResizableStructure

evolver() → ResizableHashableStructureEvolverAPI[TResizableStructure, TElement]

extend(values: Iterable[TElement]) → TResizableStructure

class ssz.hashable_structure.HashableStructureEvolver(hashable_structure: TStructure)

Bases: HashableStructureEvolverAPI[TStructure, TElement]

is_dirty() → bool

persistent() → TStructure

set(index: int, element: TElement) → None

class ssz.hashable_structure.ResizableHashableStructureEvolver(hashable_structure: TStructure)

Bases: HashableStructureEvolver, ResizableHashableStructureEvolverAPI[TStructure, TElement]

append(element: TElement) → None

extend(elements: Iterable[TElement]) → None

ssz.hashable_structure.get_appended_chunks(*, appended_elements: Sequence[bytes], element_size: int, num_padding_elements: int) → Generator[Hash32, None, None]: Get the sequence of appended chunks.

ssz.hashable_structure.get_num_padding_elements(*, num_original_elements: int, num_original_chunks: int, element_size: int) → int: Compute the number of elements that would still fit in the empty space of the last chunk.

ssz.hashable_structure.get_updated_chunks(*, updated_elements: Dict[int, bytes], appended_elements: Sequence[bytes], original_chunks: Sequence[Hash32], element_size: int, num_original_elements: int, num_padding_elements: int) → Generator[Tuple[int, Hash32], None, None]

For an element changeset, compute the updates that have to be applied to the existing chunks.

The changeset is given as a dictionary of element indices to updated elements and a sequence of appended elements. Note that appended elements that do not affect existing chunks are ignored.

The pre-existing state is given by the sequence of original chunks and the number of elements represented by these chunks.

The return value is a dictionary mapping chunk indices to chunks.

ssz.hashable_structure.update_element_in_chunk(original_chunk: Hash32, index: int, element: bytes) → Hash32

Replace part of a chunk with a given element.

The chunk is interpreted as a concatenated sequence of equally sized elements. This function replaces the element given by its index in the chunk with the given data.

If the length of the element is zero or not a divisor of the chunk size, a ValueError is raised. If the index is out of range, an IndexError is raised.

>>> from ssz.hashable_structure import update_element_in_chunk
>>> update_element_in_chunk(b"aabbcc", 1, b"xx")
b'aaxxcc'

ssz.hashable_structure.update_elements_in_chunk(original_chunk: Hash32, updated_elements: Dict[int, bytes]) → Hash32

Update multiple elements in a chunk.

The set of updates is given by a dictionary mapping indices to elements. The items of the dictionary will be passed one by one to update_element_in_chunk.

ssz.hashable_vector module

class ssz.hashable_vector.HashableVector(elements: PVector[TElement], hash_tree: HashTree, sedes: BaseProperCompositeSedes, max_length: int | None = None)

Bases: BaseHashableStructure[TElement], Sequence[TElement]

classmethod from_iterable(iterable: Iterable[TElement], sedes: Vector[TElement, TElement])

property hash_tree_root: Hash32

ssz.tree_hash module

ssz.tree_hash.get_hash_tree_root(value: Any, sedes: BaseSedes | None = None) → Hash32

ssz.typing module

ssz.utils module

ssz.utils.decode_offset(data: bytes) → int

ssz.utils.encode_offset(offset: int) → bytes

ssz.utils.get_duplicates(values)

ssz.utils.get_items_per_chunk(item_size: int) → int

ssz.utils.get_next_power_of_two(value: int) → int

ssz.utils.get_serialized_bytearray(value: Sequence[bool], bit_count: int, extra_byte: bool) → bytearray

ssz.utils.is_immutable_field_value(value: Any) → bool

ssz.utils.merkleize(chunks: Sequence[Hash32], limit: int | None = None) → Hash32

ssz.utils.merkleize_with_cache(chunks: Sequence[Hash32], cache: CacheObj, limit: int | None = None) → Tuple[Hash32, CacheObj]

ssz.utils.mix_in_length(root: Hash32, length: int) → Hash32

ssz.utils.pack(serialized_values: Sequence[bytes]) → Tuple[Hash32, ...]

ssz.utils.pack_bits(values: Sequence[bool]) → Tuple[Hash32]

ssz.utils.pack_bytes(byte_string: bytes) → Tuple[bytes, ...]

ssz.utils.pad_zeros(value: bytes) → bytes

ssz.utils.read_exact(num_bytes: int, stream: IO[bytes]) → bytes

ssz.utils.s_decode_offset(stream: IO[bytes]) → int

ssz.utils.to_chunks(packed_data: bytes) → Tuple[bytes, ...]