eth-ssz-specs 0.0.1.dev1__tar.gz

eth_ssz_specs-0.0.1.dev1/.gitignore

@@ -0,0 +1,168 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Test fixtures output
+fixtures/
+
+# UV
+.uv/
+
+# Ruff
+.ruff_cache/
+
+# Claude Code
+.claude/settings.local.json
+
+# Local agent worktrees
+.claude/worktrees/
+
+# Local Claude Code config (not tracked)
+.claude/
+
+# Packaged release test vectors
+ssz-test-vectors-*.tar.gz
+ssz-test-vectors-*.tar.gz.sha256

eth_ssz_specs-0.0.1.dev1/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing to SSZ Specs
+
+## Quick Start
+
+1. Fork and clone the repository
+2. Install dependencies: `uv sync`
+3. Make your changes
+4. Install `just`: `uv tool install just-bin`
+5. Run checks: `just check`
+6. Run tests: `just test`
+7. Submit a pull request
+
+## Pull Request Guidelines
+
+1. **Create a feature branch**: `git checkout -b feat/your-feature-name`
+2. **Write clear commit messages** that explain what and why
+3. **Add tests** for any new functionality
+4. **Update documentation** as needed
+5. **Ensure all checks pass** before submitting
+
+## Code Style
+
+- **Type hints**: Required for all functions and methods
+- **Docstrings**: Use Google style for public APIs
+- **Line length**: 100 characters (enforced by ruff)
+- **Formatting**: Run `just fix` to auto-format
+
+## Testing
+
+- Write tests that mirror the source structure
+- Use `pytest.mark.parametrize` for multiple test cases
+- Mark slow tests with `@pytest.mark.slow`
+
+## Cutting a Release
+
+1. Open a PR bumping `version` in both `pyproject.toml` and
+   `packages/testing/pyproject.toml` (they must match).
+2. Merge it, then run Actions → Release → Run workflow on `main`.
+
+The workflow runs the quality gate, packages the vectors, builds the package, tags
+`v<version>` with a GitHub release, and publishes `eth-ssz-specs` to PyPI. Versions
+other than plain `X.Y.Z` (e.g. `0.2.0rc1`) become GitHub prereleases. `ssz-testing`
+is internal and never published.
+
+If anything fails before the release job, no tag was created: fix and re-dispatch. If
+only the PyPI publish fails, re-run the failed job on the same run instead.
+
+Before the first release: add a PyPI trusted publisher (project `eth-ssz-specs`, owner
+`leanEthereum`, repository `ssz-specs`, workflow `release.yaml`, environment `pypi`)
+and create the `pypi` environment in the GitHub repository settings.
+
+Reproduce the artifacts locally with `just build` and `just pack-fixtures <tag>`
+(macOS: `brew install gnu-tar coreutils`).
+
+## Questions?
+
+- Check existing [issues](https://github.com/ethereum/ssz-specs/issues)
+- Open a new issue for discussion
+- See [README.md](README.md) for more details on the project structure and commands

eth_ssz_specs-0.0.1.dev1/Justfile

@@ -0,0 +1,135 @@
+set positional-arguments := true
+
+alias help := default
+
+# List available recipes
+default:
+    @just --list
+
+# Run all quality checks (lint, format, typecheck, spellcheck, lock)
+[group('quality')]
+check: lint format-check typecheck spellcheck lock-check
+
+# Lint with ruff (no auto-fix)
+[group('quality')]
+lint *args:
+    uv run --group lint ruff check --no-fix --show-fixes "$@"
+
+# Format code with ruff
+[group('quality')]
+format *args:
+    uv run --group lint ruff format "$@"
+
+# Verify formatting with ruff (no changes)
+[group('quality')]
+format-check *args:
+    uv run --group lint ruff format --check "$@"
+
+# Auto-fix lint and formatting issues
+[group('quality')]
+fix:
+    uv run --group lint ruff check --fix
+    uv run --group lint ruff format
+
+# Type check with ty
+[group('quality')]
+typecheck *args:
+    uv run --group lint ty check "$@"
+
+# Spell check source, tests, and packages
+[group('quality')]
+spellcheck *args:
+    uv run --group lint codespell src tests packages README.md --skip="*.lock,*.svg,.git,__pycache__,.pytest_cache" "$@"
+
+# Verify uv.lock is up to date
+[group('quality')]
+lock-check:
+    #!/usr/bin/env bash
+    if ! uv lock --check; then
+        echo ""
+        echo "uv.lock is out of date. To sync:"
+        echo "  uv lock"
+        echo ""
+        echo "Then commit the updated uv.lock."
+        exit 1
+    fi
+
+# Generate SSZ conformance test vectors under fixtures/
+[group('fill')]
+fill *args:
+    uv run --group test fill --clean "$@"
+
+# Run unit tests in parallel
+[group('tests')]
+test *args:
+    uv run --group test pytest tests -n auto --maxprocesses=10 --durations=10 --dist=worksteal "$@"
+
+# Run unit tests with coverage report (HTML + terminal)
+[group('tests')]
+test-cov *args:
+    uv run --group test pytest --cov --cov-report=html --cov-report=term "$@"
+
+# Run unit tests with coverage gate (fails below 100%)
+[group('tests')]
+test-cov-gate *args:
+    uv run --group test pytest --cov --cov-report=term-missing --cov-fail-under=100 "$@"
+
+# Build the eth-ssz-specs sdist and wheel into dist/
+[group('release')]
+build:
+    uv build
+
+# Fill vectors and package them as a versioned, deterministic release tarball
+# (requires GNU tar and sha256sum; on macOS: brew install gnu-tar coreutils)
+[group('release')]
+pack-fixtures tag: fill
+    #!/usr/bin/env bash
+    set -euo pipefail
+    TAR=tar
+    SHA256=sha256sum
+    if [ "$(uname)" = "Darwin" ]; then
+        command -v gtar >/dev/null || { echo "GNU tar required: brew install gnu-tar" >&2; exit 1; }
+        TAR=gtar
+        command -v sha256sum >/dev/null || SHA256="shasum -a 256"
+    fi
+    "$TAR" --sort=name --owner=0 --group=0 --numeric-owner \
+        --mtime='@0' --format=gnu \
+        --use-compress-program='gzip --no-name' \
+        --create --file="ssz-test-vectors-{{tag}}.tar.gz" fixtures
+    $SHA256 "ssz-test-vectors-{{tag}}.tar.gz" > "ssz-test-vectors-{{tag}}.tar.gz.sha256"
+
+# Print the command to install shell completions for just recipes
+[group('housekeeping')]
+shell-completions:
+    #!/usr/bin/env bash
+    case "$(basename "$SHELL")" in
+        bash)
+            echo "Run the following commands to install just completions for bash:"
+            echo ""
+            echo "  mkdir -p ~/.local/share/bash-completion/completions"
+            echo "  just --completions bash > ~/.local/share/bash-completion/completions/just"
+            ;;
+        zsh)
+            echo "Run the following commands to install just completions for zsh:"
+            echo ""
+            echo "  mkdir -p ~/.zsh/completions"
+            echo "  just --completions zsh > ~/.zsh/completions/_just"
+            echo ""
+            echo "Then add to your .zshrc:"
+            echo ""
+            echo "  fpath=(~/.zsh/completions \$fpath)"
+            echo "  autoload -U compinit"
+            echo "  compinit"
+            ;;
+        fish)
+            echo "Run the following commands to install just completions for fish:"
+            echo ""
+            echo "  mkdir -p ~/.config/fish/completions"
+            echo "  just --completions fish > ~/.config/fish/completions/just.fish"
+            ;;
+        *)
+            echo "See the link below for instructions for your shell."
+            ;;
+    esac
+    echo ""
+    echo "For more details, see https://just.systems/man/en/shell-completion-scripts.html"

eth_ssz_specs-0.0.1.dev1/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.

eth_ssz_specs-0.0.1.dev1/PKG-INFO

@@ -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))
+```