solpython 0.1.0__tar.gz

solpython-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 taco-jpg
+
+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.

solpython-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include pysol/contracts/artifacts *.json

solpython-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: solpython
+Version: 0.1.0
+Summary: Python-to-EVM compiler — run Python on-chain via a Solidity smart contract pipeline
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: web3>=6.0
+Requires-Dist: eth-tester>=0.10.0
+Requires-Dist: py-evm>=0.10.0
+Provides-Extra: build
+Requires-Dist: py-solc-x>=2.0; extra == "build"
+Dynamic: license-file
+
+# solpython
+
+A Python-to-EVM compiler written entirely in Solidity. Feed it Python source code as a string, get EVM-compatible bytecode out — no off-chain tooling required.
+
+644 tests across 46 test suites.
+
+## Architecture
+
+Six-phase compiler pipeline, each phase implemented as a Solidity contract:
+
+```
+Python source (string)
+       │
+       ▼
+  ┌──────────┐
+  │  Lexer   │  Tokenizes source into token stream
+  └────┬─────┘
+       │ Token[]
+       ▼
+  ┌──────────┐
+  │  Parser  │  Recursive descent → AST (struct array in storage)
+  └────┬─────┘
+       │ ASTNode[]
+       ▼
+  ┌───────────────┐
+  │   Semantic    │  Symbol table, scope resolution, type inference
+  │   Analyzer    │
+  └────┬──────────┘
+       │
+       ▼
+  ┌───────────────┐
+  │     Code      │  AST → custom stack-based bytecode
+  │   Generator   │
+  └────┬──────────┘
+       │ bytes (bytecode)
+       ▼
+  ┌──────────┐
+  │    VM    │  Stack machine executes bytecode
+  └──────────┘
+```
+
+Alternative backends:
+- **Solidity Backend** — AST → Solidity source code transpiler
+- **Yul Backend** — AST → Yul IR transpiler
+
+## Supported Python Features
+
+**Core:**
+- Integer arithmetic (`+`, `-`, `*`, `/`, `//`, `%`, `**`) with negative numbers
+- Augmented assignment (`+=`, `-=`, `*=`, `/=`)
+- Comparisons (`==`, `!=`, `<`, `>`, `<=`, `>=`, `is`, `is not`)
+- Chained comparisons (`a < b < c`)
+- Boolean operators (`and`, `or`, `not`)
+- Ternary expressions (`a if cond else b`)
+- `if` / `elif` / `else`
+- `while` loops
+- `for` loops with `range()`, list iteration, `break`, `continue`
+- `for...else` / `while...else`
+- Function definitions with recursion, default parameters, keyword arguments
+- Nested function definitions
+- `return` statements
+- `pass` statement
+
+**Data Types:**
+- Integers (tagged, -2^62 to 2^62-1)
+- Booleans (`True`, `False`) with proper tagging
+- `None` type with safety checks
+- Strings with methods (`upper`, `lower`, `split`, `contains`, `charAt`, slice)
+- Lists with indexing, negative indexing, `len()`, `append()`
+- Dicts with string/int keys, `items()`, `values()`, `get()`, `update()`
+- Sets with `add()`, `remove()`, `in` operator
+- Tuples with unpacking (`a, b = 1, 2`)
+- Float (6-digit fixed-point)
+
+**Builtins:**
+- `print()` — integer and string output
+- `len()`, `type()`, `isinstance()`
+- `range()`, `enumerate()`, `zip()`
+- `map()`, `filter()`
+- `sorted()`, `reversed()`
+- `abs()`, `min()`, `max()`
+- f-strings and `%s`/`%d` formatting
+
+**Advanced:**
+- `try` / `except` / `finally` / `raise`
+- `class` with methods, `self`, single inheritance
+- `import` / `from...import` with static linking
+- `global` / `nonlocal` keywords
+- Virtual file system (VFS) for module loading
+- Garbage collection (reference counting)
+- Constant folding and dead code elimination
+- Structured error messages with line/column info
+
+## Build & Test
+
+Requires [Foundry](https://book.getfoundry.sh/).
+
+```shell
+forge build          # compile
+forge test           # run all 644 tests
+forge test -vvv      # verbose output
+forge test --match-test testFibonacci   # run a single test
+```
+
+## Example
+
+```python
+def fib(n):
+    if n <= 1:
+        return n
+    return fib(n - 1) + fib(n - 2)
+
+print(fib(10))  # → 55
+```
+
+This compiles to bytecode that runs entirely on-chain via the Solidity VM contract.
+
+## Project Structure
+
+```
+src/
+  types/                  AST node, token, and type info structs
+  libraries/              String utility library
+  phases/
+    Lexer.sol             Tokenizer
+    Parser.sol            Recursive descent parser
+    SemanticAnalyzer.sol  Symbol table, scope resolution
+    CodeGenerator.sol     AST → bytecode
+    VM.sol                Stack-based bytecode interpreter
+    SolidityBackend.sol   AST → Solidity source transpiler
+    YulBackend.sol        AST → Yul IR transpiler
+  optimizer/
+    ConstantFolder.sol    Compile-time constant folding
+  gc/
+    RefCounter.sol        Reference counting GC
+  vfs/
+    VFS.sol               Virtual file system
+  venv/
+    Venv.sol              Compilation environment
+  PythonCompiler.sol      Top-level orchestrator
+
+test/
+  46 test suites covering lexer, parser, semantic analysis,
+  code generation, VM execution, and end-to-end integration.
+
+  Key files:
+    Integration.t.sol     End-to-end compiler tests (fibonacci, fizzbuzz, bubble sort)
+    E2E.t.sol             Feature-specific end-to-end tests
+    TypeClassify.t.sol    Type system and tagging verification
+    Exception.t.sol       Exception handling tests
+    GC.t.sol              Garbage collection tests
+```
+
+## Value Tagging
+
+The VM uses a tagged value system to distinguish types:
+
+| Type     | Tag                        | Range                         |
+|----------|----------------------------|-------------------------------|
+| Integer  | (none)                     | -2^62 to 2^62-1              |
+| Boolean  | BOOL_OFFSET (2^66)         | 2^66 (False), 2^66+1 (True)  |
+| None     | NONE_VALUE                 | Fixed sentinel                |
+| Float    | Tag at bits 252-255        | 6-digit fixed-point           |
+| List     | ID 0 to 2^60-1             | GC-tracked                    |
+| Dict     | ID 2^60 to 2^61-1          | GC-tracked                    |
+| Set      | ID 2^61 to 2^62-1          | GC-tracked                    |
+| String   | ID >= 2^62                 | Static + runtime              |
+
+## Known Limitations
+
+- No generators/iterators
+- No class inheritance beyond single-level
+- No closures (inner functions cannot capture outer variables)
+- Float arithmetic uses 6-digit fixed-point, not IEEE 754
+- GC is reference counting only (no cycle detection)
+- Solidity/Yul backends don't support all features (see `BACKEND_LIMITATIONS.md`)
+
+## License
+
+MIT

solpython-0.1.0/README.md

@@ -0,0 +1,180 @@
+# solpython
+
+A Python-to-EVM compiler written entirely in Solidity. Feed it Python source code as a string, get EVM-compatible bytecode out — no off-chain tooling required.
+
+644 tests across 46 test suites.
+
+## Architecture
+
+Six-phase compiler pipeline, each phase implemented as a Solidity contract:
+
+```
+Python source (string)
+       │
+       ▼
+  ┌──────────┐
+  │  Lexer   │  Tokenizes source into token stream
+  └────┬─────┘
+       │ Token[]
+       ▼
+  ┌──────────┐
+  │  Parser  │  Recursive descent → AST (struct array in storage)
+  └────┬─────┘
+       │ ASTNode[]
+       ▼
+  ┌───────────────┐
+  │   Semantic    │  Symbol table, scope resolution, type inference
+  │   Analyzer    │
+  └────┬──────────┘
+       │
+       ▼
+  ┌───────────────┐
+  │     Code      │  AST → custom stack-based bytecode
+  │   Generator   │
+  └────┬──────────┘
+       │ bytes (bytecode)
+       ▼
+  ┌──────────┐
+  │    VM    │  Stack machine executes bytecode
+  └──────────┘
+```
+
+Alternative backends:
+- **Solidity Backend** — AST → Solidity source code transpiler
+- **Yul Backend** — AST → Yul IR transpiler
+
+## Supported Python Features
+
+**Core:**
+- Integer arithmetic (`+`, `-`, `*`, `/`, `//`, `%`, `**`) with negative numbers
+- Augmented assignment (`+=`, `-=`, `*=`, `/=`)
+- Comparisons (`==`, `!=`, `<`, `>`, `<=`, `>=`, `is`, `is not`)
+- Chained comparisons (`a < b < c`)
+- Boolean operators (`and`, `or`, `not`)
+- Ternary expressions (`a if cond else b`)
+- `if` / `elif` / `else`
+- `while` loops
+- `for` loops with `range()`, list iteration, `break`, `continue`
+- `for...else` / `while...else`
+- Function definitions with recursion, default parameters, keyword arguments
+- Nested function definitions
+- `return` statements
+- `pass` statement
+
+**Data Types:**
+- Integers (tagged, -2^62 to 2^62-1)
+- Booleans (`True`, `False`) with proper tagging
+- `None` type with safety checks
+- Strings with methods (`upper`, `lower`, `split`, `contains`, `charAt`, slice)
+- Lists with indexing, negative indexing, `len()`, `append()`
+- Dicts with string/int keys, `items()`, `values()`, `get()`, `update()`
+- Sets with `add()`, `remove()`, `in` operator
+- Tuples with unpacking (`a, b = 1, 2`)
+- Float (6-digit fixed-point)
+
+**Builtins:**
+- `print()` — integer and string output
+- `len()`, `type()`, `isinstance()`
+- `range()`, `enumerate()`, `zip()`
+- `map()`, `filter()`
+- `sorted()`, `reversed()`
+- `abs()`, `min()`, `max()`
+- f-strings and `%s`/`%d` formatting
+
+**Advanced:**
+- `try` / `except` / `finally` / `raise`
+- `class` with methods, `self`, single inheritance
+- `import` / `from...import` with static linking
+- `global` / `nonlocal` keywords
+- Virtual file system (VFS) for module loading
+- Garbage collection (reference counting)
+- Constant folding and dead code elimination
+- Structured error messages with line/column info
+
+## Build & Test
+
+Requires [Foundry](https://book.getfoundry.sh/).
+
+```shell
+forge build          # compile
+forge test           # run all 644 tests
+forge test -vvv      # verbose output
+forge test --match-test testFibonacci   # run a single test
+```
+
+## Example
+
+```python
+def fib(n):
+    if n <= 1:
+        return n
+    return fib(n - 1) + fib(n - 2)
+
+print(fib(10))  # → 55
+```
+
+This compiles to bytecode that runs entirely on-chain via the Solidity VM contract.
+
+## Project Structure
+
+```
+src/
+  types/                  AST node, token, and type info structs
+  libraries/              String utility library
+  phases/
+    Lexer.sol             Tokenizer
+    Parser.sol            Recursive descent parser
+    SemanticAnalyzer.sol  Symbol table, scope resolution
+    CodeGenerator.sol     AST → bytecode
+    VM.sol                Stack-based bytecode interpreter
+    SolidityBackend.sol   AST → Solidity source transpiler
+    YulBackend.sol        AST → Yul IR transpiler
+  optimizer/
+    ConstantFolder.sol    Compile-time constant folding
+  gc/
+    RefCounter.sol        Reference counting GC
+  vfs/
+    VFS.sol               Virtual file system
+  venv/
+    Venv.sol              Compilation environment
+  PythonCompiler.sol      Top-level orchestrator
+
+test/
+  46 test suites covering lexer, parser, semantic analysis,
+  code generation, VM execution, and end-to-end integration.
+
+  Key files:
+    Integration.t.sol     End-to-end compiler tests (fibonacci, fizzbuzz, bubble sort)
+    E2E.t.sol             Feature-specific end-to-end tests
+    TypeClassify.t.sol    Type system and tagging verification
+    Exception.t.sol       Exception handling tests
+    GC.t.sol              Garbage collection tests
+```
+
+## Value Tagging
+
+The VM uses a tagged value system to distinguish types:
+
+| Type     | Tag                        | Range                         |
+|----------|----------------------------|-------------------------------|
+| Integer  | (none)                     | -2^62 to 2^62-1              |
+| Boolean  | BOOL_OFFSET (2^66)         | 2^66 (False), 2^66+1 (True)  |
+| None     | NONE_VALUE                 | Fixed sentinel                |
+| Float    | Tag at bits 252-255        | 6-digit fixed-point           |
+| List     | ID 0 to 2^60-1             | GC-tracked                    |
+| Dict     | ID 2^60 to 2^61-1          | GC-tracked                    |
+| Set      | ID 2^61 to 2^62-1          | GC-tracked                    |
+| String   | ID >= 2^62                 | Static + runtime              |
+
+## Known Limitations
+
+- No generators/iterators
+- No class inheritance beyond single-level
+- No closures (inner functions cannot capture outer variables)
+- Float arithmetic uses 6-digit fixed-point, not IEEE 754
+- GC is reference counting only (no cycle detection)
+- Solidity/Yul backends don't support all features (see `BACKEND_LIMITATIONS.md`)
+
+## License
+
+MIT

solpython-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "solpython"
+version = "0.1.0"
+description = "Python-to-EVM compiler — run Python on-chain via a Solidity smart contract pipeline"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = [
+    "web3>=6.0",
+    "eth-tester>=0.10.0",
+    "py-evm>=0.10.0",
+]
+
+[project.optional-dependencies]
+build = ["py-solc-x>=2.0"]
+
+[project.scripts]
+solpython = "pysol.cli.main:main"
+pysol-compile = "pysol.build:build"
+
+[tool.setuptools.packages.find]
+include = ["pysol*"]
+
+[tool.setuptools.package-data]
+pysol = ["contracts/artifacts/*.json"]

solpython-0.1.0/pysol/__init__.py

@@ -0,0 +1,3 @@
+"""solpython — Python-to-EVM compiler, runs Python on-chain."""
+
+__version__ = "0.1.0"

solpython-0.1.0/pysol/build.py

@@ -0,0 +1,144 @@
+"""Compile Solidity contracts and produce JSON artifacts for the Python package."""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+SOLC_VERSION = "0.8.20"
+SRC_DIR = Path(__file__).parent.parent / "src"
+ARTIFACTS_DIR = Path(__file__).parent / "contracts" / "artifacts"
+
+# Contracts we need to deploy from Python
+TARGET_CONTRACTS = ["PythonCompiler", "VM"]
+
+
+def _find_solc() -> str:
+    """Find solc binary — try solcx, then system solc, then forge."""
+    try:
+        import solcx
+        solcx.install_solc(SOLC_VERSION)
+        return str(Path(solcx.get_solcx_install_folder()) / f"solc-{SOLC_VERSION}")
+    except ImportError:
+        pass
+
+    # Try system solc
+    result = subprocess.run(["which", "solc"], capture_output=True, text=True)
+    if result.returncode == 0:
+        return result.stdout.strip()
+
+    # Try forge
+    result = subprocess.run(["which", "forge"], capture_output=True, text=True)
+    if result.returncode == 0:
+        # Use forge to compile, then extract artifacts
+        return "forge"
+
+    print("Error: No Solidity compiler found.")
+    print("Install one of:")
+    print("  pip install py-solc-x")
+    print("  brew install solidity  (or equivalent)")
+    print("  curl -L https://foundry.paradigm.xyz | bash && foundryup")
+    sys.exit(1)
+
+
+def _compile_with_forge():
+    """Compile using Foundry and extract artifacts."""
+    project_dir = Path(__file__).parent.parent
+    result = subprocess.run(
+        ["forge", "build"],
+        cwd=project_dir,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        print(f"Forge build failed:\n{result.stderr}")
+        sys.exit(1)
+
+    ARTIFACTS_DIR.mkdir(parents=True, exist_ok=True)
+
+    for name in TARGET_CONTRACTS:
+        # Foundry stores artifacts in out/ContractName.sol/ContractName.json
+        artifact_path = project_dir / "out" / f"{name}.sol" / f"{name}.json"
+        if not artifact_path.exists():
+            print(f"Warning: artifact not found at {artifact_path}")
+            continue
+
+        data = json.loads(artifact_path.read_text())
+        # Extract just abi and bytecode
+        output = {
+            "abi": data.get("abi", []),
+            "bytecode": data.get("bytecode", {}).get("object", ""),
+        }
+        out_path = ARTIFACTS_DIR / f"{name}.json"
+        out_path.write_text(json.dumps(output, indent=2))
+        print(f"  Wrote {out_path}")
+
+
+def _compile_with_solcx(solc_path: str):
+    """Compile using solcx."""
+    import solcx
+
+    sources = {}
+    src_dir = SRC_DIR
+
+    # Collect all .sol files
+    for sol_file in src_dir.rglob("*.sol"):
+        rel = sol_file.relative_to(src_dir.parent)
+        sources[str(rel)] = {"content": sol_file.read_text()}
+
+    # Need to also find OpenZeppelin or other deps if used
+    # For now, our contracts are self-contained
+
+    output = solcx.compile_standard(
+        {
+            "language": "Solidity",
+            "sources": {k: {"content": v["content"]} for k, v in sources.items()},
+            "settings": {
+                "outputSelection": {
+                    "*": {
+                        "*": ["abi", "evm.bytecode.object"],
+                    }
+                },
+                "remappings": [],
+            },
+        },
+        solc_binary=solc_path,
+        allow_paths=[str(src_dir.parent)],
+    )
+
+    ARTIFACTS_DIR.mkdir(parents=True, exist_ok=True)
+
+    for name in TARGET_CONTRACTS:
+        # Find the contract in the output
+        for source_path, contracts in output.get("contracts", {}).items():
+            if name in contracts:
+                contract = contracts[name]
+                artifact = {
+                    "abi": contract.get("abi", []),
+                    "bytecode": contract.get("evm", {}).get("bytecode", {}).get("object", ""),
+                }
+                if artifact["bytecode"]:
+                    out_path = ARTIFACTS_DIR / f"{name}.json"
+                    out_path.write_text(json.dumps(artifact, indent=2))
+                    print(f"  Wrote {out_path}")
+                    break
+        else:
+            print(f"Warning: contract '{name}' not found in compilation output")
+
+
+def build():
+    """Compile Solidity contracts and generate artifacts."""
+    print("Compiling Solidity contracts...")
+    solc = _find_solc()
+
+    if solc == "forge":
+        _compile_with_forge()
+    else:
+        _compile_with_solcx(solc)
+
+    print("Done!")
+
+
+if __name__ == "__main__":
+    build()

solpython-0.1.0/pysol/cli/main.py

@@ -0,0 +1,104 @@
+"""CLI entry point — mimics CPython's interface."""
+
+import argparse
+import sys
+import os
+from pathlib import Path
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="solpython",
+        description="Python-to-EVM compiler — run Python on-chain",
+    )
+    parser.add_argument("script", nargs="?", help="Python script file to run")
+    parser.add_argument("-c", dest="command", help="Python command to execute")
+    parser.add_argument("-v", "--verbose", action="store_true", help="Show compilation details")
+    parser.add_argument("--version", action="store_true", help="Show version and exit")
+    parser.add_argument("--build", action="store_true", help="Compile Solidity contracts and exit")
+
+    args = parser.parse_args()
+
+    if args.version:
+        from pysol import __version__
+        print(f"solpython {__version__}")
+        return
+
+    if args.build:
+        from pysol.build import build
+        build()
+        return
+
+    if args.command:
+        source = args.command
+        if not source.endswith("\n"):
+            source += "\n"
+        _execute(source, verbose=args.verbose)
+        return
+
+    if args.script:
+        if not os.path.exists(args.script):
+            print(f"solpython: can't open file '{args.script}': No such file or directory")
+            sys.exit(1)
+        source = Path(args.script).read_text()
+        _execute(source, verbose=args.verbose)
+        return
+
+    _repl(verbose=args.verbose)
+
+
+def _execute(source: str, *, verbose: bool = False):
+    from pysol.executor import run
+    try:
+        output = run(source, verbose=verbose)
+        if output:
+            print(output)
+    except FileNotFoundError as e:
+        print(str(e))
+        sys.exit(1)
+    except Exception as e:
+        print(f"solpython: error: {e}", file=sys.stderr)
+        if verbose:
+            import traceback
+            traceback.print_exc()
+        sys.exit(1)
+
+
+def _repl(*, verbose: bool = False):
+    from pysol import __version__
+    print(f"solpython {__version__}")
+    print('Type "exit()" or Ctrl-D to exit.')
+    print()
+
+    while True:
+        try:
+            line = input(">>> ")
+        except (EOFError, KeyboardInterrupt):
+            print()
+            break
+
+        if not line.strip():
+            continue
+        if line.strip() in ("exit()", "quit()"):
+            break
+
+        source = line + "\n"
+        if line.rstrip().endswith(":"):
+            while True:
+                try:
+                    cont = input("... ")
+                except (EOFError, KeyboardInterrupt):
+                    print()
+                    break
+                if not cont.strip():
+                    break
+                source += cont + "\n"
+
+        try:
+            _execute(source, verbose=verbose)
+        except SystemExit:
+            pass
+
+
+if __name__ == "__main__":
+    main()