eth-ssz-specs 0.0.1.dev1__py3-none-any.whl

eth_ssz_specs-0.0.1.dev1.dist-info/METADATA

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: eth-ssz-specs
+Version: 0.0.1.dev1
+Summary: Ethereum SSZ (Simple Serialize) specification and Merkleization
+Project-URL: Homepage, https://github.com/ethereum/ssz-specs
+Project-URL: Source, https://github.com/ethereum/ssz-specs
+Project-URL: Issues, https://github.com/ethereum/ssz-specs/issues
+Author-email: Ethereum Foundation <security@ethereum.org>
+License: MIT License
+        
+        Copyright (c) 2025 Ethereum Foundation
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ethereum,merkleization,simple-serialize,specifications,ssz
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Requires-Dist: pydantic<3,>=2.12.0
+Requires-Dist: typing-extensions>=4.4
+Description-Content-Type: text/markdown
+
+# SSZ Specs
+
+Simple Serialize (SSZ) is a serialization and hashing scheme used by Ethereum.
+This project is a reference implementation written in Python which serves as the
+official specifications.
+
+## Development
+
+This project uses [`uv`](https://docs.astral.sh/uv/) and
+[`just`](https://just.systems/).
+
+```bash
+just check  # Run code quality checks
+just fix    # Run code quality fixers
+just test   # Run unit tests
+just fill   # Generate reference tests
+```
+
+## Tests
+
+This project generates JSON reference tests, included in each release, that SSZ
+implementations can run to ensure compliance with the specifications.
+
+## Releases
+
+Each release ships the `eth-ssz-specs` package on PyPI and the reference tests on the
+[releases page](https://github.com/leanEthereum/ssz-specs/releases), both built from
+the tagged commit.
+
+```bash
+pip install eth-ssz-specs
+```
+
+```bash
+TAG=v0.1.0
+curl -sSLO "https://github.com/leanEthereum/ssz-specs/releases/download/$TAG/ssz-test-vectors-$TAG.tar.gz"
+curl -sSLO "https://github.com/leanEthereum/ssz-specs/releases/download/$TAG/ssz-test-vectors-$TAG.tar.gz.sha256"
+sha256sum --check "ssz-test-vectors-$TAG.tar.gz.sha256"
+tar -xzf "ssz-test-vectors-$TAG.tar.gz"   # extracts fixtures/
+```
+
+## Types
+
+### `Boolean`
+
+A true or false value.
+
+```python
+Boolean(True)
+```
+
+### `Bit`
+
+A zero or one value.
+
+```python
+Bit(1)
+```
+
+### `Byte`
+
+Eight bits of opaque data.
+
+```python
+Byte(0xFF)
+```
+
+### `Uint8`
+
+An 8-bit unsigned integer.
+
+```python
+Uint8(0xFF)
+```
+
+### `Uint16`
+
+A 16-bit unsigned integer.
+
+```python
+Uint16(0xFFFF)
+```
+
+### `Uint32`
+
+A 32-bit unsigned integer.
+
+```python
+Uint32(0xFFFFFFFF)
+```
+
+### `Uint64`
+
+A 64-bit unsigned integer.
+
+```python
+Uint64(0xFFFFFFFFFFFFFFFF)
+```
+
+### `Uint128`
+
+A 128-bit unsigned integer.
+
+```python
+Uint128(0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF)
+```
+
+### `Uint256`
+
+A 256-bit unsigned integer.
+
+```python
+Uint256(0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF)
+```
+
+### `Vector`
+
+A fixed number of elements.
+
+```python
+class Color(Vector[Uint8]):
+    LENGTH = 3
+
+Color(data=[255, 128, 0])
+```
+
+### `List`
+
+A variable number of elements up to a limit.
+
+```python
+class Scores(List[Uint64]):
+    LIMIT = 8
+
+Scores(data=[10, 20, 30])
+```
+
+### `ByteVector`
+
+A fixed number of bytes.
+
+```python
+class Serial(ByteVector):
+    LENGTH = 4
+
+Serial(b"\x01\x02\x03\x04")
+```
+
+### `ByteList`
+
+A variable number of bytes up to a limit.
+
+```python
+class Message(ByteList):
+    LIMIT = 32
+
+Message(data=b"hello")
+```
+
+### `BitVector`
+
+A fixed number of bits.
+
+```python
+class Weekdays(BitVector):
+    LENGTH = 7
+
+Weekdays(data=[1, 0, 0, 1, 0, 1, 0])
+```
+
+### `BitList`
+
+A variable number of bits up to a limit.
+
+```python
+class Answers(BitList):
+    LIMIT = 20
+
+Answers(data=[1, 0, 1])
+```
+
+### `ProgressiveList`
+
+A variable number of elements with no limit.
+
+```python
+class Temperatures(ProgressiveList[Uint16]):
+    pass
+
+Temperatures(data=[20, 21, 19])
+```
+
+### `ProgressiveBitList`
+
+A variable number of bits with no limit.
+
+```python
+ProgressiveBitList(data=[1, 0, 1])
+```
+
+### `Container`
+
+A fixed set of named fields.
+
+```python
+class Point(Container):
+    x: Uint64
+    y: Uint64
+
+Point(x=1, y=2)
+```
+
+### `ProgressiveContainer`
+
+Named fields that keep their positions as the set changes.
+
+```python
+class Square(ProgressiveContainer):
+    ACTIVE_FIELDS = active_fields(width=3, gaps=(1,))
+
+    side: Uint16   # position 0
+    color: Uint8   # position 2
+
+Square(side=0x1234, color=0x42)
+```
+
+### `CompatibleUnion`
+
+A choice between options that share one tree shape.
+
+```python
+class Shape(CompatibleUnion):
+    OPTIONS = {1: Square, 2: Circle}
+
+Shape(selector=1, data=Square(side=0x1234, color=0x42))
+```

eth_ssz_specs-0.0.1.dev1.dist-info/RECORD

@@ -0,0 +1,17 @@
+ssz/__init__.py,sha256=GNyR-JMAOVW32wIFhEMSSLd9hFtB_SnVeYvisEF4-JE,2606
+ssz/base.py,sha256=SfSWgUILQ0ykHm3kuBGumxA1j0T--Gpicbix1TdFzuk,535
+ssz/bitfields.py,sha256=PPWF58iyO9AQd1j9VYo13-NDugtSnxY5SKmqU0b-Lis,21778
+ssz/boolean.py,sha256=d6Z3yH-_ANDBcoL54zewHkg3csMa2xYC__5e4bsqW4A,8926
+ssz/byte_arrays.py,sha256=BO4kZghk2s4v4RIFeSUp6bVGZZSAnPlNFSwTuDaw8ac,16360
+ssz/collections.py,sha256=B0gQQu5-W9m0cBIYunSc-Gi4MKyvZ9fURYKkMbnDyOM,30739
+ssz/container.py,sha256=WljEQJGutLqW9_LwEXwGZ3UMzHOWABSPWjLQax7FyLs,16198
+ssz/exceptions.py,sha256=fwdY4_HsENMDz8cx7g9308AgurjEd4zsJbg9CZjxgAw,5222
+ssz/merkleization.py,sha256=JhkQLtFjLutqzQaj-S2EUoLrk38uWTUDGnOA1IY5teo,22648
+ssz/proofs.py,sha256=fDGCcHkA8pP-wgFqJrCWp6DnPLPsIzp2yTV41RKvoKs,23377
+ssz/ssz_base.py,sha256=TsBJdnTOq9hT7Z2O2_BY8XS6rnWLBL87Ye-8PHIfU7A,15921
+ssz/uint.py,sha256=CppS_JeP8IMeUpulcrWVuQnvplfKQFqVCyTYfLSPrjU,16327
+ssz/union.py,sha256=9w0rrRokUaMoe4jqdtWxOL-gHJRp67-aYCP5OK7D5Ro,17461
+eth_ssz_specs-0.0.1.dev1.dist-info/METADATA,sha256=ULu62WTqjFfQgugVeWPchViIhbUde7NT-d_ziAegZLs,5808
+eth_ssz_specs-0.0.1.dev1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+eth_ssz_specs-0.0.1.dev1.dist-info/licenses/LICENSE,sha256=z8-I9X573urgoCse0cLjILiOv-Un_SW1I3t9yCnHYgw,1076
+eth_ssz_specs-0.0.1.dev1.dist-info/RECORD,,

eth_ssz_specs-0.0.1.dev1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

eth_ssz_specs-0.0.1.dev1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ethereum Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ssz/__init__.py

@@ -0,0 +1,116 @@
+"""SSZ primitive types and (de)serialization for Ethereum."""
+
+from ssz.bitfields import BitList, BitVector, ProgressiveBitList
+from ssz.boolean import Bit, Boolean
+from ssz.byte_arrays import (
+    ByteList,
+    ByteVector,
+)
+from ssz.collections import List, ProgressiveList, Vector
+from ssz.container import Container, ProgressiveContainer, active_fields
+from ssz.exceptions import (
+    SSZActiveFieldsError,
+    SSZDefaultError,
+    SSZDefinitionError,
+    SSZError,
+    SSZFixedSizeError,
+    SSZLengthError,
+    SSZLimitError,
+    SSZRangeError,
+    SSZScopeError,
+    SSZSerializationError,
+    SSZTypeError,
+    SSZTypeMismatch,
+    SSZUnionOptionsError,
+    SSZValueError,
+)
+from ssz.merkleization import ZERO_ROOT, Chunk, Root
+from ssz.proofs import (
+    ACTIVE_FIELDS_KEY,
+    LENGTH_KEY,
+    SELECTOR_KEY,
+    calculate_merkle_root,
+    calculate_multi_merkle_root,
+    chunk_count,
+    chunk_position,
+    element_type,
+    get_branch_indices,
+    get_generalized_index,
+    get_helper_indices,
+    get_path_indices,
+    gindex_bit,
+    gindex_child,
+    gindex_concat,
+    gindex_length,
+    gindex_parent,
+    gindex_sibling,
+    item_length,
+    verify_merkle_multiproof,
+    verify_merkle_proof,
+)
+from ssz.ssz_base import SSZType
+from ssz.uint import Byte, Uint8, Uint16, Uint32, Uint64, Uint128, Uint256
+from ssz.union import CompatibleUnion
+
+__all__ = [
+    "ACTIVE_FIELDS_KEY",
+    "Bit",
+    "BitList",
+    "BitVector",
+    "Boolean",
+    "Byte",
+    "ByteList",
+    "ByteVector",
+    "Chunk",
+    "CompatibleUnion",
+    "Container",
+    "LENGTH_KEY",
+    "List",
+    "ProgressiveBitList",
+    "ProgressiveContainer",
+    "ProgressiveList",
+    "Root",
+    "SELECTOR_KEY",
+    "SSZActiveFieldsError",
+    "SSZDefaultError",
+    "SSZDefinitionError",
+    "SSZError",
+    "SSZFixedSizeError",
+    "SSZLengthError",
+    "SSZLimitError",
+    "SSZRangeError",
+    "SSZScopeError",
+    "SSZSerializationError",
+    "SSZType",
+    "SSZTypeError",
+    "SSZTypeMismatch",
+    "SSZUnionOptionsError",
+    "SSZValueError",
+    "Uint128",
+    "Uint16",
+    "Uint256",
+    "Uint32",
+    "Uint64",
+    "Uint8",
+    "Vector",
+    "ZERO_ROOT",
+    "active_fields",
+    "calculate_merkle_root",
+    "calculate_multi_merkle_root",
+    "chunk_count",
+    "chunk_position",
+    "element_type",
+    "get_branch_indices",
+    "get_generalized_index",
+    "get_helper_indices",
+    "get_path_indices",
+    "gindex_bit",
+    "gindex_child",
+    "gindex_concat",
+    "gindex_length",
+    "gindex_parent",
+    "gindex_sibling",
+    "item_length",
+    "verify_merkle_multiproof",
+    "verify_merkle_proof",
+]

ssz/base.py

@@ -0,0 +1,21 @@
+"""Reusable, strict base model for SSZ types."""
+
+from pydantic import BaseModel, ConfigDict
+
+
+class StrictBaseModel(BaseModel):
+    """
+    Immutable, strict base model for all SSZ types.
+
+    - Frozen: attribute assignment after construction raises
+    - Extra forbidden: unknown fields rejected at construction
+    - Strict: no implicit type coercion
+    """
+
+    model_config = ConfigDict(
+        validate_default=True,
+        arbitrary_types_allowed=True,
+        extra="forbid",
+        frozen=True,
+        strict=True,
+    )