runar-compiler 0.3.1__tar.gz

runar_compiler-0.3.1/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: runar-compiler
+Version: 0.3.1
+Summary: Runar smart contract compiler - Python implementation
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"

runar_compiler-0.3.1/README.md

@@ -0,0 +1,168 @@
+# Rúnar Python Compiler
+
+**Alternative Rúnar compiler implemented in Python.**
+
+---
+
+## Status
+
+| Phase | Description | Status |
+|---|---|---|
+| **Phase 1** | IR consumer: accepts canonical ANF IR JSON, performs stack lowering and emission (Passes 5-6). | Implemented |
+| **Phase 2** | Full frontend: parses source files directly (Passes 1-4), produces canonical ANF IR. | Implemented |
+
+Phase 1 validates that the Python implementation can produce identical Bitcoin Script from the same ANF IR as the reference compiler. Phase 2 adds an independent frontend that must produce byte-identical ANF IR.
+
+---
+
+## Architecture
+
+### Phase 1: IR Consumer
+
+```
+  ANF IR (JSON)  -->  [Stack Lower]  -->  [Peephole]  -->  [Emit]  -->  Bitcoin Script
+                      Python pass 5      Optimize        Python pass 6
+```
+
+The Python compiler reads canonical ANF IR JSON and performs stack scheduling and opcode emission.
+
+### Phase 2: Full Frontend
+
+```
+  .runar.*  -->  [Parse]  -->  [Validate]  -->  [Typecheck]  -->  [ANF Lower]
+              hand-written    Python pass 2    Python pass 3    Python pass 4
+              parsers
+                                                                     |
+                                                                     v
+                                                                 ANF IR (JSON)
+                                                                     |
+                                                                     v
+            [Stack Lower]  -->  [Peephole]  -->  [Emit]  -->  Bitcoin Script
+            Python pass 5      Optimize        Python pass 6
+```
+
+The Python compiler supports **all six input formats** via hand-written recursive descent parsers — the most of any compiler:
+
+| Extension | Parser Module |
+|-----------|---------------|
+| `.runar.ts` | `frontend/parser_ts.py` |
+| `.runar.sol` | `frontend/parser_sol.py` |
+| `.runar.move` | `frontend/parser_move.py` |
+| `.runar.go` | `frontend/parser_go.py` |
+| `.runar.rs` | `frontend/parser_rust.py` |
+| `.runar.py` | `frontend/parser_python.py` |
+
+All parsers produce the same Rúnar AST (`ContractNode`), and from that point the pipeline is identical.
+
+### Dedicated Codegen Modules
+
+- `codegen/ec.py` — EC point operations (`ecAdd`, `ecMul`, `ecMulGen`, `ecNegate`, `ecOnCurve`, etc.)
+- `codegen/slh_dsa.py` — SLH-DSA (SPHINCS+) signature verification
+- `codegen/optimizer.py` — Peephole optimizer (runs on Stack IR between stack lowering and emit)
+
+### ANF EC Optimizer (Pass 4.5)
+
+The `frontend/anf_optimize.py` module implements 12 algebraic EC simplification rules that run between ANF lowering and stack lowering. This pass is always enabled and eliminates redundant EC operations (e.g., `ecAdd(P, ecNegate(P))` → identity, `ecMul(G, k)` → `ecMulGen(k)`).
+
+---
+
+## Building
+
+No build step required — the compiler is pure Python.
+
+### Prerequisites
+
+- Python 3.10+
+- No external dependencies
+
+---
+
+## Running
+
+```bash
+# Full compilation from source (outputs artifact JSON)
+python -m runar_compiler --source MyContract.runar.ts
+
+# Output only hex
+python -m runar_compiler --source MyContract.runar.ts --hex
+
+# Output only ASM
+python -m runar_compiler --source MyContract.runar.ts --asm
+
+# Dump ANF IR for conformance checking
+python -m runar_compiler --source MyContract.runar.ts --emit-ir
+
+# Write output to a file
+python -m runar_compiler --source MyContract.runar.ts --output artifacts/MyContract.json
+
+# Compile from ANF IR JSON
+python -m runar_compiler --ir input-anf.json
+python -m runar_compiler --ir input-anf.json --hex
+python -m runar_compiler --ir input-anf.json --output artifact.json
+```
+
+---
+
+## Conformance Testing
+
+The Python compiler must pass the same conformance suite as the TypeScript reference compiler.
+
+For each test case in `conformance/tests/`:
+
+1. Read source files as input.
+2. Run the full pipeline (Passes 1-6).
+3. Compare script hex output with `expected-script.hex` (string equality).
+4. If `expected-ir.json` exists, also compile from IR and verify the IR-compiled script matches the source-compiled script.
+
+Conformance tests include multi-format variants (`.runar.sol`, `.runar.move`, `.runar.go`, `.runar.rs`, `.runar.py`) that are all tested through the same pipeline.
+
+```bash
+# Run conformance from repo root
+pnpm run conformance:python
+
+# Or directly
+cd conformance
+python3 -m pytest test_conformance.py -v
+```
+
+---
+
+## Testing
+
+```bash
+cd compilers/python
+python3 -m pytest
+```
+
+---
+
+## Project Structure
+
+```
+runar_compiler/
+  __init__.py
+  __main__.py           # CLI entry point
+  compiler.py           # Pipeline orchestrator (parse → validate → typecheck → ANF → stack → emit)
+  frontend/
+    ast_nodes.py        # Rúnar AST node types (ContractNode, PropertyNode, MethodNode, etc.)
+    parser_dispatch.py  # File extension → parser dispatch
+    parser_ts.py        # .runar.ts parser
+    parser_sol.py       # .runar.sol parser
+    parser_move.py      # .runar.move parser
+    parser_go.py        # .runar.go parser
+    parser_rust.py      # .runar.rs parser
+    parser_python.py    # .runar.py parser
+    validator.py        # Pass 2: Language subset validation
+    typecheck.py        # Pass 3: Type checking
+    anf_lower.py        # Pass 4: AST → ANF IR
+    anf_optimize.py     # Pass 4.5: ANF EC optimizer (12 algebraic rules)
+  ir/
+    types.py            # ANF IR type definitions
+    loader.py           # ANF IR JSON loader
+  codegen/
+    stack.py            # Pass 5: ANF → Stack IR
+    optimizer.py        # Peephole optimizer
+    emit.py             # Pass 6: Stack IR → Bitcoin Script
+    ec.py               # EC point operation codegen
+    slh_dsa.py          # SLH-DSA signature verification codegen
+```

