seismic-web3 0.1.0__tar.gz

seismic_web3-0.1.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(100 blocks\" errors when the DB lagged behind the in-memory state.:*)"
+    ]
+  }
+}

seismic_web3-0.1.0/.env.example

@@ -0,0 +1,19 @@
+# Seismic integration test configuration
+# Copy to .env and fill in your paths, or export these in your shell.
+#
+# Resolution order for each binary:
+#   1. Specific root env var (SFOUNDRY_ROOT / SRETH_ROOT)
+#   2. SEISMIC_WORKSPACE fallback (derives paths from workspace layout)
+#
+# You only need to set ONE of the following:
+#   - SEISMIC_WORKSPACE (if your repos follow the standard layout), OR
+#   - The individual ROOT vars below
+
+# Parent directory containing all seismic-* repos
+# SEISMIC_WORKSPACE=~/code/seismic-workspace
+
+# Seismic Foundry repo root (binary: target/debug/sanvil)
+# SFOUNDRY_ROOT=~/code/seismic-workspace/seismic-foundry
+
+# Seismic Reth repo root (binary: target/debug/seismic-reth)
+# SRETH_ROOT=~/code/seismic-workspace/seismic-reth

seismic_web3-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+.venv/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Tools
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+
+# Environment
+.env

seismic_web3-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

seismic_web3-0.1.0/DEVELOPMENT.md

