refactor(python): modernize SDK with Pydantic v2 and modern Python patterns

- Convert dataclasses to Pydantic v2 models with validation
- Use modern type hints (list[X], X | None) for Python 3.10+
- Add environment variable defaults (CASCADE_RPC_URL, CASCADE_PRIVATE_KEY)
- Add custom exception hierarchy (CascadeSplitsError, ConfigurationError, etc.)
- Add PEP 561 py.typed marker for type checker support
- Rename addresses.py to constants.py
- Use relative imports throughout
- Add Python patterns to .gitignore

Author: tenequm

.gitignore

@@ -13,6 +13,17 @@ docker-target
 .env
 tmp
 
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.venv/
+*.egg-info/
+.ruff_cache/
+.pytest_cache/
+.ty/
+
 
 
 .nx/cache

python/splits-sdk-evm/README.md

@@ -1,4 +1,4 @@
-# @cascade-fyi/splits-sdk-python
+# cascade-splits-evm
 
 Python SDK for [Cascade Splits](https://github.com/cascade-protocol/splits) on EVM chains (Base).
 
@@ -9,22 +9,24 @@ Split incoming payments to multiple recipients automatically. Built for high-thr
 ## Installation
 
 ```bash
-pip install cascade-splits
+pip install cascade-splits-evm
 ```
 
 **Requirements:**
-- Python 3.9+
-- `web3` >= 6.0.0
+- Python 3.10+
+- `web3` >= 7.0.0
+- `pydantic` >= 2.0.0
 
 ## Quick Start
 
 ### Create a Split
 
 ```python
-from cascade_splits import CascadeSplitsClient, Recipient
+from cascade_splits_evm import CascadeSplitsClient, Recipient
 import secrets
 
 # Initialize client (Base mainnet)
+# Can also use CASCADE_RPC_URL and CASCADE_PRIVATE_KEY environment variables
 client = CascadeSplitsClient(
     rpc_url="https://mainnet.base.org",
     private_key="0x...",
@@ -91,7 +93,7 @@ Recipient(address="0xBob...", share=40)    # 40% of 99% = 39.6%
 
 ### Discriminated Union Results
 
-All operations return typed results with `status` discriminant:
+All operations return typed Pydantic models with `status` discriminant:
 
 ```python
 # ensure_split results
@@ -118,13 +120,14 @@ EVM splits are **immutable** — recipients cannot be changed after creation. Cr
 ### CascadeSplitsClient
 
 ```python
-from cascade_splits import CascadeSplitsClient
+from cascade_splits_evm import CascadeSplitsClient
 
+# All parameters can be set via environment variables
 client = CascadeSplitsClient(
-    rpc_url="https://mainnet.base.org",
-    private_key="0x...",
-    chain_id=8453,  # Optional, default: 8453 (Base mainnet)
-    factory_address=None,  # Optional, uses default
+    rpc_url="https://mainnet.base.org",  # or CASCADE_RPC_URL env var
+    private_key="0x...",                  # or CASCADE_PRIVATE_KEY env var
+    chain_id=8453,                        # Optional, default: 8453 (Base mainnet)
+    factory_address=None,                 # Optional, uses default
 )
 
 # Properties
@@ -145,7 +148,7 @@ predicted = client.predict_split_address(unique_id, recipients, authority, token
 ### Helper Functions
 
 ```python
-from cascade_splits import (
+from cascade_splits_evm import (
     to_evm_recipient,
     to_evm_recipients,
     is_cascade_split,
@@ -156,7 +159,7 @@ from cascade_splits import (
 )
 
 # Convert share (1-100) to basis points
-recipient = to_evm_recipient(Recipient("0x...", share=50))
+recipient = to_evm_recipient(Recipient(address="0x...", share=50))
 # EvmRecipient(addr="0x...", percentage_bps=4950)
 
 # Check if address is a split
@@ -166,10 +169,10 @@ is_split = is_cascade_split(w3, address)
 balance = get_split_balance(w3, split_address)
 ```
 
-### Address Utilities
+### Constants
 
 ```python
-from cascade_splits import (
+from cascade_splits_evm import (
     get_split_factory_address,
     get_usdc_address,
     is_supported_chain,
@@ -183,10 +186,24 @@ usdc = get_usdc_address(8453)
 supported = is_supported_chain(8453)  # True
 ```
 
+### Exceptions
+
+```python
+from cascade_splits_evm import (
+    CascadeSplitsError,        # Base exception
+    ConfigurationError,         # Missing RPC URL, private key, etc.
+    ChainNotSupportedError,     # Unsupported chain ID
+    TransactionError,           # Transaction failed
+    TransactionRejectedError,   # Wallet rejected transaction
+    TransactionRevertedError,   # Transaction reverted on-chain
+    InsufficientGasError,       # Not enough gas
+)
+```
+
 ## Types
 
 ```python
-from cascade_splits import (
+from cascade_splits_evm import (
     Recipient,          # Input recipient with share (1-100)
     EvmRecipient,       # On-chain format with basis points
     EnsureResult,       # Result of ensure_split
@@ -203,19 +220,14 @@ from cascade_splits import (
 | Base Mainnet | 8453 | `0x946Cd053514b1Ab7829dD8fEc85E0ade5550dcf7` | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
 | Base Sepolia | 84532 | `0x946Cd053514b1Ab7829dD8fEc85E0ade5550dcf7` | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
 
-## ubounty.ai Integration
-
-This SDK is designed for easy integration with payment platforms:
+## Example Integration
 
 ```python
-from cascade_splits import CascadeSplitsClient, Recipient
-import secrets
+from cascade_splits_evm import CascadeSplitsClient, Recipient
+import os
 
-# Initialize client
-client = CascadeSplitsClient(
-    rpc_url="https://mainnet.base.org",
-    private_key=os.environ["PRIVATE_KEY"],
-)
+# Initialize client (uses environment variables)
+client = CascadeSplitsClient()
 
 # Create a split for bounty distribution
 result = client.ensure_split(
@@ -227,7 +239,8 @@ result = client.ensure_split(
 )
 
 # After PR is merged, execute the split
-exec_result = client.execute_split(result.split)
+if result.status == "CREATED" or result.status == "NO_CHANGE":
+    exec_result = client.execute_split(result.split)
 ```
 
 ## Resources

python/splits-sdk-evm/project.json

@@ -0,0 +1,36 @@
+{
+	"name": "cascade-splits-evm-python",
+	"$schema": "../../node_modules/nx/schemas/project-schema.json",
+	"sourceRoot": "python/splits-sdk-evm/src",
+	"projectType": "library",
+	"tags": ["type:sdk", "platform:evm", "lang:python"],
+	"targets": {
+		"format": {
+			"command": "cd python/splits-sdk-evm && uv run ruff format .",
+			"inputs": ["{projectRoot}/**/*.py"],
+			"cache": true
+		},
+		"lint": {
+			"command": "cd python/splits-sdk-evm && uv run ruff check",
+			"inputs": ["{projectRoot}/**/*.py"],
+			"cache": true
+		},
+		"check": {
+			"dependsOn": ["format", "lint"],
+			"command": "cd python/splits-sdk-evm && uv run ty check",
+			"inputs": ["{projectRoot}/**/*.py"],
+			"cache": true
+		},
+		"test": {
+			"command": "cd python/splits-sdk-evm && uv run pytest",
+			"inputs": ["{projectRoot}/**/*.py", "{projectRoot}/tests/**/*.py"],
+			"cache": true
+		},
+		"build": {
+			"command": "cd python/splits-sdk-evm && uv build",
+			"inputs": ["{projectRoot}/**/*.py", "{projectRoot}/pyproject.toml"],
+			"outputs": ["{projectRoot}/dist/**"],
+			"cache": true
+		}
+	}
+}

python/splits-sdk-evm/pyproject.toml

@@ -3,42 +3,57 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [project]
-name = "cascade-splits"
+name = "cascade-splits-evm"
 version = "0.1.0"
 description = "Python SDK for Cascade Splits - Non-custodial payment splitting on Base (EVM)"
 readme = "README.md"
 license = "Apache-2.0"
-requires-python = ">=3.9"
-authors = [
-    { name = "Cascade Protocol", email = "hello@cascade.fyi" }
-]
-keywords = ["ethereum", "base", "payments", "splits", "web3", "usdc"]
+requires-python = ">=3.10"
+authors = [{ name = "Cascade Protocol", email = "hello@cascade.fyi" }]
+keywords = ["ethereum", "evm", "base", "payments", "splits", "web3", "usdc", "cascade"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
 ]
 dependencies = [
-    "web3>=6.0.0",
-    "eth-account>=0.8.0",
-]
-
-[project.optional-dependencies]
-dev = [
-    "pytest>=7.0.0",
-    "pytest-asyncio>=0.21.0",
+    "web3>=7.0.0",
+    "pydantic>=2.0.0",
 ]
 
 [project.urls]
 Homepage = "https://github.com/cascade-protocol/splits"
-Documentation = "https://github.com/cascade-protocol/splits/tree/main/packages/splits-sdk-python"
+Documentation = "https://github.com/cascade-protocol/splits/tree/main/python/splits-sdk-evm"
 Repository = "https://github.com/cascade-protocol/splits"
 
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.8",
+    "ty>=0.0.1a20",
+]
+
 [tool.hatch.build.targets.wheel]
-packages = ["src/cascade_splits"]
+packages = ["src/cascade_splits_evm"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ty.environment]
+python-version = "3.10"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

python/splits-sdk-evm/src/cascade_splits_evm/__init__.py

@@ -1,11 +1,11 @@
 """
-Cascade Splits Python SDK
+Cascade Splits EVM SDK
 
 Non-custodial payment splitting on Base (EVM).
 Automatically distribute incoming payments to multiple recipients.
 
 Usage:
-    from cascade_splits import CascadeSplitsClient, Recipient
+    from cascade_splits_evm import CascadeSplitsClient, Recipient
 
     client = CascadeSplitsClient(
         rpc_url="https://mainnet.base.org",
@@ -21,46 +21,64 @@
     )
 """
 
-from cascade_splits.types import (
-    Recipient,
-    EvmRecipient,
-    EnsureResult,
-    ExecuteResult,
-    ExecutionPreview,
-    SplitConfig,
+from ._exceptions import (
+    CascadeSplitsError,
+    ChainNotSupportedError,
+    ConfigurationError,
+    InsufficientGasError,
+    TransactionError,
+    TransactionRejectedError,
+    TransactionRevertedError,
 )
-from cascade_splits.addresses import (
+from ._version import __version__
+from .client import CascadeSplitsClient
+from .constants import (
     SPLIT_FACTORY_ADDRESSES,
-    USDC_ADDRESSES,
     SUPPORTED_CHAIN_IDS,
+    USDC_ADDRESSES,
     get_split_factory_address,
     get_usdc_address,
     is_supported_chain,
 )
-from cascade_splits.client import CascadeSplitsClient
-from cascade_splits.helpers import (
-    to_evm_recipient,
-    to_evm_recipients,
-    is_cascade_split,
+from .helpers import (
     get_split_balance,
     get_split_config,
     has_pending_funds,
+    is_cascade_split,
     preview_execution,
+    to_evm_recipient,
+    to_evm_recipients,
+)
+from .types import (
+    EnsureResult,
+    EnsureStatus,
+    EvmRecipient,
+    ExecuteResult,
+    ExecuteStatus,
+    ExecutionPreview,
+    FailedReason,
+    Recipient,
+    SkippedReason,
+    SplitConfig,
 )
-
-__version__ = "0.1.0"
 
 __all__ = [
+    # Version
+    "__version__",
     # Client
     "CascadeSplitsClient",
     # Types
     "Recipient",
     "EvmRecipient",
+    "SplitConfig",
     "EnsureResult",
     "ExecuteResult",
     "ExecutionPreview",
-    "SplitConfig",
-    # Addresses
+    "EnsureStatus",
+    "ExecuteStatus",
+    "FailedReason",
+    "SkippedReason",
+    # Constants
     "SPLIT_FACTORY_ADDRESSES",
     "USDC_ADDRESSES",
     "SUPPORTED_CHAIN_IDS",
@@ -75,4 +93,12 @@
     "get_split_config",
     "has_pending_funds",
     "preview_execution",
+    # Exceptions
+    "CascadeSplitsError",
+    "ConfigurationError",
+    "ChainNotSupportedError",
+    "TransactionError",
+    "TransactionRejectedError",
+    "TransactionRevertedError",
+    "InsufficientGasError",
 ]