Stoffel Python SDK Base

.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install Poetry
+      uses: snok/install-poetry@v1
+      with:
+        version: latest
+        virtualenvs-create: true
+        virtualenvs-in-project: true
+
+    - name: Load cached venv
+      id: cached-poetry-dependencies
+      uses: actions/cache@v3
+      with:
+        path: .venv
+        key: venv-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
+
+    - name: Install dependencies
+      if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
+      run: poetry install --no-interaction --no-root
+
+    - name: Install project
+      run: poetry install --no-interaction
+
+    - name: Run tests
+      run: poetry run pytest --cov=stoffel --cov-report=xml
+
+    - name: Run linting
+      run: |
+        poetry run flake8 stoffel/ tests/ examples/
+        poetry run black --check stoffel/ tests/ examples/
+        poetry run isort --check-only stoffel/ tests/ examples/
+
+    - name: Run type checking
+      run: poetry run mypy stoffel/
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v3
+      with:
+        file: ./coverage.xml
+        fail_ci_if_error: true

CLAUDE.md

@@ -0,0 +1,111 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Development Commands
+- `poetry install` - Install dependencies
+- `poetry run pytest` - Run tests
+- `poetry run pytest --cov=stoffel` - Run tests with coverage
+- `poetry run black stoffel/ tests/ examples/` - Format code
+- `poetry run isort stoffel/ tests/ examples/` - Sort imports  
+- `poetry run flake8 stoffel/ tests/ examples/` - Lint code
+- `poetry run mypy stoffel/` - Type check
+
+### Example Commands
+- `poetry run python examples/simple_api_demo.py` - Run simple API demonstration
+- `poetry run python examples/correct_flow.py` - Run complete architecture example
+- `poetry run python examples/vm_example.py` - Run StoffelVM low-level bindings example
+
+## Architecture
+
+This Python SDK provides a clean, high-level interface for the Stoffel framework with proper separation of concerns:
+
+### Main API Components
+
+**StoffelProgram** (`stoffel/program.py`):
+- Handles StoffelLang program compilation and VM operations
+- Manages execution parameters and local testing
+- VM responsibility: compilation, loading, program lifecycle
+
+**StoffelMPCClient** (`stoffel/client.py`):
+- Handles MPC network communication and private data management  
+- Manages secret sharing, result reconstruction, network connections
+- Client responsibility: network communication, private data, MPC operations
+
+### Clean Separation of Concerns
+
+- **VM/Program**: Compilation, execution parameters, local program execution
+- **Client/Network**: MPC communication, secret sharing, result reconstruction  
+- **Coordinator** (optional): MPC orchestration and metadata exchange (not node discovery)
+
+### Core Components (`stoffel/vm/`, `stoffel/mpc/`)
+
+**StoffelVM Integration**:
+- **vm.py**: VirtualMachine class using ctypes FFI to StoffelVM's C API
+- **types.py**: Enhanced with Share types and ShareType enum for MPC integration
+- **exceptions.py**: VM-specific exception hierarchy
+- Uses ctypes to interface with libstoffel_vm shared library
+
+**MPC Types**:
+- **types.py**: Core MPC types (SecretValue, MPCResult, MPCConfig, etc.)
+- Abstract MPC types for high-level interface
+- Exception hierarchy for MPC-specific errors
+
+## Key Design Principles
+
+1. **Simple Public API**: All internal complexity hidden behind intuitive methods
+2. **Proper Abstractions**: Developers don't need to understand secret sharing schemes or protocol details
+3. **Generic Field Operations**: Not tied to specific cryptographic curves
+4. **MPC-as-a-Service**: Client-side interface to MPC networks rather than full protocol implementation
+5. **Clean Architecture**: Clear boundaries between VM, Client, and optional Coordinator
+
+## Network Architecture
+
+- **Direct Connection**: Client connects directly to known MPC nodes
+- **Coordinator (Optional)**: Used for metadata exchange and MPC network orchestration (not discovery)
+- **MPC Nodes**: Handle actual secure computation on secret shares
+- **Client**: Always knows MPC node addresses directly (deployment responsibility)
+
+## FFI Integration
+
+The SDK uses ctypes for FFI integration with:
+- `libstoffel_vm.so/.dylib` - StoffelVM C API 
+- Future: `libmpc_protocols.so/.dylib` - MPC protocols (skeleton implementation)
+
+FFI interfaces based on C headers in `~/Documents/Stoffel-Labs/dev/StoffelVM/` and `~/Documents/Stoffel-Labs/dev/mpc-protocols/`.
+
+## Project Structure
+
+```
+stoffel/
+├── __init__.py          # Main API exports (StoffelProgram, StoffelMPCClient)
+├── program.py           # StoffelLang compilation and VM management
+├── client.py            # MPC network client and communication
+├── compiler.py          # StoffelLang compiler interface
+├── vm/                  # StoffelVM Python bindings
+│   ├── vm.py           # VirtualMachine class with FFI bindings
+│   ├── types.py        # Enhanced with Share types for MPC
+│   └── exceptions.py   # VM-specific exceptions
+└── mpc/                # MPC types and configurations
+    └── types.py        # Core MPC types and exceptions
+
+examples/
+├── README.md           # Examples documentation and architecture overview
+├── simple_api_demo.py  # Minimal usage example (recommended for most users)  
+├── correct_flow.py     # Complete architecture demonstration
+└── vm_example.py       # Advanced VM bindings usage
+
+tests/
+└── test_client.py      # Clean client tests matching final API
+```
+
+## Important Notes
+
+- MPC protocol selection happens via StoffelVM, not direct protocol management
+- Secret sharing schemes are completely abstracted from developers
+- Field operations are generic, not tied to specific curves like BLS12-381  
+- Client configuration requires MPC nodes to be specified directly
+- Coordinator interaction is limited to metadata exchange when needed
+- Examples demonstrate proper separation of concerns and clean API usage