@@ -0,0 +1,150 @@
+# Development
+
+## Prerequisites
+
+- **Python 3.10+**
+- **[uv](https://docs.astral.sh/uv/)** — install with `curl -LsSf https://astral.sh/uv/install.sh | sh`
+
+## Environment Variables for Integration Tests
+
+Integration tests start a local sanvil or seismic-reth node and need to know where the binaries are. Set **one** of the following:
+
+| Variable | Description |
+|----------|-------------|
+| `SEISMIC_WORKSPACE` | Parent directory containing `seismic-foundry/` and `seismic-reth/` repos |
+| `SFOUNDRY_ROOT` | Path to seismic-foundry repo root (overrides `SEISMIC_WORKSPACE` for sanvil) |
+| `SRETH_ROOT` | Path to seismic-reth repo root (overrides `SEISMIC_WORKSPACE` for reth) |
+
+The binaries are resolved as:
+- **sanvil**: `$SFOUNDRY_ROOT/target/debug/sanvil` or `$SEISMIC_WORKSPACE/seismic-foundry/target/debug/sanvil`
+- **seismic-reth**: `$SRETH_ROOT/target/debug/seismic-reth` or `$SEISMIC_WORKSPACE/seismic-reth/target/debug/seismic-reth`
+
+Quick setup:
+
+```bash
+# Option 1: Set workspace root (works for both)
+export SEISMIC_WORKSPACE=~/code/seismic-workspace
+
+# Option 2: Set individual roots
+export SFOUNDRY_ROOT=~/code/seismic-workspace/seismic-foundry
+export SRETH_ROOT=~/code/seismic-workspace/seismic-reth
+```
+
+See `.env.example` for a template you can copy to `.env`.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `make install` | Install all dependencies into venv |
+| `make fmt` | Format code with ruff |
+| `make fmt-check` | Check formatting without changes |
+| `make lint` | Run ruff linter |
+| `make typecheck` | Run ty type checker |
+| `make test` | Run unit tests (no node required) |
+| `make test-integration-anvil` | Run integration tests against sanvil |
+| `make test-integration-reth` | Run integration tests against seismic-reth |
+| `make test-all` | Run all tests (unit + integration) |
+| `make ci` | Run all CI checks (fmt-check + lint + typecheck + unit tests) |
+
+## Running CI Locally
+
+```bash
+./ci.sh                    # Full CI: lint, typecheck, unit + integration tests
+./ci.sh --no-anvil         # Skip anvil integration tests
+./ci.sh --no-reth          # Skip reth integration tests
+./ci.sh --no-integration   # Skip all integration tests (unit only)
+```
+
+## Publishing to PyPI
+
+```bash
+# Build
+uv build
+
+# Publish (requires authentication)
+uv publish
+
+# Or with token
+uv publish --token <PYPI_TOKEN>
+```
+
+## Project Structure
+
+```
+clients/py/
+├── pyproject.toml
+├── Makefile
+├── ci.sh
+├── .python-version
+├── src/
+│   └── seismic_web3/
+│       ├── __init__.py              # Public API exports
+│       ├── _types.py                # PrivateKey, Bytes32, etc.
+│       ├── chains.py                # ChainConfig, SEISMIC_TESTNET, SANVIL
+│       ├── client.py                # create_shielded_web3, EncryptionState
+│       ├── module.py                # SeismicNamespace (w3.seismic)
+│       ├── transaction_types.py     # SeismicSecurityParams, TxSeismic types
+│       ├── py.typed                 # PEP 561 type marker
+│       ├── abis/
+│       │   ├── __init__.py           # Re-exports SRC20_ABI, DIRECTORY_ABI
+│       │   ├── deposit_contract.py   # Deposit contract ABI + helpers
+│       │   ├── directory.py          # Directory genesis contract ABI
+│       │   └── src20.py              # ISRC20 interface ABI + events
+│       ├── contract/
+│       │   ├── abi.py               # ABI encoding, shielded type remapping
+│       │   └── shielded.py          # ShieldedContract (5-namespace pattern)
+│       ├── crypto/
+│       │   ├── aes.py               # AES-GCM encryption
+│       │   ├── ecdh.py              # ECDH key agreement
+│       │   ├── nonce.py             # Nonce generation
+│       │   └── secp.py              # secp256k1 utilities
+│       ├── src20/
+│       │   ├── __init__.py           # Re-exports public API
+│       │   ├── types.py              # DecryptedTransferLog, DecryptedApprovalLog
+│       │   ├── crypto.py             # AES-GCM decryption of encrypted amounts
+│       │   ├── directory.py          # Directory contract helpers (viewing keys)
+│       │   └── watch.py              # SRC20EventWatcher, factory functions
+│       ├── precompiles/
+│       │   ├── _base.py             # Precompile framework (call, gas helpers)
+│       │   ├── rng.py               # RNG precompile (0x64)
+│       │   ├── ecdh.py              # ECDH precompile (0x65)
+│       │   ├── aes.py               # AES encrypt/decrypt (0x66, 0x67)
+│       │   ├── hkdf.py              # HKDF precompile (0x68)
+│       │   └── secp256k1.py         # secp256k1 sign precompile (0x69)
+│       └── transaction/
+│           ├── aead.py              # AAD construction
+│           ├── eip712.py            # EIP-712 typed data signing
+│           ├── metadata.py          # Transaction metadata
+│           ├── send.py              # send_shielded_transaction, signed_call
+│           └── serialize.py         # RLP serialization
+└── tests/
+    ├── test_abi.py
+    ├── test_chains.py
+    ├── test_client.py
+    ├── test_contract.py
+    ├── test_crypto.py
+    ├── test_eip712.py
+    ├── test_encryption.py
+    ├── test_module.py
+    ├── test_rpc.py
+    ├── test_send.py
+    ├── test_serialize.py
+    ├── test_transaction_types.py
+    ├── test_precompiles.py
+    ├── test_types.py
+    ├── test_deposit_helpers.py
+    └── integration/
+        ├── conftest.py
+        ├── contracts.py
+        ├── artifacts/                # Compiled contract JSON
+        ├── test_deposit_contract.py
+        ├── test_directory.py
+        ├── test_client_factory.py
+        ├── test_namespace.py
+        ├── test_precompiles.py
+        ├── test_seismic_counter.py
+        ├── test_src20_events.py
+        ├── test_src20_token.py
+        └── test_transparent_counter.py
+```

seismic_web3-0.1.0/Makefile

@@ -0,0 +1,30 @@
+.PHONY: install lint fmt fmt-check typecheck test test-integration-anvil test-integration-reth test-all ci
+
+install: ## Install all dependencies into venv
+	uv sync --all-extras --dev
+
+lint: ## Run ruff linter
+	uv run ruff check src/ tests/
+
+fmt: ## Format code with ruff
+	uv run ruff format src/ tests/
+
+fmt-check: ## Check formatting without making changes
+	uv run ruff format --check src/ tests/
+
+typecheck: ## Run ty type checker
+	uv run ty check src/
+
+test: ## Run unit tests (no node required)
+	uv run pytest tests/ -v --ignore=tests/integration
+
+test-integration-anvil: ## Run integration tests against sanvil
+	CHAIN=anvil uv run pytest tests/integration/ -v --timeout=120
+
+test-integration-reth: ## Run integration tests against seismic-reth
+	CHAIN=reth uv run pytest tests/integration/ -v --timeout=120
+
+test-all: ## Run all tests (unit + integration)
+	uv run pytest tests/ -v --timeout=120
+
+ci: fmt-check lint typecheck test ## Run all CI checks

seismic_web3-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: seismic-web3
+Version: 0.1.0
+Summary: Seismic Python SDK — web3.py extensions for the Seismic privacy-enabled EVM
+Project-URL: Documentation, https://docs.seismic.systems/clients/python
+Project-URL: Repository, https://github.com/SeismicSystems/seismic
+Project-URL: Source, https://github.com/SeismicSystems/seismic/tree/main/clients/py
+Author: Seismic Systems
+License-Expression: MIT
+Keywords: blockchain,ethereum,evm,privacy,seismic,web3
+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: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: coincurve>=20.0
+Requires-Dist: cryptography>=43.0
+Requires-Dist: web3<8,>=7.0
+Description-Content-Type: text/markdown
+
+# seismic-web3
+
+Python SDK for [Seismic](https://seismic.systems), built on [web3.py](https://github.com/ethereum/web3.py). Requires **Python 3.10+**.
+
+```bash
+pip install seismic-web3
+```
+
+## Quick start
+
+```python
+from seismic_web3 import SEISMIC_TESTNET, PrivateKey
+
+pk = PrivateKey(bytes.fromhex("YOUR_PRIVATE_KEY_HEX"))
+
+w3 = SEISMIC_TESTNET.create_client(pk)
+
+contract = w3.seismic.contract(address="0x...", abi=ABI)
+
+# Shielded write — calldata is encrypted (TxSeismic type 0x4a)
+tx_hash = contract.write.setNumber(42)
+receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
+
+# Shielded read — signed, encrypted eth_call
+result = contract.read.getNumber()
+```
+
+`ShieldedContract` exposes five namespaces:
+
+| Namespace | What it does | On-chain visibility |
+|-----------|-------------|-------------------|
+| `.write` | Encrypted transaction (`TxSeismic` type `0x4a`) | Calldata hidden |
+| `.read` | Encrypted signed `eth_call` | Calldata + result hidden |
+| `.twrite` | Standard `eth_sendTransaction` | Calldata visible |
+| `.tread` | Standard `eth_call` | Calldata visible |
+| `.dwrite` | Debug write — returns plaintext + encrypted views | Calldata hidden |
+
+Both sync and async clients are supported. See the full documentation for details.
+
+## Documentation
+
+Full docs are hosted on GitBook: **[docs.seismic.systems/clients/python](https://docs.seismic.systems/clients/python)**
+
+## Contributing
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for local setup, running tests, and publishing.

seismic_web3-0.1.0/README.md

@@ -0,0 +1,46 @@
+# seismic-web3
+
+Python SDK for [Seismic](https://seismic.systems), built on [web3.py](https://github.com/ethereum/web3.py). Requires **Python 3.10+**.
+
+```bash
+pip install seismic-web3
+```
+
+## Quick start
+
+```python
+from seismic_web3 import SEISMIC_TESTNET, PrivateKey
+
+pk = PrivateKey(bytes.fromhex("YOUR_PRIVATE_KEY_HEX"))
+
+w3 = SEISMIC_TESTNET.create_client(pk)
+
+contract = w3.seismic.contract(address="0x...", abi=ABI)
+
+# Shielded write — calldata is encrypted (TxSeismic type 0x4a)
+tx_hash = contract.write.setNumber(42)
+receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
+
+# Shielded read — signed, encrypted eth_call
+result = contract.read.getNumber()
+```
+
+`ShieldedContract` exposes five namespaces:
+
+| Namespace | What it does | On-chain visibility |
+|-----------|-------------|-------------------|
+| `.write` | Encrypted transaction (`TxSeismic` type `0x4a`) | Calldata hidden |
+| `.read` | Encrypted signed `eth_call` | Calldata + result hidden |
+| `.twrite` | Standard `eth_sendTransaction` | Calldata visible |
+| `.tread` | Standard `eth_call` | Calldata visible |
+| `.dwrite` | Debug write — returns plaintext + encrypted views | Calldata hidden |
+
+Both sync and async clients are supported. See the full documentation for details.
+
+## Documentation
+
+Full docs are hosted on GitBook: **[docs.seismic.systems/clients/python](https://docs.seismic.systems/clients/python)**
+
+## Contributing
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for local setup, running tests, and publishing.

seismic_web3-0.1.0/TODO.md

@@ -0,0 +1,12 @@
+# seismic-web3 TODO
+
+Deferred features not included in the initial SDK implementation.
+
+## Block Explorer URL Helpers
+
+- Generate URLs for addresses, transactions, tokens, blocks
+- Support for SeismicScan explorer
+
+## Faucet Interaction
+
+- Request testnet ETH from the Seismic faucet

seismic_web3-0.1.0/ci.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")"
+
+# ---------------------------------------------------------------------------
+# Flags
+# ---------------------------------------------------------------------------
+run_anvil=true
+run_reth=true
+
+usage() {
+  cat <<EOF
+Usage: $0 [OPTIONS]
+
+Run CI checks: lint, typecheck, unit tests, and integration tests.
+
+Options:
+  --no-anvil, -A    Skip anvil integration tests
+  --no-reth,  -R    Skip reth integration tests
+  --no-integration, -I  Skip all integration tests
+  -h, --help        Show this help
+EOF
+  exit 0
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -A|--no-anvil)  run_anvil=false ;;
+    -R|--no-reth)   run_reth=false ;;
+    -I|--no-integration) run_anvil=false; run_reth=false ;;
+    -h|--help)      usage ;;
+    *) echo "Unknown option: $1" >&2; usage ;;
+  esac
+  shift
+done
+
+# ---------------------------------------------------------------------------
+# Check binary environment for integration tests
+# ---------------------------------------------------------------------------
+
+if $run_anvil || $run_reth; then
+  if [[ -z "${SEISMIC_WORKSPACE:-}" && -z "${SFOUNDRY_ROOT:-}" && -z "${SRETH_ROOT:-}" ]]; then
+    echo "WARNING: No binary path env vars set (SEISMIC_WORKSPACE, SFOUNDRY_ROOT, SRETH_ROOT)."
+    echo "Integration tests will fail. See .env.example for setup instructions."
+    echo ""
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Static checks + unit tests
+# ---------------------------------------------------------------------------
+
+echo "==> Installing dependencies"
+uv sync --locked --dev
+
+echo "==> Checking formatting"
+uv run ruff format --check src/ tests/
+
+echo "==> Running linter"
+uv run ruff check src/ tests/
+
+echo "==> Running type checker"
+uv run ty check src/
+
+echo "==> Running unit tests"
+uv run pytest tests/ -v --ignore=tests/integration
+
+# ---------------------------------------------------------------------------
+# Integration tests
+# ---------------------------------------------------------------------------
+
+if $run_anvil; then
+  echo ""
+  echo "=========================================="
+  echo "  Integration tests: sanvil (anvil)"
+  echo "=========================================="
+  CHAIN=anvil uv run pytest tests/integration/ -v --timeout=120
+fi
+
+if $run_reth; then
+  echo ""
+  echo "=========================================="
+  echo "  Integration tests: seismic-reth"
+  echo "=========================================="
+  CHAIN=reth uv run pytest tests/integration/ -v --timeout=120
+fi
+
+echo "==> All checks passed"

seismic_web3-0.1.0/pyproject.toml

@@ -0,0 +1,96 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "seismic-web3"
+version = "0.1.0"
+description = "Seismic Python SDK — web3.py extensions for the Seismic privacy-enabled EVM"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Seismic Systems" }]
+keywords = ["seismic", "web3", "ethereum", "evm", "privacy", "blockchain"]
+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",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "web3>=7.0,<8",
+    "coincurve>=20.0",
+    "cryptography>=43.0",
+]
+
+[project.urls]
+Documentation = "https://docs.seismic.systems/clients/python"
+Repository = "https://github.com/SeismicSystems/seismic"
+Source = "https://github.com/SeismicSystems/seismic/tree/main/clients/py"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.11",
+    "ty>=0.0.1a1",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.25",
+    "pytest-timeout>=2.0",
+    "requests>=2.0",
+]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+    "RUF", # ruff-specific rules
+    "SIM", # flake8-simplify
+    "TCH", # flake8-type-checking
+    "ANN", # flake8-annotations
+    "PT",  # flake8-pytest-style
+]
+ignore = [
+    "ANN401",  # allow Any in *args/**kwargs (needed for dynamic ABI args)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+    "ANN",  # don't require type annotations in tests
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.ty.environment]
+python-version = "3.10"
+
+[tool.ty.terminal]
+error-on-warning = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+strict_markers = true
+markers = [
+    "integration: requires a running seismic node",
+]
+filterwarnings = [
+    # Upstream web3.py issues — not fixable on our side:
+    # https://github.com/ethereum/web3.py/issues — web3 uses the legacy websockets API
+    "ignore::DeprecationWarning:websockets.legacy",
+    # https://github.com/ethereum/web3.py/issues — web3 passes deprecated param to aiohttp
+    "ignore::DeprecationWarning:aiohttp.connector",
+]