Initial commit: MetaXScalar project

Dockerfile

@@ -0,0 +1,14 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt /app/requirements.txt
+RUN pip install --no-cache-dir -r /app/requirements.txt
+
+COPY . /app
+
+ENV PYTHONUNBUFFERED=1
+
+EXPOSE 7860
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

HACKATHON_GUIDELINES.md

@@ -0,0 +1,154 @@
+# Meta x PyTorch Hackathon - Round 1 Guidelines
+
+## Overview
+
+- **Event**: Meta x PyTorch Hackathon by Scaler School of Technology
+- **Theme**: Build OpenEnv environments (Reinforcement Learning)
+- **Registration**: 14th March - 3rd April
+- **Round 1**: 25th March - 8th April
+- **Submission Window Opens**: 28th March
+- **Finale**: 25th-26th April
+- **Submission Deadline**: 8th April 2026, 11:59 PM (confirm timezone on dashboard)
+
+---
+
+## Team Structure
+
+- **Solo**: Compete individually (locked for Round 1 only)
+- **Team**: 2-3 members. Only team lead fills the team form.
+- Once confirmed, teams cannot be changed.
+
+---
+
+## Round 1 Problem Statement
+
+Build a complete, real-world OpenEnv environment that an AI agent can learn from through the standard `step()` / `reset()` / `state()` API.
+
+### Key Requirements
+
+1. **Must simulate a real-world task** (not games or toys)
+2. **Implement full OpenEnv spec**: typed models, `step()/reset()/state()`, `openenv.yaml`
+3. **Minimum 3 tasks** with agent graders (easy → medium → hard, scores/reward 0.0–1.0)
+4. **Meaningful reward function** with partial progress signals
+5. **Baseline inference script** with reproducible scores
+6. **Deploy to Hugging Face Spaces** + working Dockerfile
+7. **README** with environment description, action/observation spaces, setup instructions
+
+---
+
+## Evaluation Criteria
+
+### Pre-Submission Checklist (All Must Pass)
+
+| Criteria | Description |
+|----------|-------------|
+| **HF Space deploys** | Automated ping to Space URL must return 200 and respond to `reset()` |
+| **OpenEnv spec compliance** | Validate `openenv.yaml`, typed models, `step()/reset()/state()` endpoints |
+| **Dockerfile builds** | Automated docker build on submitted repo |
+| **Baseline reproduces** | Run inference script — must complete without error and produce scores |
+| **3+ tasks with graders** | Enumerate tasks, run each grader, verify scores/reward in 0.0–1.0 range |
+
+---
+
+## Mandatory Additional Instructions
+
+### Environment Variables (Must be defined)
+
+```bash
+API_BASE_URL   # The API endpoint for the LLM
+MODEL_NAME     # The model identifier to use for inference
+HF_TOKEN       # Your Hugging Face API key
+```
+
+### Inference Script Requirements
+
+- **Filename**: Must be named `inference.py` in the root directory
+- **LLM Client**: Must use OpenAI Client for all LLM calls
+- **Logging Format**: Must emit structured stdout logs following `[START]`, `[STEP]`, and `[END]` format (field names, ordering, and formatting are strict)
+
+### Infrastructure Restrictions
+
+- Runtime of inference script should be less than **20 minutes**
+- Must work on a machine with **vCPU=2, memory=8GB**
+
+---
+
+## Quick Checklist (Must-Haves)
+
+- HF Space returns 200 and responds to `reset()`
+- `openenv.yaml` validates; `step()/reset()/state()` endpoints respond correctly
+- Dockerfile builds in CI
+- `inference.py` runs end-to-end and produces scores
+- 3+ tasks with graders; reward in 0.0–1.0 range
+- OpenAI client used for all LLM calls; logs follow strict `[START]/[STEP]/[END]` format
+
+---
+
+## Preparatory Course (4 Modules ~3.5 hours)
+
+| Module | Title | Duration |
+|--------|-------|----------|
+| 1 | Why OpenEnv? | 45 min |
+| 2 | Using Existing Environments | 50 min |
+| 3 | Deploying Environments | 45 min |
+| 4 | Building Your Own Environment | 60 min |
+
+**Note**: Each module - read the README first, then open the notebook in Colab. No local setup needed.
+
+[Course Repository](https://github.com/raun/openenv-course/tree/main)
+
+---
+
+## How to Submit
+
+1. Complete Step 1 (Team/Solo selection)
+2. Build your OpenEnv environment
+3. Deploy to Hugging Face Spaces
+4. Run pre-submission validation script
+5. Submit via dashboard (only team leaders can submit)
+
+---
+
+## What Happens After Round 1
+
+- Results announced: 10th April
+- Finale: 25th-26th April
+
+---
+
+## Need Help?
+
+- **Email**: help_openenvhackathon@scaler.com
+- **Discord**: Join the community for announcements, mentor access, and team matching
+- **Discord Link**: https://discord.gg/Dedhy5pkWD
+
+---
+
+## Example Problem Statement Format
+
+> "Build a real-world task environment (e.g., incident triage or logistics scheduling) with clearly defined tasks, automated graders, and reward logic using the OpenEnv framework."
+
+### Expected Deliverables:
+- Create an environment an AI agent can interact with
+- Define tasks with increasing difficulty
+- Write graders that verify task completion
+- Define reward logic for scoring
+- Package using OpenEnv for automated evaluation
+
+### Evaluation Areas:
+- **Runtime correctness**: Runs without errors
+- **Interface compliance**: Follows OpenEnv standard
+- **Task design**: Clear, realistic, testable
+- **Grading logic**: Reward system makes sense
+
+---
+
+## Resources
+
+- [OpenEnv Course Repository](https://github.com/raun/openenv-course/tree/main)
+- [Join Discord Community](https://discord.gg/Dedhy5pkWD)
+- [Contact Support](mailto:help_openenvhackathon@scaler.com)
+
+---
+
+*Last Updated: April 3, 2026*

README.md

@@ -0,0 +1,65 @@
+# SolidityGuard
+
+SolidityGuard is an OpenEnv RL environment that trains agents to review Solidity smart contracts for best practices, gas optimizations, and security vulnerabilities.
+
+## Quick Start
+
+### Requirements
+- Python 3.11+
+- `API_BASE_URL`, `MODEL_NAME`, `HF_TOKEN` set in the environment
+
+### Install
+```bash
+pip install -r requirements.txt
+```
+
+### Run Inference
+```bash
+python inference.py
+```
+
+### Run API Server
+```bash
+uvicorn app:app --host 0.0.0.0 --port 7860
+```
+
+### Expected Output
+Structured logs with `[START]`, `[STEP]`, and `[END]` tags. The final score is reported in the `[END]` log.
+
+## Environment Overview
+
+### Observation
+- `source_code`: Solidity code string
+- `metadata`: contract name, compiler version, file path
+- `task_id`: active task
+
+### Action
+JSON array of findings:
+```json
+[
+  {
+    "issue_type": "reentrancy",
+    "line_number": 13,
+    "description": "State updated after external call",
+    "severity": "Critical"
+  }
+]
+```
+
+### Tasks
+- Task 1: Best practices and syntax
+- Task 2: Gas optimization
+- Task 3: Security vulnerabilities
+
+## Files
+- `openenv.yaml`: Environment spec
+- `environment.py`: Core env logic (`reset/step/state`)
+- `graders.py`: Reward logic and grading
+- `data/manifest.json`: Dataset manifest
+- `inference.py`: Baseline runner and logging
+- `app.py`: FastAPI endpoints for reset/step/state
+- `Dockerfile`: Container build
+
+## Notes
+- Runtime should stay under 20 minutes on 2 vCPU / 8 GB.
+- Docker build must succeed for submission.

app.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel, Field
+
+from environment import SolidityGuardEnv
+
+
+app = FastAPI(title="SolidityGuard")
+env = SolidityGuardEnv()
+
+
+class ResetRequest(BaseModel):
+    task_id: Optional[str] = Field(default=None)
+
+
+class StepRequest(BaseModel):
+    action: List[Dict[str, Any]]
+
+
+@app.get("/health")
+def health() -> Dict[str, str]:
+    return {"status": "ok"}
+
+
+@app.post("/reset")
+def reset(request: ResetRequest) -> Dict[str, Any]:
+    try:
+        return env.reset(task_id=request.task_id)
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@app.post("/step")
+def step(request: StepRequest) -> Dict[str, Any]:
+    try:
+        return env.step(request.action)
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@app.get("/state")
+def state() -> Dict[str, Any]:
+    try:
+        return env.state()
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc))

data/manifest.json

@@ -0,0 +1,176 @@
+[
+  {
+    "id": "t1_sample_1",
+    "task_id": "task_1_best_practices",
+    "source_path": "data/samples/task1/missing_spdx.sol",
+    "metadata": {
+      "contract_name": "NoSpdx",
+      "compiler_version": "0.7.6",
+      "file_path": "missing_spdx.sol"
+    },
+    "labels": [
+      {
+        "issue_type": "missing_spdx",
+        "line_number": 1,
+        "description": "Missing SPDX license identifier",
+        "severity": "Low"
+      },
+      {
+        "issue_type": "old_compiler_version",
+        "line_number": 2,
+        "description": "Compiler version below 0.8.x",
+        "severity": "Low"
+      }
+    ]
+  },
+  {
+    "id": "t1_sample_2",
+    "task_id": "task_1_best_practices",
+    "source_path": "data/samples/task1/missing_natspec.sol",
+    "metadata": {
+      "contract_name": "NoNatSpec",
+      "compiler_version": "0.8.13",
+      "file_path": "missing_natspec.sol"
+    },
+    "labels": [
+      {
+        "issue_type": "missing_natspec",
+        "line_number": 6,
+        "description": "Public function missing NatSpec comment",
+        "severity": "Low"
+      }
+    ]
+  },
+  {
+    "id": "t1_sample_3",
+    "task_id": "task_1_best_practices",
+    "source_path": "data/samples/task1/deprecated_constructor.sol",
+    "metadata": {
+      "contract_name": "LegacyConstructor",
+      "compiler_version": "0.4.24",
+      "file_path": "deprecated_constructor.sol"
+    },
+    "labels": [
+      {
+        "issue_type": "deprecated_constructor",
+        "line_number": 6,
+        "description": "Constructor uses deprecated syntax",
+        "severity": "Low"
+      },
+      {
+        "issue_type": "old_compiler_version",
+        "line_number": 2,
+        "description": "Compiler version below 0.8.x",
+        "severity": "Low"
+      }
+    ]
+  },
+  {
+    "id": "t2_sample_1",
+    "task_id": "task_2_gas_optimization",
+    "source_path": "data/samples/task2/inefficient_loop.sol",
+    "metadata": {
+      "contract_name": "LoopGas",
+      "compiler_version": "0.8.17",
+      "file_path": "inefficient_loop.sol"
+    },
+    "labels": [
+      {
+        "issue_type": "unbounded_loop",
+        "line_number": 10,
+        "description": "Loop uses dynamic array length without bounds",
+        "severity": "Medium"
+      }
+    ]
+  },
+  {
+    "id": "t2_sample_2",
+    "task_id": "task_2_gas_optimization",
+    "source_path": "data/samples/task2/redundant_storage.sol",
+    "metadata": {
+      "contract_name": "StorageGas",
+      "compiler_version": "0.8.19",
+      "file_path": "redundant_storage.sol"
+    },
+    "labels": [
+      {
+        "issue_type": "redundant_storage_read",
+        "line_number": 12,
+        "description": "Repeated storage reads could be cached",
+        "severity": "Medium"
+      }
+    ]
+  },
+  {
+    "id": "t2_sample_3",
+    "task_id": "task_2_gas_optimization",
+    "source_path": "data/samples/task2/require_string.sol",
+    "metadata": {
+      "contract_name": "RequireString",
+      "compiler_version": "0.8.18",
+      "file_path": "require_string.sol"
+    },
+    "labels": [
+      {
+        "issue_type": "custom_error_missing",
+        "line_number": 6,
+        "description": "Custom errors are preferred over require strings",
+        "severity": "Low"
+      }
+    ]
+  },
+  {
+    "id": "t3_sample_1",
+    "task_id": "task_3_security",
+    "source_path": "data/samples/task3/reentrancy.sol",
+    "metadata": {
+      "contract_name": "Reentry",
+      "compiler_version": "0.8.20",
+      "file_path": "reentrancy.sol"
+    },
+    "labels": [
+      {
+        "issue_type": "reentrancy",
+        "line_number": 13,
+        "description": "State update after external call allows reentrancy",
+        "severity": "Critical"
+      }
+    ]
+  },
+  {
+    "id": "t3_sample_2",
+    "task_id": "task_3_security",
+    "source_path": "data/samples/task3/missing_access_control.sol",
+    "metadata": {
+      "contract_name": "Admin",
+      "compiler_version": "0.8.20",
+      "file_path": "missing_access_control.sol"
+    },
+    "labels": [
+      {
+        "issue_type": "missing_access_control",
+        "line_number": 9,
+        "description": "Sensitive function lacks access control",
+        "severity": "Critical"
+      }
+    ]
+  },
+  {
+    "id": "t3_sample_3",
+    "task_id": "task_3_security",
+    "source_path": "data/samples/task3/tx_origin_auth.sol",
+    "metadata": {
+      "contract_name": "OriginAuth",
+      "compiler_version": "0.8.20",
+      "file_path": "tx_origin_auth.sol"
+    },
+    "labels": [
+      {
+        "issue_type": "tx_origin_auth",
+        "line_number": 11,
+        "description": "Authorization uses tx.origin",
+        "severity": "Critical"
+      }
+    ]
+  }
+]

data/samples/task1/deprecated_constructor.sol

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.4.24;
+
+contract LegacyConstructor {
+    uint256 public value;
+
+    function LegacyConstructor(uint256 initial) public {
+        value = initial;
+    }
+}

data/samples/task1/missing_natspec.sol

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+contract NoNatSpec {
+    uint256 public total;
+
+    function add(uint256 value) public {
+        total += value;
+    }
+}

data/samples/task1/missing_spdx.sol

@@ -0,0 +1,9 @@
+pragma solidity ^0.7.6;
+
+contract NoSpdx {
+    uint256 public count;
+
+    function increment() public {
+        count += 1;
+    }
+}

data/samples/task2/inefficient_loop.sol

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.17;
+
+contract LoopGas {
+    uint256[] public values;
+
+    function sum() public view returns (uint256) {
+        uint256 total = 0;
+        for (uint256 i = 0; i < values.length; i++) {
+            total += values[i];
+        }
+        return total;
+    }
+}

data/samples/task2/redundant_storage.sol

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.19;
+
+contract StorageGas {
+    uint256 public price;
+    uint256 public fee;
+
+    function totalCost(uint256 quantity) public view returns (uint256) {
+        uint256 cost = price * quantity;
+        cost = cost + fee;
+        cost = cost + fee;
+        return cost;
+    }
+}

data/samples/task2/require_string.sol

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.18;
+
+contract RequireString {
+    function update(uint256 amount) public pure returns (uint256) {
+        require(amount > 0, "amount must be positive");
+        return amount;
+    }
+}

data/samples/task3/missing_access_control.sol

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+contract Admin {
+    mapping(address => bool) public admins;
+
+    function setAdmin(address account, bool status) public {
+        admins[account] = status;
+    }
+}

data/samples/task3/reentrancy.sol

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+contract Reentry {
+    mapping(address => uint256) public balances;
+
+    function deposit() public payable {
+        balances[msg.sender] += msg.value;
+    }
+
+    function withdraw() public {
+        uint256 amount = balances[msg.sender];
+        require(amount > 0);
+        (bool success, ) = msg.sender.call{value: amount}("");
+        require(success);
+        balances[msg.sender] = 0;
+    }
+}

data/samples/task3/tx_origin_auth.sol

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+contract OriginAuth {
+    address public owner;
+
+    constructor() {
+        owner = msg.sender;
+    }
+
+    function withdraw(uint256 amount) public {
+        require(tx.origin == owner);
+        payable(msg.sender).transfer(amount);
+    }
+}

environment.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from graders import grade_action
+
+
+@dataclass
+class EnvironmentState:
+    task_id: str
+    step_count: int
+    max_steps: int
+    score_so_far: float
+    done: bool
+
+
+class SolidityGuardEnv:
+    def __init__(self, data_path: str = "data/manifest.json") -> None:
+        self.data_path = data_path
+        self._load_manifest()
+        self._index = 0
+        self._current_sample: Optional[Dict[str, Any]] = None
+        self._state: Optional[EnvironmentState] = None
+
+    def _load_manifest(self) -> None:
+        if not os.path.exists(self.data_path):
+            raise FileNotFoundError(f"Manifest not found: {self.data_path}")
+        with open(self.data_path, "r", encoding="utf-8") as handle:
+            self._manifest = json.load(handle)
+        if not isinstance(self._manifest, list) or not self._manifest:
+            raise ValueError("Manifest must be a non-empty list")
+
+    def reset(self, task_id: Optional[str] = None) -> Dict[str, Any]:
+        if task_id:
+            candidates = [item for item in self._manifest if item["task_id"] == task_id]
+        else:
+            candidates = self._manifest
+
+        if not candidates:
+            raise ValueError("No samples available for the requested task")
+
+        self._current_sample = candidates[self._index % len(candidates)]
+        self._index += 1
+
+        source_path = self._current_sample["source_path"]
+        with open(source_path, "r", encoding="utf-8") as handle:
+            source_code = handle.read()
+
+        observation = {
+            "source_code": source_code,
+            "metadata": self._current_sample.get("metadata", {}),
+            "task_id": self._current_sample["task_id"],
+        }
+
+        self._state = EnvironmentState(
+            task_id=self._current_sample["task_id"],
+            step_count=0,
+            max_steps=1,
+            score_so_far=0.0,
+            done=False,
+        )
+
+        return observation
+
+    def step(self, action: List[Dict[str, Any]]) -> Dict[str, Any]:
+        if self._current_sample is None or self._state is None:
+            raise RuntimeError("Call reset() before step().")
+
+        if self._state.done:
+            return {
+                "reward": self._state.score_so_far,
+                "done": True,
+                "details": {"message": "Episode already completed"},
+            }
+
+        expected = self._current_sample.get("labels", [])
+        reward, details = grade_action(action, expected)
+
+        self._state.step_count += 1
+        self._state.score_so_far = reward
+        self._state.done = True
+
+        return {
+            "reward": reward,
+            "done": True,
+            "details": details,
+        }
+
+    def state(self) -> Dict[str, Any]:
+        if self._state is None:
+            raise RuntimeError("Call reset() before state().")
+        return {
+            "task_id": self._state.task_id,
+            "step_count": self._state.step_count,
+            "max_steps": self._state.max_steps,
+            "score_so_far": self._state.score_so_far,
+            "done": self._state.done,
+        }

graders.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+
+
+@dataclass(frozen=True)
+class Issue:
+    issue_type: str
+    line_number: Optional[int]
+    severity: str
+
+
+def _normalize_issue(issue: Dict[str, Any]) -> Issue:
+    return Issue(
+        issue_type=str(issue.get("issue_type", "")).strip(),
+        line_number=issue.get("line_number"),
+        severity=str(issue.get("severity", "")).strip(),
+    )
+
+
+def _match_issue(pred: Issue, expected: Issue) -> bool:
+    if pred.issue_type.lower() != expected.issue_type.lower():
+        return False
+    if pred.severity.lower() != expected.severity.lower():
+        return False
+    return True
+
+
+def _line_bonus(pred_line: Optional[int], exp_line: Optional[int]) -> float:
+    if pred_line is None or exp_line is None:
+        return 0.0
+    diff = abs(pred_line - exp_line)
+    if diff == 0:
+        return 0.2
+    if diff <= 2:
+        return 0.1
+    return 0.0
+
+
+def grade_action(action: List[Dict[str, Any]], expected: List[Dict[str, Any]]) -> Tuple[float, Dict[str, Any]]:
+    expected_issues = [_normalize_issue(item) for item in expected]
+    predicted_issues = [_normalize_issue(item) for item in action]
+
+    matched = 0
+    line_bonus_total = 0.0
+    expected_used = [False] * len(expected_issues)
+
+    for pred in predicted_issues:
+        found = False
+        for idx, exp in enumerate(expected_issues):
+            if expected_used[idx]:
+                continue
+            if _match_issue(pred, exp):
+                expected_used[idx] = True
+                matched += 1
+                line_bonus_total += _line_bonus(pred.line_number, exp.line_number)
+                found = True
+                break
+        if not found:
+            continue
+
+    expected_count = max(len(expected_issues), 1)
+    base_score = matched / expected_count
+    false_positives = max(len(predicted_issues) - matched, 0)
+    fp_penalty = 0.05 * false_positives
+
+    score = base_score * 0.8 + min(line_bonus_total, 0.2) - fp_penalty
+    score = max(min(score, 1.0), 0.0)
+
+    details = {
+        "matched": matched,
+        "expected": len(expected_issues),
+        "false_positives": false_positives,
+        "line_bonus": round(min(line_bonus_total, 0.2), 3),
+        "score": round(score, 4),
+    }
+    return score, details

idea.md

@@ -0,0 +1,287 @@
+# SolidityGuard - OpenEnv RL Environment
+
+## Project Title
+**SolidityGuard** - An OpenEnv RL Environment for Smart Contract Security Review
+
+## Problem Statement
+Build an AI agent that learns to review Solidity smart contracts for security vulnerabilities, gas optimization issues, and best practices using the OpenEnv framework.
+
+## Why This Project?
+- Real-world utility: Smart contracts hold billions in crypto assets
+- Unique & differentiated: Most RL envs are generic code review, Solidity is specialized
+- Measurable success: Graders can verify against known vulnerability patterns
+- High impact: Automated security review is in high demand in Web3
+
+---
+
+## Environment Design
+
+### Observation Space
+- **Input**: Solidity source code (string)
+- **Metadata**: Contract name, compiler version, file path
+
+### Action Space
+- **Output**: Review comments with severity levels (Critical/Medium/Low/Info)
+- **Format**: JSON with `issue_type`, `line_number`, `description`, `severity`
+
+---
+
+## 3 Tasks (Difficulty Levels)
+
+| Task | Difficulty | Focus Area | Examples | Max Score |
+|------|------------|------------|----------|-----------|
+| Task 1 | Easy | Syntax & Best Practices | Missing SPDX license, old compiler version, missing NatSpec | 0.33 |
+| Task 2 | Medium | Gas Optimization | Unchecked external calls, inefficient loops, redundant storage reads | 0.33 |
+| Task 3 | Hard | Security Vulnerabilities | Reentrancy, integer overflow, access control issues, tx.origin usage | 0.34 |
+
+---
+
+## Grading System
+
+### Task 1: Syntax & Best Practices (0-0.33)
+Grader checks for:
+- [ ] SPDX license identifier present
+- [ ] Compiler version specified (>=0.8.0)
+- [ ] NatSpec comments on public functions
+- [ ] No deprecated Solidity features
+
+### Task 2: Gas Optimization (0-0.33)
+Grader checks for:
+- [ ] Cache storage variables in memory where possible
+- [ ] Use of custom errors instead of require strings
+- [ ] Loop optimization (avoid unbounded loops)
+- [ ] Unchecked external call handling
+
+### Task 3: Security Vulnerabilities (0-0.34)
+Grader checks for:
+- [ ] Reentrancy guards on sensitive functions
+- [ ] Integer overflow/underflow protection
+- [ ] Access control on sensitive functions
+- [ ] Safe usage of low-level calls
+- [ ] No tx.origin usage for authorization
+
+---
+
+## Reward Function
+
+- **Partial Progress**: Points awarded for each correct issue detected
+- **Penalty**: Points deducted for false positives (wrongly reported issues)
+- **Explanation Bonus**: Extra points for accurate line numbers and helpful descriptions
+- **Final Score**: 0.0 to 1.0 scale
+
+---
+
+## Tech Stack
+
+- Python 3.x
+- OpenEnv framework
+- OpenAI Client for LLM inference
+- Hugging Face Spaces + Docker
+- Environment variables: `API_BASE_URL`, `MODEL_NAME`, `HF_TOKEN`
+
+---
+
+## Deliverables
+
+1. `openenv.yaml` - Environment specification
+2. `environment.py` - Main env implementation with step/reset/state
+3. `inference.py` - LLM inference script with [START]/[STEP]/[END] logging
+4. `Dockerfile` - Container configuration
+5. `README.md` - Setup instructions and documentation
+6. Deployed on Hugging Face Spaces
+
+---
+
+## Timeline
+
+| Day | Task |
+|-----|------|
+| Day 1 | Setup + study OpenEnv templates |
+| Day 2 | Design env spec + grader functions |
+| Day 3 | Implement step/reset/state methods |
+| Day 4 | Create inference.py with logging |
+| Day 5 | Deploy to HF Spaces + validate |
+| Day 6 | Polish + write README |
+| Day 7 | Final validation + submit (Deadline: 8th April) |
+
+---
+
+## Production-Ready Execution Plan
+
+### Objective
+Build **SolidityGuard**, a compliant OpenEnv RL environment where an agent audits Solidity contracts for security, gas optimization, and best practices. Must pass all hackathon validators: OpenEnv spec, graders, Docker build, Hugging Face Space, and reproducible `inference.py` with strict logging.
+
+### Scope & Constraints
+- Real-world task; no games or toy problems
+- Must implement OpenEnv spec: typed models + `reset()/step()/state()` + `openenv.yaml`
+- Must include 3 tasks (easy/medium/hard) with graders and rewards in 0.0–1.0
+- `inference.py` must exist in repo root, use OpenAI client, and emit strict `[START]/[STEP]/[END]` logs
+- Runtime < 20 minutes on 2 vCPU / 8 GB
+- Deploy to Hugging Face Spaces + Dockerfile must build
+
+### Environment Design Summary
+
+**Observation**
+- `source_code: str`
+- `metadata`: contract name, compiler version, file path (optional)
+- `task_id`: which task is active
+
+**Action**
+- JSON list of findings:
+  - `issue_type` (string enum)
+  - `line_number` (int or null)
+  - `description` (string)
+  - `severity` (Critical/Medium/Low/Info)
+
+**State**
+- `task_id`
+- `step_count`
+- `max_steps`
+- `score_so_far`
+- `done`
+
+### Task Definitions (3 Levels)
+
+**Task 1 (Easy): Best Practices / Syntax**
+- SPDX license presence
+- compiler version >= 0.8.x
+- NatSpec for public functions
+- deprecated patterns detection
+
+**Task 2 (Medium): Gas Optimization**
+- cache storage vars
+- custom errors instead of require strings
+- avoid unbounded loops
+- safe/efficient external calls
+
+**Task 3 (Hard): Security Vulnerabilities**
+- reentrancy detection
+- missing access control
+- unsafe low-level calls
+- no `tx.origin` auth
+
+### Grader Logic
+- Partial credit per correct finding
+- Penalty for false positives
+- Bonus for accurate line numbers (bounded)
+- Normalize per task to 0.0–1.0
+- Aggregate score across tasks
+
+### Dataset Plan
+- 12–20 Solidity snippets total (4–6 per task)
+- Each snippet has a ground-truth label set for issues
+- Mix of clean and vulnerable examples
+- Add control samples with no issues to penalize false positives
+
+### Implementation Plan (Step-By-Step)
+
+**Phase 0 — Scope Lock (0.5 day)**
+- Freeze task rubrics
+- Lock dataset size + sourcing method
+- Define baseline score targets
+
+**Phase 1 — Spec & Schema (1 day)**
+- Define typed models for observation/action/state
+- Draft `openenv.yaml` with tasks and endpoints
+- Validate schema alignment
+
+**Phase 2 — Environment Core (1–2 days)**
+- Implement `reset()` to provide a task-specific sample
+- Implement `step()` to grade action JSON and produce reward
+- Implement `state()` to surface current status
+- Ensure deterministic responses
+
+**Phase 3 — Graders + Reward (1–2 days)**
+- Implement task graders
+- Add partial credit and penalty logic
+- Normalize to 0–1
+- Unit-test grader outputs
+
+**Phase 4 — Inference Pipeline (1 day)**
+- Implement `inference.py`
+- Use OpenAI client with `API_BASE_URL`, `MODEL_NAME`, `HF_TOKEN`
+- Emit strict `[START]/[STEP]/[END]` logs with required fields
+- Ensure runtime < 20 min
+
+**Phase 5 — Packaging & Deployment (1 day)**
+- Dockerfile builds and runs inference
+- Deploy to Hugging Face Spaces
+- Confirm `/reset` returns 200
+
+**Phase 6 — Validation & Hardening (0.5–1 day)**
+- Run pre-submission validation script
+- Add input size checks
+- Add timeouts and safe error handling
+- Pin dependencies for reproducibility
+
+**Phase 7 — Documentation & Release (0.5 day)**
+- README with setup, schema, tasks, baseline scores
+- Troubleshooting steps
+- Submission checklist
+
+### Required Files
+- `openenv.yaml`
+- `environment.py` (or equivalent)
+- `inference.py` (root)
+- `Dockerfile`
+- `README.md`
+- `dataset/` or `samples/` (Solidity snippets + labels)
+
+### Success Criteria
+- HF Space deploys and responds to `/reset`
+- Docker build passes
+- `inference.py` completes under 20 minutes
+- Strict log format compliance
+- All graders return normalized scores
+
+---
+
+## Sample Test Cases
+
+### Test Case 1: Reentrancy Vulnerability
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+contract Vulnerable {
+    mapping(address => uint) balances;
+    
+    function withdraw() public {
+        uint bal = balances[msg.sender];
+        require(bal > 0);
+        
+        (bool success, ) = msg.sender.call{value: bal}("");
+        require(success);
+        
+        balances[msg.sender] = 0;
+    }
+}
+```
+**Expected**: Agent should detect reentrancy vulnerability (Task 3)
+
+### Test Case 2: Missing Access Control
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+contract AdminContract {
+    mapping(address => bool) admins;
+    
+    function setAdmin(address addr, bool status) public {
+        admins[addr] = status;
+    }
+}
+```
+**Expected**: Agent should identify missing access control (Task 3)
+
+---
+
+## References
+
+- OpenEnv Framework: https://github.com/raun/openenv-course
+- Common Smart Contract Vulnerabilities: Slither, Mythril
+- Gas Optimization: Solidity docs, OpenZeppelin
+
+---
+
+*Last Updated: April 3, 2026*

inference.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any, Dict, List
+
+from environment import SolidityGuardEnv
+
+
+def _log(tag: str, payload: Dict[str, Any]) -> None:
+    print(f"[{tag}] {json.dumps(payload, ensure_ascii=True)}")
+
+
+def _load_env_var(name: str) -> str:
+    value = os.getenv(name)
+    if not value:
+        raise RuntimeError(f"Missing required environment variable: {name}")
+    return value
+
+
+def _call_model(prompt: str) -> List[Dict[str, Any]]:
+    from openai import OpenAI
+
+    api_base_url = _load_env_var("API_BASE_URL")
+    model_name = _load_env_var("MODEL_NAME")
+    hf_token = _load_env_var("HF_TOKEN")
+
+    client = OpenAI(base_url=api_base_url, api_key=hf_token)
+    response = client.chat.completions.create(
+        model=model_name,
+        messages=[
+            {"role": "system", "content": "You are a Solidity security reviewer."},
+            {"role": "user", "content": prompt},
+        ],
+        temperature=0.0,
+        max_tokens=800,
+    )
+
+    content = response.choices[0].message.content or "[]"
+    try:
+        parsed = json.loads(content)
+    except json.JSONDecodeError:
+        parsed = []
+    if isinstance(parsed, list):
+        return parsed
+    return []
+
+
+def _build_prompt(source_code: str, task_id: str) -> str:
+    return (
+        "Review the Solidity contract and return a JSON array of findings. "
+        "Each finding must include: issue_type, line_number, description, severity. "
+        f"Task: {task_id}.\n\n"
+        f"Contract:\n{source_code}"
+    )
+
+
+def run() -> int:
+    env = SolidityGuardEnv()
+    tasks = [
+        "task_1_best_practices",
+        "task_2_gas_optimization",
+        "task_3_security",
+    ]
+
+    _log("START", {"task_count": len(tasks)})
+    total_score = 0.0
+
+    for task_id in tasks:
+        observation = env.reset(task_id=task_id)
+        prompt = _build_prompt(observation["source_code"], task_id)
+        actions = _call_model(prompt)
+
+        step_result = env.step(actions)
+        state = env.state()
+
+        total_score += step_result["reward"]
+
+        _log(
+            "STEP",
+            {
+                "task_id": task_id,
+                "reward": step_result["reward"],
+                "details": step_result.get("details", {}),
+                "state": state,
+            },
+        )
+
+    final_score = round(total_score / len(tasks), 4)
+    _log("END", {"final_score": final_score})
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(run())
+    except Exception as exc:
+        _log("END", {"final_score": 0.0, "error": str(exc)})
+        sys.exit(1)

openenv.yaml

@@ -0,0 +1,66 @@
+name: SolidityGuard
+version: 0.1.0
+description: OpenEnv RL environment for Solidity security review
+entrypoint: environment.py:SolidityGuardEnv
+tasks:
+  - id: task_1_best_practices
+    difficulty: easy
+    description: Detect syntax and best-practice issues in Solidity contracts.
+    max_steps: 1
+  - id: task_2_gas_optimization
+    difficulty: medium
+    description: Detect gas optimization opportunities in Solidity contracts.
+    max_steps: 1
+  - id: task_3_security
+    difficulty: hard
+    description: Detect security vulnerabilities in Solidity contracts.
+    max_steps: 1
+schemas:
+  observation:
+    type: object
+    required: [source_code, metadata, task_id]
+    properties:
+      source_code:
+        type: string
+      metadata:
+        type: object
+        required: [contract_name, compiler_version, file_path]
+        properties:
+          contract_name:
+            type: string
+          compiler_version:
+            type: string
+          file_path:
+            type: string
+      task_id:
+        type: string
+  action:
+    type: array
+    items:
+      type: object
+      required: [issue_type, line_number, description, severity]
+      properties:
+        issue_type:
+          type: string
+        line_number:
+          type: integer
+          nullable: true
+        description:
+          type: string
+        severity:
+          type: string
+          enum: [Critical, Medium, Low, Info]
+  state:
+    type: object
+    required: [task_id, step_count, max_steps, score_so_far, done]
+    properties:
+      task_id:
+        type: string
+      step_count:
+        type: integer
+      max_steps:
+        type: integer
+      score_so_far:
+        type: number
+      done:
+        type: boolean

requirements.txt

@@ -0,0 +1,3 @@
+fastapi>=0.110.0
+openai>=1.30.0
+uvicorn>=0.27.0