zerostyl-sdk 0.1.0__tar.gz

zerostyl_sdk-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+/target
+target/
+Cargo.lock
+**/*.rs.bk
+*.pdb
+.DS_Store
+.claude/worktrees/
+.zerostyl_cache/
+proof.bin
+public_inputs.json
+
+# Node / pnpm
+node_modules/
+packages/**/dist/
+pnpm-debug.log
+.pnpm-store/
+
+# Python
+packages/**/.venv/
+__pycache__/
+*.egg-info/

zerostyl_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Zakaria Chaikhi
+
+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.

zerostyl_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: zerostyl-sdk
+Version: 0.1.0
+Summary: Python SDK for the ZeroStyl zk toolkit on Arbitrum Stylus: ABI schema types and typed-bindings codegen
+Project-URL: Repository, https://github.com/kazai777/zerostyl
+Author-email: kazai777 <kazai777.dev@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: arbitrum,halo2,privacy,stylus,zero-knowledge,zk-snarks
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# zerostyl-sdk (Python)
+
+Python SDK for the [ZeroStyl](https://github.com/kazai777/zerostyl) zk toolkit on
+Arbitrum Stylus. Parses the exporter's `abi.json` documents into typed dataclasses and
+generates typed Python bindings — the same scope as `@zerostyl/sdk-ts`, in Python.
+
+Pure Python, zero runtime dependencies, Python ≥ 3.10.
+
+## Install (from the repo)
+
+```bash
+cd packages/sdk-py
+python -m pip install ".[dev]"
+```
+
+## Usage
+
+```python
+from pathlib import Path
+from zerostyl_sdk import parse_abi_schema, generate_bindings
+
+abi = parse_abi_schema(Path("abi.json").read_text())
+print(abi.circuit.name, abi.circuit.num_public_inputs)
+
+bindings = generate_bindings(abi)   # a Python module as a string
+Path("deposit_bindings.py").write_text(bindings)
+```
+
+CLI (equivalent of the TS SDK's `zerostyl-sdk generate`):
+
+```bash
+# after `pip install` (see above), either form works:
+zerostyl-sdk-py generate --abi ../../examples/zk_private_demo/abi.json --out bindings.py
+python -m zerostyl_sdk generate --abi ../../examples/zk_private_demo/abi.json
+```
+
+Generated output for the demo circuit:
+
+```python
+DEPOSIT_CIRCUIT: Final = {
+    "name": "deposit",
+    ...
+}
+
+@dataclass(frozen=True)
+class DepositWitness:
+    collateral: str
+    collateral_nonce: str
+    threshold: str
+
+@dataclass(frozen=True)
+class DepositPublicInputs:
+    collateral_commitment: str
+```
+
+Type mapping: `u64`/`u128` → `int`, `bool` → `bool`, `fp`/`bytes32`/`address` → `str`
+(`0x`-prefixed hex), arrays → `tuple[..., ...]`.
+
+## Tests
+
+```bash
+python -m pytest
+ruff check src tests
+```
+
+The snapshot test locks the generated bindings for
+`examples/zk_private_demo/abi.json`; regenerate with
+`REGEN_SDK_PY_SNAPSHOTS=1 python -m pytest`.
+
+## Scope and future work
+
+Codegen only — proof generation from Python (bindings to the Rust prover) and on-chain
+submission helpers are future work, mirroring the TypeScript SDK's roadmap. The package
+is not yet published to PyPI.
+
+## License
+
+MIT — see the repository's [LICENSE](../../LICENSE).

zerostyl_sdk-0.1.0/README.md

@@ -0,0 +1,78 @@
+# zerostyl-sdk (Python)
+
+Python SDK for the [ZeroStyl](https://github.com/kazai777/zerostyl) zk toolkit on
+Arbitrum Stylus. Parses the exporter's `abi.json` documents into typed dataclasses and
+generates typed Python bindings — the same scope as `@zerostyl/sdk-ts`, in Python.
+
+Pure Python, zero runtime dependencies, Python ≥ 3.10.
+
+## Install (from the repo)
+
+```bash
+cd packages/sdk-py
+python -m pip install ".[dev]"
+```
+
+## Usage
+
+```python
+from pathlib import Path
+from zerostyl_sdk import parse_abi_schema, generate_bindings
+
+abi = parse_abi_schema(Path("abi.json").read_text())
+print(abi.circuit.name, abi.circuit.num_public_inputs)
+
+bindings = generate_bindings(abi)   # a Python module as a string
+Path("deposit_bindings.py").write_text(bindings)
+```
+
+CLI (equivalent of the TS SDK's `zerostyl-sdk generate`):
+
+```bash
+# after `pip install` (see above), either form works:
+zerostyl-sdk-py generate --abi ../../examples/zk_private_demo/abi.json --out bindings.py
+python -m zerostyl_sdk generate --abi ../../examples/zk_private_demo/abi.json
+```
+
+Generated output for the demo circuit:
+
+```python
+DEPOSIT_CIRCUIT: Final = {
+    "name": "deposit",
+    ...
+}
+
+@dataclass(frozen=True)
+class DepositWitness:
+    collateral: str
+    collateral_nonce: str
+    threshold: str
+
+@dataclass(frozen=True)
+class DepositPublicInputs:
+    collateral_commitment: str
+```
+
+Type mapping: `u64`/`u128` → `int`, `bool` → `bool`, `fp`/`bytes32`/`address` → `str`
+(`0x`-prefixed hex), arrays → `tuple[..., ...]`.
+
+## Tests
+
+```bash
+python -m pytest
+ruff check src tests
+```
+
+The snapshot test locks the generated bindings for
+`examples/zk_private_demo/abi.json`; regenerate with
+`REGEN_SDK_PY_SNAPSHOTS=1 python -m pytest`.
+
+## Scope and future work
+
+Codegen only — proof generation from Python (bindings to the Rust prover) and on-chain
+submission helpers are future work, mirroring the TypeScript SDK's roadmap. The package
+is not yet published to PyPI.
+
+## License
+
+MIT — see the repository's [LICENSE](../../LICENSE).

zerostyl_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zerostyl-sdk"
+version = "0.1.0"
+description = "Python SDK for the ZeroStyl zk toolkit on Arbitrum Stylus: ABI schema types and typed-bindings codegen"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "kazai777", email = "kazai777.dev@gmail.com" }]
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["arbitrum", "stylus", "zero-knowledge", "privacy", "zk-snarks", "halo2"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security :: Cryptography",
+]
+
+[project.urls]
+Repository = "https://github.com/kazai777/zerostyl"
+
+[project.scripts]
+zerostyl-sdk-py = "zerostyl_sdk.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.5"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zerostyl_sdk"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+# Pinned rule set so local runs and CI agree regardless of user-level config.
+select = ["E4", "E7", "E9", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

zerostyl_sdk-0.1.0/src/zerostyl_sdk/__init__.py

@@ -0,0 +1,40 @@
+"""Python SDK for the ZeroStyl zk toolkit on Arbitrum Stylus.
+
+Parses the exporter's ``abi.json`` documents into typed dataclasses and
+generates typed Python bindings (mirroring ``@zerostyl/sdk-ts``).
+"""
+
+from .codegen.generator import generate_bindings
+from .codegen.type_mapping import field_type_to_py
+from .types import (
+    ABI_VERSION,
+    AbiSchema,
+    CircuitMetadata,
+    FieldType,
+    OnChainBinding,
+    ProofMetadata,
+    PublicInputField,
+    PublicInputsSchema,
+    WitnessField,
+    WitnessSchema,
+    parse_abi_schema,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ABI_VERSION",
+    "AbiSchema",
+    "CircuitMetadata",
+    "FieldType",
+    "OnChainBinding",
+    "ProofMetadata",
+    "PublicInputField",
+    "PublicInputsSchema",
+    "WitnessField",
+    "WitnessSchema",
+    "__version__",
+    "field_type_to_py",
+    "generate_bindings",
+    "parse_abi_schema",
+]

zerostyl_sdk-0.1.0/src/zerostyl_sdk/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for ``python -m zerostyl_sdk``."""
+
+from .cli import main
+
+raise SystemExit(main())

zerostyl_sdk-0.1.0/src/zerostyl_sdk/cli.py

@@ -0,0 +1,53 @@
+"""Command-line interface: ``zerostyl-sdk-py generate --abi <file> [--out <file>]``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .codegen.generator import generate_bindings
+from .types import parse_abi_schema
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="zerostyl-sdk-py",
+        description="Generate typed Python bindings from a ZeroStyl abi.json",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    generate = subparsers.add_parser("generate", help="generate bindings from an abi.json")
+    generate.add_argument("--abi", "-a", required=True, help="path to the abi.json file")
+    generate.add_argument(
+        "--out", "-o", help="output .py file (prints to stdout when omitted)"
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command != "generate":  # pragma: no cover — argparse enforces this
+        return 2
+
+    abi_path = Path(args.abi)
+    try:
+        abi = parse_abi_schema(abi_path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        print(f"error: cannot read {abi_path}: {exc}", file=sys.stderr)
+        return 1
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    bindings = generate_bindings(abi)
+    if args.out:
+        Path(args.out).write_text(bindings, encoding="utf-8")
+        print(f"wrote {args.out}", file=sys.stderr)
+    else:
+        print(bindings, end="")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

zerostyl_sdk-0.1.0/src/zerostyl_sdk/codegen/__init__.py

@@ -0,0 +1,4 @@
+from .generator import generate_bindings
+from .type_mapping import field_type_to_py
+
+__all__ = ["field_type_to_py", "generate_bindings"]

zerostyl_sdk-0.1.0/src/zerostyl_sdk/codegen/generator.py

@@ -0,0 +1,75 @@
+"""Generate Python bindings from an ABI schema.
+
+The generated module mirrors the TypeScript SDK's output: a circuit-metadata
+constant plus frozen dataclasses for the witness and the public inputs.
+"""
+
+from __future__ import annotations
+
+import keyword
+
+from ..types import AbiSchema, PublicInputField, WitnessField
+from .type_mapping import field_type_to_py
+
+HEADER = "# auto-generated by zerostyl-sdk (python) — do not edit"
+
+
+def _safe_ident(name: str) -> str:
+    """Make an ABI field name a valid, non-keyword Python identifier.
+
+    ABI names are Rust identifiers, so the only collision is a Python keyword
+    (e.g. a field literally named ``from``): append an underscore, matching
+    PEP 8's convention for keyword-clashing names.
+    """
+    return f"{name}_" if keyword.iskeyword(name) else name
+
+
+def generate_bindings(abi: AbiSchema) -> str:
+    """Emit a Python module with typed bindings for one circuit."""
+    pascal = _pascal_case(abi.circuit.name)
+    upper = abi.circuit.name.upper()
+    sections = [
+        HEADER,
+        "",
+        "from dataclasses import dataclass",
+        "from typing import Final",
+        "",
+        _emit_circuit_const(upper, abi),
+        "",
+        _emit_dataclass(f"{pascal}Witness", abi.witness.fields),
+        "",
+        _emit_dataclass(f"{pascal}PublicInputs", abi.public_inputs.fields),
+        "",
+    ]
+    return "\n".join(sections)
+
+
+def _emit_circuit_const(upper: str, abi: AbiSchema) -> str:
+    c = abi.circuit
+    return "\n".join(
+        [
+            f"{upper}_CIRCUIT: Final = {{",
+            f'    "name": {c.name!r},',
+            f'    "version": {c.version!r},',
+            f'    "default_k": {c.default_k},',
+            f'    "num_public_inputs": {c.num_public_inputs},',
+            f'    "num_private_witnesses": {c.num_private_witnesses},',
+            "}",
+        ]
+    )
+
+
+def _emit_dataclass(
+    name: str, fields: tuple[WitnessField, ...] | tuple[PublicInputField, ...]
+) -> str:
+    lines = ["@dataclass(frozen=True)", f"class {name}:"]
+    if not fields:
+        lines.append("    pass")
+    else:
+        for f in fields:
+            lines.append(f"    {_safe_ident(f.name)}: {field_type_to_py(f.kind)}")
+    return "\n".join(lines)
+
+
+def _pascal_case(name: str) -> str:
+    return "".join(part.capitalize() for part in name.split("_") if part)

zerostyl_sdk-0.1.0/src/zerostyl_sdk/codegen/type_mapping.py

@@ -0,0 +1,23 @@
+"""Mapping from ABI field types to Python type annotations."""
+
+from __future__ import annotations
+
+from ..types import FieldType
+
+_SCALAR_TO_PY = {
+    "u64": "int",
+    "u128": "int",
+    "bool": "bool",
+    # Field elements, hashes, and addresses travel as 0x-prefixed hex strings.
+    "fp": "str",
+    "bytes32": "str",
+    "address": "str",
+}
+
+
+def field_type_to_py(field_type: FieldType) -> str:
+    """Return the Python annotation for an ABI field type."""
+    if field_type.is_array:
+        assert field_type.kind is not None  # guaranteed by FieldType validation
+        return f"tuple[{field_type_to_py(field_type.kind)}, ...]"
+    return _SCALAR_TO_PY[field_type.type]

zerostyl_sdk-0.1.0/src/zerostyl_sdk/types.py

@@ -0,0 +1,217 @@
+"""Typed mirror of the ZeroStyl ABI schema (``abi.json``).
+
+The dataclasses here map 1:1 onto the Rust ``zerostyl_circuits::abi::AbiSchema``
+(and the TypeScript ``@zerostyl/sdk-ts`` types): circuit metadata, private
+witness fields, public inputs, and proof metadata.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+ABI_VERSION = 1
+
+_SCALAR_TAGS = frozenset({"u64", "u128", "bool", "bytes32", "address", "fp"})
+_PROVING_SYSTEMS = frozenset(
+    {"halo2_ipa", "halo2_kzg_groth16_wrap", "halo2_kzg", "stark_fri"}
+)
+_VISIBILITIES = frozenset({"private", "public"})
+
+
+@dataclass(frozen=True)
+class FieldType:
+    """A field's wire type: a scalar tag, or ``array`` with ``kind``/``len``."""
+
+    type: str
+    kind: FieldType | None = None
+    len: int | None = None
+
+    def __post_init__(self) -> None:
+        if self.type == "array":
+            if self.kind is None or self.len is None:
+                raise ValueError("array field type requires `kind` and `len`")
+        elif self.type in _SCALAR_TAGS:
+            if self.kind is not None or self.len is not None:
+                raise ValueError(f"scalar field type `{self.type}` takes no `kind`/`len`")
+        else:
+            raise ValueError(f"unknown field type tag `{self.type}`")
+
+    @property
+    def is_array(self) -> bool:
+        return self.type == "array"
+
+
+@dataclass(frozen=True)
+class WitnessField:
+    name: str
+    kind: FieldType
+    visibility: str
+    description: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.visibility not in _VISIBILITIES:
+            raise ValueError(f"unknown visibility `{self.visibility}`")
+
+
+@dataclass(frozen=True)
+class WitnessSchema:
+    fields: tuple[WitnessField, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True)
+class PublicInputField:
+    name: str
+    kind: FieldType
+    description: str | None = None
+
+
+@dataclass(frozen=True)
+class PublicInputsSchema:
+    fields: tuple[PublicInputField, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True)
+class CircuitMetadata:
+    name: str
+    version: str
+    description: str
+    default_k: int
+    num_public_inputs: int
+    num_private_witnesses: int
+
+
+@dataclass(frozen=True)
+class ProofMetadata:
+    format_version: int
+    proving_system: str
+    approx_size_bytes: int | None = None
+
+    def __post_init__(self) -> None:
+        if self.proving_system not in _PROVING_SYSTEMS:
+            raise ValueError(f"unknown proving system `{self.proving_system}`")
+
+
+@dataclass(frozen=True)
+class OnChainBinding:
+    chain_id: int
+    contract_address: str
+
+
+@dataclass(frozen=True)
+class AbiSchema:
+    abi_version: int
+    circuit: CircuitMetadata
+    witness: WitnessSchema
+    public_inputs: PublicInputsSchema
+    proof: ProofMetadata
+    on_chain: OnChainBinding | None = None
+
+
+def _parse_field_type(data: Any) -> FieldType:
+    if not isinstance(data, dict):
+        raise ValueError(f"field type must be an object, got {type(data).__name__}")
+    tag = data.get("type")
+    if tag == "array":
+        if "kind" not in data or "len" not in data:
+            raise ValueError("array field type requires `kind` and `len`")
+        return FieldType(type="array", kind=_parse_field_type(data["kind"]), len=int(data["len"]))
+    if not isinstance(tag, str):
+        raise ValueError("field type object is missing its `type` tag")
+    return FieldType(type=tag)
+
+
+def _require(data: dict[str, Any], key: str, context: str) -> Any:
+    if key not in data:
+        raise ValueError(f"missing `{key}` in {context}")
+    return data[key]
+
+
+def parse_abi_schema(json_str: str) -> AbiSchema:
+    """Parse and validate an ``abi.json`` document.
+
+    Raises ``ValueError`` on malformed JSON, unknown enum values, an
+    unsupported ``abi_version``, or count mismatches between the circuit
+    metadata and the field lists.
+    """
+    try:
+        data = json.loads(json_str)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"abi.json is not valid JSON: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ValueError("abi.json must be a JSON object")
+
+    abi_version = int(_require(data, "abi_version", "abi.json"))
+    if abi_version != ABI_VERSION:
+        raise ValueError(
+            f"unsupported abi_version {abi_version} (this SDK supports {ABI_VERSION})"
+        )
+
+    circuit_data = _require(data, "circuit", "abi.json")
+    circuit = CircuitMetadata(
+        name=str(_require(circuit_data, "name", "circuit")),
+        version=str(_require(circuit_data, "version", "circuit")),
+        description=str(_require(circuit_data, "description", "circuit")),
+        default_k=int(_require(circuit_data, "default_k", "circuit")),
+        num_public_inputs=int(_require(circuit_data, "num_public_inputs", "circuit")),
+        num_private_witnesses=int(_require(circuit_data, "num_private_witnesses", "circuit")),
+    )
+
+    witness = WitnessSchema(
+        fields=tuple(
+            WitnessField(
+                name=str(_require(f, "name", "witness field")),
+                kind=_parse_field_type(_require(f, "kind", "witness field")),
+                visibility=str(_require(f, "visibility", "witness field")),
+                description=f.get("description"),
+            )
+            for f in _require(data, "witness", "abi.json")["fields"]
+        )
+    )
+
+    public_inputs = PublicInputsSchema(
+        fields=tuple(
+            PublicInputField(
+                name=str(_require(f, "name", "public input field")),
+                kind=_parse_field_type(_require(f, "kind", "public input field")),
+                description=f.get("description"),
+            )
+            for f in _require(data, "public_inputs", "abi.json")["fields"]
+        )
+    )
+
+    proof_data = _require(data, "proof", "abi.json")
+    proof = ProofMetadata(
+        format_version=int(_require(proof_data, "format_version", "proof")),
+        proving_system=str(_require(proof_data, "proving_system", "proof")),
+        approx_size_bytes=proof_data.get("approx_size_bytes"),
+    )
+
+    on_chain = None
+    if data.get("on_chain") is not None:
+        oc = data["on_chain"]
+        on_chain = OnChainBinding(
+            chain_id=int(_require(oc, "chain_id", "on_chain")),
+            contract_address=str(_require(oc, "contract_address", "on_chain")),
+        )
+
+    if circuit.num_public_inputs != len(public_inputs.fields):
+        raise ValueError(
+            f"circuit.num_public_inputs ({circuit.num_public_inputs}) does not match "
+            f"public_inputs.fields length ({len(public_inputs.fields)})"
+        )
+    if circuit.num_private_witnesses != len(witness.fields):
+        raise ValueError(
+            f"circuit.num_private_witnesses ({circuit.num_private_witnesses}) does not match "
+            f"witness.fields length ({len(witness.fields)})"
+        )
+
+    return AbiSchema(
+        abi_version=abi_version,
+        circuit=circuit,
+        witness=witness,
+        public_inputs=public_inputs,
+        proof=proof,
+        on_chain=on_chain,
+    )

zerostyl_sdk-0.1.0/tests/snapshots/zk_private_demo_snap.py

@@ -0,0 +1,22 @@
+# auto-generated by zerostyl-sdk (python) — do not edit
+
+from dataclasses import dataclass
+from typing import Final
+
+DEPOSIT_CIRCUIT: Final = {
+    "name": 'deposit',
+    "version": '1.0.0',
+    "default_k": 10,
+    "num_public_inputs": 1,
+    "num_private_witnesses": 3,
+}
+
+@dataclass(frozen=True)
+class DepositWitness:
+    collateral: int
+    collateral_nonce: str
+    threshold: int
+
+@dataclass(frozen=True)
+class DepositPublicInputs:
+    collateral_commitment: str

zerostyl_sdk-0.1.0/tests/test_cli.py

@@ -0,0 +1,47 @@
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from zerostyl_sdk.cli import main
+
+DEMO_ABI = (
+    Path(__file__).resolve().parents[3] / "examples" / "zk_private_demo" / "abi.json"
+)
+
+
+def test_generate_to_stdout(capsys):
+    assert main(["generate", "--abi", str(DEMO_ABI)]) == 0
+    out = capsys.readouterr().out
+    assert "class DepositWitness:" in out
+
+
+def test_generate_to_file(tmp_path):
+    out_file = tmp_path / "bindings.py"
+    assert main(["generate", "--abi", str(DEMO_ABI), "--out", str(out_file)]) == 0
+    content = out_file.read_text(encoding="utf-8")
+    compile(content, str(out_file), "exec")
+    assert "DEPOSIT_CIRCUIT" in content
+
+
+def test_missing_abi_file_fails(tmp_path, capsys):
+    assert main(["generate", "--abi", str(tmp_path / "nope.json")]) == 1
+    assert "cannot read" in capsys.readouterr().err
+
+
+def test_invalid_abi_fails(tmp_path, capsys):
+    bad = tmp_path / "bad.json"
+    bad.write_text(json.dumps({"abi_version": 1}), encoding="utf-8")
+    assert main(["generate", "--abi", str(bad)]) == 1
+    assert "error:" in capsys.readouterr().err
+
+
+def test_module_entry_point_runs():
+    result = subprocess.run(
+        [sys.executable, "-m", "zerostyl_sdk", "generate", "--abi", str(DEMO_ABI)],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert result.returncode == 0
+    assert "class DepositWitness:" in result.stdout

zerostyl_sdk-0.1.0/tests/test_generator.py

@@ -0,0 +1,97 @@
+import json
+
+from zerostyl_sdk import generate_bindings, parse_abi_schema
+from zerostyl_sdk.codegen.generator import HEADER
+
+
+def abi(witness_fields=None, public_fields=None, name="deposit"):
+    witness_fields = witness_fields if witness_fields is not None else [
+        {"name": "amount", "kind": {"type": "fp"}, "visibility": "private"}
+    ]
+    public_fields = public_fields if public_fields is not None else [
+        {"name": "amount_commitment", "kind": {"type": "fp"}}
+    ]
+    return parse_abi_schema(
+        json.dumps(
+            {
+                "abi_version": 1,
+                "circuit": {
+                    "name": name,
+                    "version": "1.0.0",
+                    "description": "test",
+                    "default_k": 10,
+                    "num_public_inputs": len(public_fields),
+                    "num_private_witnesses": len(witness_fields),
+                },
+                "witness": {"fields": witness_fields},
+                "public_inputs": {"fields": public_fields},
+                "proof": {"format_version": 1, "proving_system": "halo2_kzg"},
+            }
+        )
+    )
+
+
+def test_generated_module_is_valid_python():
+    code = generate_bindings(abi())
+    compile(code, "<generated>", "exec")
+
+
+def test_header_and_const_present():
+    code = generate_bindings(abi())
+    assert code.startswith(HEADER)
+    assert 'DEPOSIT_CIRCUIT: Final = {' in code
+    assert '"name": \'deposit\'' in code or "\"name\": 'deposit'" in code
+    assert '"default_k": 10' in code
+
+
+def test_dataclasses_have_typed_fields():
+    code = generate_bindings(abi())
+    assert "@dataclass(frozen=True)" in code
+    assert "class DepositWitness:" in code
+    assert "    amount: str" in code
+    assert "class DepositPublicInputs:" in code
+    assert "    amount_commitment: str" in code
+
+
+def test_array_fields_map_to_tuples():
+    code = generate_bindings(
+        abi(
+            witness_fields=[
+                {
+                    "name": "siblings",
+                    "kind": {"type": "array", "kind": {"type": "fp"}, "len": 32},
+                    "visibility": "private",
+                }
+            ]
+        )
+    )
+    assert "    siblings: tuple[str, ...]" in code
+
+
+def test_empty_schemas_generate_pass_dataclasses():
+    code = generate_bindings(abi(witness_fields=[], public_fields=[]))
+    compile(code, "<generated>", "exec")
+    assert "class DepositWitness:\n    pass" in code
+    assert "class DepositPublicInputs:\n    pass" in code
+
+
+def test_multi_segment_name_pascal_cased():
+    code = generate_bindings(abi(name="private_vote_tally"))
+    assert "class PrivateVoteTallyWitness:" in code
+    assert "PRIVATE_VOTE_TALLY_CIRCUIT: Final = {" in code
+
+
+def test_python_keyword_field_names_are_sanitized():
+    # `from` is a valid Rust identifier but a Python keyword; the generated
+    # dataclass must stay importable.
+    code = generate_bindings(
+        abi(
+            witness_fields=[
+                {"name": "from", "kind": {"type": "address"}, "visibility": "private"},
+                {"name": "amount", "kind": {"type": "u64"}, "visibility": "private"},
+            ]
+        )
+    )
+    compile(code, "<generated>", "exec")
+    assert "    from_: str" in code
+    assert "    amount: int" in code

zerostyl_sdk-0.1.0/tests/test_snapshot.py

@@ -0,0 +1,32 @@
+"""Locks the generated bindings for the demo circuit against a committed
+snapshot. Set ``REGEN_SDK_PY_SNAPSHOTS=1`` to overwrite the snapshot after an
+intentional generator change."""
+
+import os
+from pathlib import Path
+
+from zerostyl_sdk import generate_bindings, parse_abi_schema
+
+DEMO_ABI = (
+    Path(__file__).resolve().parents[3] / "examples" / "zk_private_demo" / "abi.json"
+)
+SNAPSHOT = Path(__file__).parent / "snapshots" / "zk_private_demo_snap.py"
+
+
+def test_demo_bindings_match_snapshot():
+    abi = parse_abi_schema(DEMO_ABI.read_text(encoding="utf-8"))
+    generated = generate_bindings(abi)
+    compile(generated, "<generated>", "exec")
+
+    if os.environ.get("REGEN_SDK_PY_SNAPSHOTS"):
+        SNAPSHOT.parent.mkdir(parents=True, exist_ok=True)
+        SNAPSHOT.write_text(generated, encoding="utf-8")
+        return
+
+    assert SNAPSHOT.exists(), (
+        f"snapshot {SNAPSHOT} missing — run REGEN_SDK_PY_SNAPSHOTS=1 python -m pytest"
+    )
+    on_disk = SNAPSHOT.read_text(encoding="utf-8").replace("\r\n", "\n")
+    assert on_disk == generated.replace("\r\n", "\n"), (
+        "snapshot out of sync — run REGEN_SDK_PY_SNAPSHOTS=1 python -m pytest"
+    )

zerostyl_sdk-0.1.0/tests/test_type_mapping.py

@@ -0,0 +1,29 @@
+import pytest
+
+from zerostyl_sdk import FieldType, field_type_to_py
+
+
+@pytest.mark.parametrize(
+    ("tag", "expected"),
+    [
+        ("u64", "int"),
+        ("u128", "int"),
+        ("bool", "bool"),
+        ("fp", "str"),
+        ("bytes32", "str"),
+        ("address", "str"),
+    ],
+)
+def test_scalar_mappings(tag, expected):
+    assert field_type_to_py(FieldType(type=tag)) == expected
+
+
+def test_array_mapping():
+    t = FieldType(type="array", kind=FieldType(type="fp"), len=32)
+    assert field_type_to_py(t) == "tuple[str, ...]"
+
+
+def test_nested_array_mapping():
+    inner = FieldType(type="array", kind=FieldType(type="u64"), len=4)
+    outer = FieldType(type="array", kind=inner, len=2)
+    assert field_type_to_py(outer) == "tuple[tuple[int, ...], ...]"

zerostyl_sdk-0.1.0/tests/test_types.py

@@ -0,0 +1,131 @@
+import json
+
+import pytest
+
+from zerostyl_sdk import ABI_VERSION, FieldType, parse_abi_schema
+
+
+def sample_abi() -> dict:
+    return {
+        "abi_version": ABI_VERSION,
+        "circuit": {
+            "name": "deposit",
+            "version": "1.0.0",
+            "description": "test circuit",
+            "default_k": 10,
+            "num_public_inputs": 1,
+            "num_private_witnesses": 2,
+        },
+        "witness": {
+            "fields": [
+                {"name": "amount", "kind": {"type": "fp"}, "visibility": "private"},
+                {"name": "amount_nonce", "kind": {"type": "fp"}, "visibility": "private"},
+            ]
+        },
+        "public_inputs": {
+            "fields": [{"name": "amount_commitment", "kind": {"type": "fp"}}]
+        },
+        "proof": {"format_version": 1, "proving_system": "halo2_kzg"},
+    }
+
+
+def test_parses_valid_schema():
+    abi = parse_abi_schema(json.dumps(sample_abi()))
+    assert abi.abi_version == ABI_VERSION
+    assert abi.circuit.name == "deposit"
+    assert abi.witness.fields[0].name == "amount"
+    assert abi.public_inputs.fields[0].kind.type == "fp"
+    assert abi.proof.proving_system == "halo2_kzg"
+    assert abi.on_chain is None
+
+
+def test_parses_nested_array_field_type():
+    data = sample_abi()
+    data["witness"]["fields"][0]["kind"] = {
+        "type": "array",
+        "kind": {"type": "fp"},
+        "len": 32,
+    }
+    abi = parse_abi_schema(json.dumps(data))
+    kind = abi.witness.fields[0].kind
+    assert kind.is_array
+    assert kind.len == 32
+    assert kind.kind == FieldType(type="fp")
+
+
+def test_parses_on_chain_binding():
+    data = sample_abi()
+    data["on_chain"] = {"chain_id": 421614, "contract_address": "0x" + "aa" * 20}
+    abi = parse_abi_schema(json.dumps(data))
+    assert abi.on_chain is not None
+    assert abi.on_chain.chain_id == 421614
+
+
+@pytest.mark.parametrize(
+    "system", ["halo2_ipa", "halo2_kzg_groth16_wrap", "halo2_kzg", "stark_fri"]
+)
+def test_accepts_all_proving_systems(system):
+    data = sample_abi()
+    data["proof"]["proving_system"] = system
+    assert parse_abi_schema(json.dumps(data)).proof.proving_system == system
+
+
+def test_rejects_unknown_proving_system():
+    data = sample_abi()
+    data["proof"]["proving_system"] = "groth16"
+    with pytest.raises(ValueError, match="unknown proving system"):
+        parse_abi_schema(json.dumps(data))
+
+
+def test_rejects_wrong_abi_version():
+    data = sample_abi()
+    data["abi_version"] = 99
+    with pytest.raises(ValueError, match="unsupported abi_version"):
+        parse_abi_schema(json.dumps(data))
+
+
+def test_rejects_public_input_count_mismatch():
+    data = sample_abi()
+    data["circuit"]["num_public_inputs"] = 5
+    with pytest.raises(ValueError, match="num_public_inputs"):
+        parse_abi_schema(json.dumps(data))
+
+
+def test_rejects_witness_count_mismatch():
+    data = sample_abi()
+    data["circuit"]["num_private_witnesses"] = 5
+    with pytest.raises(ValueError, match="num_private_witnesses"):
+        parse_abi_schema(json.dumps(data))
+
+
+def test_rejects_malformed_json():
+    with pytest.raises(ValueError, match="not valid JSON"):
+        parse_abi_schema("{not json")
+
+
+def test_array_field_missing_kind_or_len_raises_value_error():
+    data = sample_abi()
+    data["witness"]["fields"][0]["kind"] = {"type": "array", "kind": {"type": "fp"}}  # no len
+    with pytest.raises(ValueError, match="requires `kind` and `len`"):
+        parse_abi_schema(json.dumps(data))
+
+
+def test_rejects_unknown_field_type_tag():
+    data = sample_abi()
+    data["witness"]["fields"][0]["kind"] = {"type": "u256"}
+    with pytest.raises(ValueError, match="unknown field type tag"):
+        parse_abi_schema(json.dumps(data))
+
+
+def test_rejects_unknown_visibility():
+    data = sample_abi()
+    data["witness"]["fields"][0]["visibility"] = "hidden"
+    with pytest.raises(ValueError, match="unknown visibility"):
+        parse_abi_schema(json.dumps(data))
+
+
+def test_field_type_validates_array_shape():
+    with pytest.raises(ValueError, match="requires `kind` and `len`"):
+        FieldType(type="array")
+    with pytest.raises(ValueError, match="takes no"):
+        FieldType(type="fp", len=3)