runar_compiler-0.3.1/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "runar-compiler"
+version = "0.3.1"
+description = "Runar smart contract compiler - Python implementation"
+requires-python = ">=3.10"
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

runar_compiler-0.3.1/runar_compiler/__init__.py

@@ -0,0 +1,3 @@
+"""Runar smart contract compiler - Python implementation."""
+
+from runar_compiler.compiler import compile_from_source, compile_from_ir

runar_compiler-0.3.1/runar_compiler/__main__.py

@@ -0,0 +1,198 @@
+"""CLI entry point for the Runar Python compiler.
+
+Usage:
+    python -m runar_compiler --source Contract.runar.py --output artifact.json
+    python -m runar_compiler --ir program.json --output artifact.json
+    python -m runar_compiler --source Contract.runar.py --hex
+    python -m runar_compiler --source Contract.runar.py --asm
+    python -m runar_compiler --source Contract.runar.py --emit-ir
+
+Direct port of ``compilers/go/main.go``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from runar_compiler.compiler import (
+    CompilationError,
+    artifact_to_json,
+    compile_from_ir,
+    compile_from_source,
+    compile_source_to_ir,
+)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="runar-compiler-python",
+        description="Runar smart contract compiler (Python implementation).",
+    )
+    parser.add_argument(
+        "--ir",
+        metavar="PATH",
+        help="Path to ANF IR JSON file",
+    )
+    parser.add_argument(
+        "--source",
+        metavar="PATH",
+        help="Path to .runar.* source file",
+    )
+    parser.add_argument(
+        "--output",
+        metavar="PATH",
+        help="Output artifact path (default: stdout)",
+    )
+    parser.add_argument(
+        "--hex",
+        action="store_true",
+        help="Output only the script hex (no artifact JSON)",
+    )
+    parser.add_argument(
+        "--asm",
+        action="store_true",
+        help="Output only the script ASM (no artifact JSON)",
+    )
+    parser.add_argument(
+        "--emit-ir",
+        action="store_true",
+        help="Output only the ANF IR JSON (requires --source)",
+    )
+    parser.add_argument(
+        "--disable-constant-folding",
+        action="store_true",
+        help="Disable the ANF constant folding pass",
+    )
+
+    args = parser.parse_args()
+
+    if not args.ir and not args.source:
+        print(
+            "Usage: runar-compiler-python [--ir <path> | --source <path>] "
+            "[--output <path>] [--hex] [--asm] [--emit-ir]",
+            file=sys.stderr,
+        )
+        print("", file=sys.stderr)
+        print(
+            "Phase 1: Compile from ANF IR JSON to Bitcoin Script (--ir).",
+            file=sys.stderr,
+        )
+        print(
+            "Phase 2: Compile from source to Bitcoin Script (--source).",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    # Handle --emit-ir: dump ANF IR JSON and exit
+    if args.emit_ir:
+        if not args.source:
+            print("--emit-ir requires --source", file=sys.stderr)
+            sys.exit(1)
+        try:
+            program = compile_source_to_ir(
+                args.source,
+                disable_constant_folding=args.disable_constant_folding,
+            )
+        except CompilationError as e:
+            print(f"Compilation error: {e}", file=sys.stderr)
+            sys.exit(1)
+        # Serialize the ANFProgram to camelCase JSON (matching Go/TS output)
+        ir_json = json.dumps(_anf_to_camel_dict(program), indent=2, default=str)
+        print(ir_json)
+        return
+
+    try:
+        if args.source:
+            artifact = compile_from_source(
+                args.source,
+                disable_constant_folding=args.disable_constant_folding,
+            )
+        else:
+            artifact = compile_from_ir(
+                args.ir,
+                disable_constant_folding=args.disable_constant_folding,
+            )
+    except CompilationError as e:
+        print(f"Compilation error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Compilation error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Determine output
+    if args.hex:
+        output = artifact.script
+    elif args.asm:
+        output = artifact.asm
+    else:
+        output = artifact_to_json(artifact)
+
+    # Write output
+    if args.output:
+        with open(args.output, "w") as f:
+            f.write(output)
+        print(f"Output written to {args.output}", file=sys.stderr)
+    else:
+        print(output)
+
+
+_SNAKE_TO_CAMEL = {
+    "contract_name": "contractName",
+    "is_public": "isPublic",
+    "iter_var": "iterVar",
+    "state_values": "stateValues",
+    "initial_value": "initialValue",
+    "else_": "else",
+    # These stay as snake_case to match Go/TS IR format
+    "result_type": "result_type",
+    # Both raw_value and value_ref map to "value" in Go JSON (they never coexist)
+    "value_ref": "value",
+    "raw_value": "value",
+}
+
+# Fields that should be excluded from IR output (internal decoded fields)
+_IR_EXCLUDED_FIELDS = frozenset({
+    "const_string", "const_big_int", "const_bool", "const_int",
+})
+
+
+def _snake_key(k: str) -> str:
+    return _SNAKE_TO_CAMEL.get(k, k)
+
+
+def _anf_to_camel_dict(obj: object) -> object:
+    """Convert an ANF dataclass tree to a dict matching Go/TS IR JSON format."""
+    import json as _json
+    from dataclasses import fields, is_dataclass
+    if is_dataclass(obj) and not isinstance(obj, type):
+        d: dict = {}
+        has_raw_value = False
+        for f in fields(obj):
+            if f.name in _IR_EXCLUDED_FIELDS:
+                continue
+            v = getattr(obj, f.name)
+            if v is None:
+                continue
+            # raw_value is the canonical Go JSON "value" field — parse and emit its content
+            if f.name == "raw_value":
+                try:
+                    d["value"] = _json.loads(v)
+                except (ValueError, TypeError):
+                    d["value"] = v
+                has_raw_value = True
+                continue
+            # Skip value_ref if raw_value was already emitted as "value"
+            if f.name == "value_ref" and has_raw_value:
+                continue
+            key = _snake_key(f.name)
+            d[key] = _anf_to_camel_dict(v)
+        return d
+    if isinstance(obj, list):
+        return [_anf_to_camel_dict(item) for item in obj]
+    return obj
+
+
+if __name__ == "__main__":
+    main()