Add random program generation and mutation.

.envrc

@@ -0,0 +1 @@
+use flake

.gitignore

@@ -1,5 +1,6 @@
 onchain/cache/
 onchain/out/
-out/
-cache/
-lib/forge-std
+
+offchain/target/
+
+.direnv

ISSUE_TEMPLATE.md

@@ -1,47 +0,0 @@
-me: Bounty
-about: Bounty
-title: ''
-labels: bounty
-assignees: ''
-
----
-
-# Bounty
-
-## Scope
-<!-- A list of specific things which should be done to deliver the bounty. These could be seen as requirements to verify/review bounty against -->
-
--
--
--
-
-## Deliverables
-<!-- Artifacts produced as the result of this bounty. Something that could be verified/reviewed. Some examples: updated code, deployment made, blog post published, public event conducted etc -->
-
--
--
-
-## Bounty Owner/Gardener
-<!-- The Role who is responsible for the bounty. -->
-<@your github username> as **<Role>**
-
-## Gain for the Role
-<!-- How the completion of this bounty helps to pursue the Role's purpose -->
-
-## Roles
-bounty gardener: <@your git username> / X DAI <!-- likely shouldn't be a % but rather flat -->
-bounty worker: name / share
-bounty reviewer: name / share
-
-## Gardener checklist
-
-- [ ] I have attached one of the `size-` labels to this bounty
-
-<!--
-# Bounty sizes
-XS / 200 DAI / effort ~ 3h
-S / 350 DAI / effort ~5h 
-M / 550 DAI / effort ~8h
-L / 900 DAI / effort ~13h
-XL / 1400 DAI / effort ~21h
--->

Interpreter.md

@@ -0,0 +1,124 @@
+# Interpreter.md
+
+## Overview
+
+This repository provides a **Push3-like interpreter** implemented in Solidity. It uses a _token-based bytecode_ approach to parse programs from a `bytes` array (the `code`) into typed **descriptors**, which are then executed by the interpreter.
+
+**Push3** is a stack-based language originally designed for genetic programming and autoconstructive evolution. Each data type (e.g. `INT_LITERAL`, `FLOAT`, `BOOLEAN`, etc.) has its own stack. The **`EXEC`** stack manages the flow of execution.
+
+**In this implementation**:
+- We store code in a single `bytes` array (`code`).
+- We parse sublists and integer literals from that array.
+- We push instructions and literals onto an execution stack.
+- We pop them in LIFO order and execute them.
+
+### Key Features
+
+1. **Token-Based Parsing**: We define small tokens (`0x00` => NOOP, `0x01` => INTEGER_PLUS, `0x02` => INT_LITERAL, `0x03` => SUBLIST). If we see `INT_LITERAL`, we read 4 bytes for a 32-bit integer; if we see `SUBLIST`, we read 2 bytes for the sublist length, then parse it recursively.
+2. **Descriptor System**: We represent instructions, literals, and sublists using 256-bit “descriptors.” Each descriptor encodes:
+   - A `tag` (top 8 bits): e.g. `INT_LITERAL`, `INSTRUCTION`, `SUBLIST`.
+   - `offset` and `length` for sublists.
+   - A leftover field (e.g. for storing integer data).
+3. **Reversing Items**: When we pop a sublist descriptor, we parse it into descriptors and then push them onto the `EXEC` stack in reverse order. This ensures the list’s leftmost token executes first, consistent with the Push3 spec.
+4. **Separation of Parsing and Execution**: 
+   - **Parsing**: Transforms raw byte tokens into typed descriptors (instructions, literals, or nested sublists).
+   - **Execution**: The `runInterpreter` function repeatedly pops from `EXEC`, decides if it’s an instruction or literal or sublist, and acts accordingly.
+
+## Code Structure
+
+### 1. **Enums**
+
+- **`CodeTag`**: 
+  - `NO_TAG` (unused), 
+  - `INSTRUCTION`, 
+  - `INT_LITERAL`, 
+  - `SUBLIST`.
+
+- **`OpCode`**:  
+  - `NOOP`, 
+  - `INTEGER_PLUS`.
+
+### 2. **Descriptor Layout**
+
+A **256-bit** word has:
+```
+[  top 8 bits    |  offset(32 bits) |  length(32 bits)  |  leftover(184 bits) ]
+```
+- `tag`: The top 8 bits (e.g. `INT_LITERAL`).
+- `offset, length`: If `tag = SUBLIST`, these define which bytes in `code` represent the sub-sublists.
+- `leftover`: If `tag = INT_LITERAL`, we store the 32-bit integer in the bottom 32 bits of leftover. If `tag = INSTRUCTION`, we store the opcode (`NOOP`, `INTEGER_PLUS`) in the lowest 8 bits of leftover.
+
+### 3. **Helper Reads**
+
+- **`readUint32(code, start)`**: Copies 4 bytes from calldata into a small buffer, returns the final `uint32`. By shifting bits if needed, we ensure we get the integer from the correct part of the loaded word.
+- **`readUint16(code, start)`**: Similar logic for 2 bytes.
+
+### 4. **`parseSublist` Function**
+
+When we see a sublist descriptor (`tag=SUBLIST`), we parse the slice `[off..off+len]` in the `bytes code`. We iterate token by token:
+- `0x00` => `NOOP`
+- `0x01` => `INTEGER_PLUS`
+- `0x02` => read 4 bytes => `INT_LITERAL`
+- `0x03` => read 2 bytes => sub-sublist length => build a sub-descriptor
+
+We accumulate these descriptors in an array. Then, later, we push them _in reverse_ onto the `EXEC` stack.
+
+### 5. **`runInterpreter` Function**
+
+1. Loads initial CODE, EXEC, and INT stacks from the provided arrays.
+2. While `EXEC` is non-empty:
+   - Pop the top descriptor.
+   - If `INSTRUCTION`, decode the opcode (e.g. `INTEGER_PLUS`) and do it (pop top 2 ints, push their sum).
+   - If `INT_LITERAL`, push that integer onto the int stack.
+   - If `SUBLIST`, parse that sublist into descriptors, then push those in reverse.
+
+## How to Contribute
+
+1. **Add New Instructions**  
+   - Expand `OpCode` enum (e.g. `INTEGER_MINUS`, `INTEGER_MUL`, etc.).
+   - Write a `makeInstruction` or `makeIntLiteral` function to build the descriptor for it.
+   - In the main loop, implement the logic (pop the correct number of integers, do the operation, push the result).
+
+2. **Support More Data Types**  
+   - For instance, a `FLOAT` or `BOOLEAN` stack.  
+   - Add a new tag (`FLOAT_LITERAL`?), new instructions (`FLOAT.PLUS`?), etc.
+
+3. **Improve Parsing**  
+   - If you want 256-bit literals, define a new token that reads 32 bytes, or do other expansions (like `CODE` type).  
+   - Or define advanced sublist structures (like nested `( ( ) )` expansions).
+
+4. **Gas Optimization**  
+   - Check how large arrays are allocated (like in `parseSublist`).  
+   - Possibly implement step-by-step execution if large code exceeds block gas limits.
+
+5. **Add Logging & Debug Tools**  
+   - Use `console.log(...)` to trace tokens, track final states, or measure performance.
+
+6. **Test Coverage**  
+   - Provide more unit tests in Foundry for advanced instructions, nested sublists, edge cases with zero-length sublists, etc.
+
+## Next Steps
+
+### A. Extending the VM
+
+A “full” Push3 VM might include:
+- **Multiple Data Stacks**: `BOOLEAN`, `FLOAT`, `NAME`, etc.  
+- **NAME Binding**: Let `NAME`s reference values or code.  
+- **Control Structures**: `EXEC.IF`, `EXEC.DO*COUNT`, or combinators like `EXEC.Y`.
+
+### B. Example Project
+
+You could use this interpreter in:
+- A genetic programming environment, where random code is generated and mutated.
+- A puzzle solver that runs tiny “scripts” in EVM-like constraints.
+
+## Conclusion
+
+This `Push3Interpreter` is a **minimal** scaffold for a token-based, list-expanding interpreter with typed descriptors. By following the patterns for instructions, sublists, and typed stacks, you can easily expand it into a more complete VM. We welcome contributions in the form of new instructions, data types, and performance optimizations.
+
+1. **Clone** this repo.  
+2. **Check** the `test/` folder for Foundry-based tests.  
+3. **Add** or modify instructions & sublists in `parseSublist` and `runInterpreter`.  
+4. **Run** `forge test --via-ir -vv` to see logs and confirm your changes.
+
+Enjoy exploring the **Push3** style VM in Solidity!

README.md

@@ -1,14 +1,6 @@
 # **SoLUSH**: A Push 3 Virtual Machine in Solidity
 
-Welcome to **SoLUSH 3** (pronounced like **"slush"** without the "o", composed from **S**o**L**idity and p**USH** 3), a **Push3-like interpreter** implemented in Solidity. It uses a _token-based bytecode_ approach to parse programs from a `bytes` array (the `code`) into typed **descriptors**, which are then executed by the interpreter.
-
-**Push3** is a stack-based language originally designed for genetic programming and autoconstructive evolution. Each data type (e.g. `INT_LITERAL`, `FLOAT`, `BOOLEAN`, etc.) has its own stack. The **`EXEC`** stack manages the flow of execution.
-
-**In this implementation**:
-- We store code in a single `bytes` array (`code`).
-- We parse sublists and integer literals from that array.
-- We push instructions and literals onto an execution stack.
-- We pop them in LIFO order and execute them.
+Welcome to **SoLUSH 3** (pronounced like **"slush"** without the "o", composed from **S**o**L**idity and p**USH** 3), a Solidity implementation of the [Push 3 stack machine](http://faculty.hampshire.edu/lspector/push3-description.html), designed to bring evolved genetic algorithms on-chain. By enabling the execution of Push 3 programs directly within Ethereum smart contracts, SoLush 3 paves the way for decentralized, adaptive systems to address complex optimization problems.
 
 ## 🌟 Vision
 
@@ -20,97 +12,19 @@ SoLUSH is a key step toward realizing the vision of running decentralized evolut
 
 To understand the broader vision, check out the [Vision Document](vision.md).
 
-### Key Features
-
-1. **Token-Based Parsing**: We define small tokens (`0x00` => NOOP, `0x01` => INTEGER_PLUS, `0x02` => INT_LITERAL, `0x03` => SUBLIST). If we see `INT_LITERAL`, we read 4 bytes for a 32-bit integer; if we see `SUBLIST`, we read 2 bytes for the sublist length, then parse it recursively.
-2. **Descriptor System**: We represent instructions, literals, and sublists using 256-bit “descriptors.” Each descriptor encodes:
-   - A `tag` (top 8 bits): e.g. `INT_LITERAL`, `INSTRUCTION`, `SUBLIST`.
-   - `offset` and `length` for sublists.
-   - A leftover field (e.g. for storing integer data).
-3. **Reversing Items**: When we pop a sublist descriptor, we parse it into descriptors and then push them onto the `EXEC` stack in reverse order. This ensures the list’s leftmost token executes first, consistent with the Push3 spec.
-4. **Separation of Parsing and Execution**: 
-   - **Parsing**: Transforms raw byte tokens into typed descriptors (instructions, literals, or nested sublists).
-   - **Execution**: The `runInterpreter` function repeatedly pops from `EXEC`, decides if it’s an instruction or literal or sublist, and acts accordingly.
-
-## Code Structure
-
-### 1. **Enums**
-
-- **`CodeTag`**: 
-  - `NO_TAG` (unused), 
-  - `INSTRUCTION`, 
-  - `INT_LITERAL`, 
-  - `SUBLIST`.
-
-- **`OpCode`**:  
-  - `NOOP`, 
-  - `INTEGER_PLUS`.
-
-### 2. **Descriptor Layout**
-
-A **256-bit** word has:
-```
-[  top 8 bits    |  offset(32 bits) |  length(32 bits)  |  leftover(184 bits) ]
-```
-- `tag`: The top 8 bits (e.g. `INT_LITERAL`).
-- `offset, length`: If `tag = SUBLIST`, these define which bytes in `code` represent the sub-sublists.
-- `leftover`: If `tag = INT_LITERAL`, we store the 32-bit integer in the bottom 32 bits of leftover. If `tag = INSTRUCTION`, we store the opcode (`NOOP`, `INTEGER_PLUS`) in the lowest 8 bits of leftover.
-
-### 3. **Helper Reads**
-
-- **`readUint32(code, start)`**: Copies 4 bytes from calldata into a small buffer, returns the final `uint32`. By shifting bits if needed, we ensure we get the integer from the correct part of the loaded word.
-- **`readUint16(code, start)`**: Similar logic for 2 bytes.
-
-### 4. **`parseSublist` Function**
-
-When we see a sublist descriptor (`tag=SUBLIST`), we parse the slice `[off..off+len]` in the `bytes code`. We iterate token by token:
-- `0x00` => `NOOP`
-- `0x01` => `INTEGER_PLUS`
-- `0x02` => read 4 bytes => `INT_LITERAL`
-- `0x03` => read 2 bytes => sub-sublist length => build a sub-descriptor
-
-We accumulate these descriptors in an array. Then, later, we push them _in reverse_ onto the `EXEC` stack.
-
-### 5. **`runInterpreter` Function**
-
-1. Loads initial CODE, EXEC, and INT stacks from the provided arrays.
-2. While `EXEC` is non-empty:
-   - Pop the top descriptor.
-   - If `INSTRUCTION`, decode the opcode (e.g. `INTEGER_PLUS`) and do it (pop top 2 ints, push their sum).
-   - If `INT_LITERAL`, push that integer onto the int stack.
-   - If `SUBLIST`, parse that sublist into descriptors, then push those in reverse.
-
-
-
-## Next Steps
-
-### A. Extending the VM
-
-A “full” Push3 VM might include:
-- **Multiple Data Stacks**: `BOOLEAN`, `FLOAT`, `NAME`, etc.  
-- **NAME Binding**: Let `NAME`s reference values or code.  
-- **Control Structures**: `EXEC.IF`, `EXEC.DO*COUNT`, or combinators like `EXEC.Y`.
-
-### B. Example Project
-
-You could use this interpreter in:
-- A genetic programming environment, where random code is generated and mutated.
-- A puzzle solver that runs tiny “scripts” in EVM-like constraints.
-
 ## 🚀 Getting Started
 
-This `Push3Interpreter` is a **minimal** scaffold for a token-based, list-expanding interpreter with typed descriptors. By following the patterns for instructions, sublists, and typed stacks, you can easily expand it into a more complete VM. We welcome contributions in the form of new instructions, data types, and performance optimizations.
+SoLUSH 3 is in active development. To contribute or test the functionality, follow these steps:
 
-1. **Clone** this repo.  
-2. **Check** the `test/` folder for Foundry-based tests.  
-3. **Add** or modify instructions & sublists in `parseSublist` and `runInterpreter`.  
-4. **Run** `forge test --via-ir -vv` to see logs and confirm your changes.
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/your-username/SoLUSH.git
+   cd SoLUSH
+   ```
+2. Install dependencies (if applicable).
+3. Review the examples and test cases to understand how Push 3 programs are executed on the VM.
 
 
-### How to contribute
-
-Check the [Issues](../../../issues) section to find tasks to tackle.
-
 ## 🛠️ Roadmap
 
 - **Core Features:**

flake.nix

@@ -23,6 +23,9 @@
 
             # ... any other dependencies we need
             solc
+            cargo
+            rustc
+            rust-analyzer
           ];
 
           # Decorative prompt override so we know when we're in a dev shell

offchain/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "offchain"
+version = "0.1.0"
+edition = "2021"
+
+[[bin]]
+name = "gp_tester"
+path = "src/bin/gp_tester.rs"
+
+[dependencies]
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+rand = "0.8"
+hex = "0.4"
+# ethers = { version = "2.0", features = ["abi"] }
+anyhow = "1.0"
+revm = { git = "https://github.com/bluealloy/revm.git", rev = "03ea24bd9550e93b08f343e0b410725557c1adb4", features = ["std"] }
+database = { git = "https://github.com/bluealloy/revm.git", rev = "03ea24bd9550e93b08f343e0b410725557c1adb4", package = "revm-database" }
+ethers = "2.0"
+
+
+

offchain/src/bin/gp_tester.rs

@@ -0,0 +1,91 @@
+// src/bin/gp_tester.rs
+
+use anyhow::{anyhow, bail, Result};
+use rand::{thread_rng, Rng};
+
+// 1) We'll use the helper that reads creation code from a JSON artifact
+use offchain::helpers::artifact::get_creation_code;
+
+// 2) EvmRunner to deploy & run the interpreter
+use offchain::runner::revm_runner::EvmRunner;
+
+// 3) AST generation & mutation
+use offchain::gp::generate::random_ast;
+use offchain::gp::genetic_ops::mutated_ast;
+use offchain::compiler::ast::UntypedAst;
+
+fn main() -> Result<()> {
+    // ----------------------------------------------------------------------
+    // 1) Read the creation code (Push3Interpreter) using our helper function
+    // ----------------------------------------------------------------------
+    let creation_hex_filename = "../onchain/out/Push3Interpreter.sol/Push3Interpreter.json";
+    let creation_bytes = get_creation_code(creation_hex_filename)?;
+    println!(
+        "Loaded creation code from {} ({} bytes)",
+        creation_hex_filename,
+        creation_bytes.len()
+    );
+
+    // 2) Create the ephemeral EVM (deploy the contract)
+    let mut runner = EvmRunner::new(creation_bytes)?;
+    println!("Deployed test interpreter at: 0x{:x}\n", runner.interpreter_addr);
+
+    // 3) We'll generate random ASTs & mutate them
+    let number_of_programs = 3; // how many random ASTs to try
+    let max_depth = 4;         // max AST depth
+    let mut rng = thread_rng();
+
+    for i in 0..number_of_programs {
+        // a) Generate a random AST
+        let ast: UntypedAst = random_ast(&mut rng, 0, max_depth);
+
+        println!("=== Program {} ===", i);
+        println!("Random AST:\n{:#?}", ast);
+
+        // b) Run the original AST
+        match runner.run_ast(&ast) {
+            Ok(outputs) => {
+                println!("Original AST ran successfully!");
+                println!("Final CODE stack: {:?}", outputs.final_code_stack);
+                println!("Final EXEC stack: {:?}", outputs.final_exec_stack);
+                println!("Final INT stack:  {:?}", outputs.final_int_stack);
+
+                // c) Mutate it a few times
+                let mutated1 = mutated_ast(&ast, &mut rng, 0, max_depth);
+                println!("\n-- MUTATED 1 --\n{:#?}", mutated1);
+
+                match runner.run_ast(&mutated1) {
+                    Ok(m1_out) => {
+                        println!("MUTATED 1 ran successfully!");
+                        println!("Final INT stack: {:?}", m1_out.final_int_stack);
+                    }
+                    Err(e) => {
+                        println!("MUTATED 1 error: {}", e);
+                    }
+                }
+
+                let mutated2 = mutated_ast(&ast, &mut rng, 0, max_depth);
+                println!("\n-- MUTATED 2 --\n{:#?}", mutated2);
+
+                match runner.run_ast(&mutated2) {
+                    Ok(m2_out) => {
+                        println!("MUTATED 2 ran successfully!");
+                        println!("Final INT stack: {:?}", m2_out.final_int_stack);
+                    }
+                    Err(e) => {
+                        println!("MUTATED 2 error: {}", e);
+                    }
+                }
+            }
+            Err(e) => {
+                // If the original fails, we won't bother mutating it
+                println!("Original AST error: {}", e);
+            }
+        }
+
+        println!("=== End of Program {} ===\n", i);
+    }
+
+    println!("Finished running & mutating {} random programs.", number_of_programs);
+    Ok(())
+}

offchain/src/compiler/ast.rs

@@ -0,0 +1,273 @@
+//! src/compiler/ast.rs
+//! 
+//! This module defines an **abstract** untyped AST for our Push3-like language,
+//! plus a mapping for how to encode opcodes as bytes. We do *not* hardcode numeric
+//! values in the `OpCode` enum. Instead, we provide a trait that can map
+//! opcodes to bytes. This allows us to expand or change instructions easily
+//! (e.g., when the on-chain interpreter adds new opcodes or changes their IDs).
+
+/// A trait describing how to convert an AST into Push3 bytecode.
+///
+/// This is deliberately minimal for now. In the future, we could add more methods
+/// (like parsing from bytecode or AST mutation).
+pub trait Push3Ast {
+    /// Convert this AST into a bytecode vector that the on-chain interpreter
+    /// can parse and execute.
+    fn to_bytecode(&self) -> Vec<u8>;
+}
+
+/// A trait that **maps** each [`OpCode`] variant to its **single-byte** representation.
+///
+/// By centralizing this, we can easily add or reorder instructions without rewriting
+/// big chunks of code everywhere. For example, if we add `OpCode::MyNewOp`, we just
+/// update this trait’s logic.
+pub trait OpCodeMapping {
+    /// Given an `OpCode` enum variant, return the corresponding single `u8`
+    /// that the interpreter expects.
+    fn opcode_byte(&self, op: &OpCode) -> u8;
+
+    // If you need reverse-lookup (byte => OpCode), you could add a method like:
+    // fn from_byte(&self, b: u8) -> Option<OpCode>;
+    // for now, we omit it since we only do forward mapping in this file.
+}
+
+/// Our untyped AST node:
+/// - `IntLiteral(i32)` holds a literal integer,
+/// - `Instruction(OpCode)` holds one opcode,
+/// - `Sublist(Vec<UntypedAst>)` holds a collection of nested AST nodes.
+#[derive(Debug, Clone, PartialEq)]
+pub enum UntypedAst {
+    IntLiteral(i32),
+    Instruction(OpCode),
+    Sublist(Vec<UntypedAst>),
+}
+
+/// An **abstract** set of opcodes. We do *not* assign numeric values here.
+/// Instead, see [`OpCodeMapping::opcode_byte`] for how we convert them to bytes.
+#[derive(Debug, Clone, PartialEq)]
+pub enum OpCode {
+    Noop,
+    Plus,
+    Minus,
+    Mult,
+    Dup,
+    Pop,
+    // Add new instructions here as needed. E.g.:
+    // MyNewOp, etc.
+}
+
+impl UntypedAst {
+    /// Encode this AST into bytecode, using a provided [`OpCodeMapping`].
+    ///
+    /// This method is more flexible than `to_bytecode()`, because you can pass in
+    /// *any* mapping if needed. The method used by the trait’s `to_bytecode()`
+    /// relies on the global `DEFAULT_OP_MAPPING`.
+    pub fn to_bytecode_with_mapping<M: OpCodeMapping>(&self, mapping: &M) -> Vec<u8> {
+        match self {
+            // For an integer literal, we write the “tag byte” for int-literal, then 4 bytes (LE).
+            UntypedAst::IntLiteral(val) => {
+                // Hardcode 0x02 => INT_LITERAL. 
+                // You *could* put that in the mapping if you want to make that flexible, too.
+                let mut bytes = Vec::with_capacity(1 + 4);
+                bytes.push(0x02);
+                bytes.extend_from_slice(&val.to_be_bytes());
+                bytes
+            }
+            UntypedAst::Instruction(op) => {
+                // Use the mapping to find the correct opcode byte:
+                let b = mapping.opcode_byte(op);
+                vec![b]
+            }
+            UntypedAst::Sublist(children) => {
+                // Hardcode 0x03 => SUBLIST, then big-endian length, then child payload
+                let mut payload = Vec::new();
+                for child in children {
+                    let child_bytes = child.to_bytecode_with_mapping(mapping);
+                    payload.extend(child_bytes);
+                }
+                let sub_len = payload.len() as u16;
+                let mut bytes = Vec::with_capacity(1 + 2 + payload.len());
+                bytes.push(0x03);
+                bytes.extend_from_slice(&sub_len.to_be_bytes()); // big-endian length
+                bytes.extend(payload);
+                bytes
+            }
+        }
+    }
+}
+
+/// For convenience, we implement `Push3Ast` using a *default* mapping.
+impl Push3Ast for UntypedAst {
+    fn to_bytecode(&self) -> Vec<u8> {
+        self.to_bytecode_with_mapping(&DEFAULT_OP_MAPPING)
+    }
+}
+
+/// A default mapping that corresponds to your current on-chain byte definitions.
+///
+/// This way, if your interpreter changes (e.g., `Minus` becomes 0x0A),
+/// you just update this mapping.
+pub struct DefaultOpCodeMapping;
+
+impl OpCodeMapping for DefaultOpCodeMapping {
+    fn opcode_byte(&self, op: &OpCode) -> u8 {
+        match op {
+            OpCode::Noop  => 0x00, // 0x00 => NOOP
+            OpCode::Plus  => 0x01, // 0x01 => INTEGER_PLUS
+            OpCode::Minus => 0x04, // 0x04 => INTEGER_MINUS
+            OpCode::Mult  => 0x05, // 0x05 => INTEGER_MULT
+            OpCode::Dup   => 0x06, // 0x06 => INTEGER_DUP
+            OpCode::Pop   => 0x07, // 0x07 => INTEGER_POP
+        }
+    }
+}
+
+/// A convenient global `const` or `static` for quick usage.
+pub const DEFAULT_OP_MAPPING: DefaultOpCodeMapping = DefaultOpCodeMapping;
+
+// ----------------------------------------------------------------------------
+// S-Expression Parsing Helpers
+// ----------------------------------------------------------------------------
+
+/// A simple S-expression tree for textual representation: either an `Atom` or a `List`.
+#[derive(Debug, Clone, PartialEq)]
+pub enum SExpr {
+    Atom(String),
+    List(Vec<SExpr>),
+}
+
+/// Tokenize a string into parentheses and symbols (atoms).
+pub fn tokenize(s: &str) -> Vec<String> {
+    let mut tokens = Vec::new();
+    let mut current = String::new();
+
+    for c in s.chars() {
+        match c {
+            '(' | ')' => {
+                if !current.trim().is_empty() {
+                    tokens.push(current.trim().to_string());
+                }
+                current.clear();
+                tokens.push(c.to_string());
+            }
+            ' ' | '\t' | '\n' | '\r' => {
+                if !current.trim().is_empty() {
+                    tokens.push(current.trim().to_string());
+                    current.clear();
+                }
+            }
+            _ => {
+                current.push(c);
+            }
+        }
+    }
+
+    if !current.trim().is_empty() {
+        tokens.push(current.trim().to_string());
+    }
+
+    tokens
+}
+
+/// Recursive helper to parse a single S-expression from a list of tokens, advancing `pos`.
+fn parse_sexpr_internal(tokens: &[String], pos: &mut usize) -> Result<SExpr, String> {
+    if *pos >= tokens.len() {
+        return Err("Unexpected end of tokens".to_string());
+    }
+
+    let token = &tokens[*pos];
+    match token.as_str() {
+        "(" => {
+            *pos += 1; // consume '('
+            let mut items = Vec::new();
+            while *pos < tokens.len() && tokens[*pos] != ")" {
+                let expr = parse_sexpr_internal(tokens, pos)?;
+                items.push(expr);
+            }
+            if *pos >= tokens.len() {
+                return Err("Missing closing parenthesis".to_string());
+            }
+            *pos += 1; // consume ')'
+            Ok(SExpr::List(items))
+        }
+        ")" => Err("Unexpected ')'".to_string()),
+        _ => {
+            let atom_str = token.clone();
+            *pos += 1;
+            Ok(SExpr::Atom(atom_str))
+        }
+    }
+}
+
+/// Parse a full string into a single top-level `SExpr`, assuming balanced parentheses.
+pub fn parse_string_to_sexpr(s: &str) -> Result<SExpr, String> {
+    let tokens = tokenize(s);
+    let mut pos = 0;
+    let expr = parse_sexpr_internal(&tokens, &mut pos)?;
+    if pos < tokens.len() {
+        Err(format!(
+            "Extra tokens after parse: {:?}",
+            &tokens[pos..]
+        ))
+    } else {
+        Ok(expr)
+    }
+}
+
+/// Convert an S-expression to an **untyped** AST node.
+pub fn sexpr_to_untyped(expr: &SExpr) -> Result<UntypedAst, String> {
+    match expr {
+        SExpr::Atom(text) => {
+            // 1) Try parse as integer
+            if let Ok(val) = text.parse::<i32>() {
+                Ok(UntypedAst::IntLiteral(val))
+            } else {
+                // 2) Otherwise interpret as an opcode
+                match text.to_uppercase().as_str() {
+                    "+" => Ok(UntypedAst::Instruction(OpCode::Plus)),
+                    "-" => Ok(UntypedAst::Instruction(OpCode::Minus)),
+                    "*" => Ok(UntypedAst::Instruction(OpCode::Mult)),
+                    "DUP" => Ok(UntypedAst::Instruction(OpCode::Dup)),
+                    "POP" => Ok(UntypedAst::Instruction(OpCode::Pop)),
+                    // unknown => treat as Noop
+                    _ => Ok(UntypedAst::Instruction(OpCode::Noop)),
+                }
+            }
+        }
+        SExpr::List(items) => {
+            let mut sub_asts = Vec::new();
+            for child in items {
+                sub_asts.push(sexpr_to_untyped(child)?);
+            }
+            Ok(UntypedAst::Sublist(sub_asts))
+        }
+    }
+}
+
+// ----------------------------------------------------------------------------
+// (Optional) Placeholder for a future typed AST
+// ----------------------------------------------------------------------------
+
+// /// In the future, we plan to define a `TypedAst` enum that ensures each operation
+// /// has the correct number of typed children. We might also handle errors
+// /// if an operation expects two integer children, but the user tries to attach
+// /// a sublist or zero children, etc.
+// ///
+// /// For now, the untyped AST suffices for quick prototyping, but typed checks
+// /// will be crucial in more advanced genetic programming or static analysis scenarios.
+// #[derive(Debug, Clone)]
+// pub enum TypedAst {
+//     // e.g. IntLiteral(i32),
+//     //     Instruction(InstructionKind),
+// }
+
+// #[derive(Debug, Clone)]
+// pub enum InstructionKind {
+//     // e.g. Plus(Box<TypedAst>, Box<TypedAst>),
+//     //     Minus(Box<TypedAst>, Box<TypedAst>),
+//     //     Mult(Box<TypedAst>, Box<TypedAst>),
+//     //     Dup,
+//     //     Pop,
+// }
+
+// // etc.

offchain/src/compiler/mod.rs

@@ -0,0 +1,2 @@
+pub mod ast;
+pub mod push3_describtor;

offchain/src/compiler/push3_describtor.rs

@@ -0,0 +1,67 @@
+//! src/compiler/push3_descriptor.rs
+//! 
+//! A small module of helper functions to construct or interpret the 256-bit descriptors
+//! used by our on-chain `Push3Interpreter`. Each descriptor encodes a tag, an offset,
+//! a length, and any leftover bits (e.g., immediate data).
+
+use ethers::types::U256;
+
+/// The 256-bit descriptor layout is as follows:
+/// [  8 bits: tag  |  32 bits: offset  |  32 bits: length  |  184 bits: leftover ]
+///
+/// We'll define small helper functions to build or parse these. 
+/// Our `make_sublist_descriptor` is an example for tag=3 (SUBLIST).
+
+/// Tag constants, if you want them:
+pub const TAG_SUBLIST: u8 = 3;
+pub const TAG_INT_LITERAL: u8 = 2;
+pub const TAG_INSTRUCTION: u8 = 1;
+pub const TAG_NONE: u8 = 0;
+
+/// A small helper to shift the tag into the top 8 bits.
+#[inline]
+fn tag_bits(tag: u8) -> U256 {
+    U256::from(tag) << 248
+}
+
+/// Build a descriptor for a SUBLIST with the given offset and length (in bytes),
+/// leftover=0. 
+///
+/// # Example
+/// ```
+/// let desc = make_sublist_descriptor(0, code_bytes.len() as u32);
+/// // pass `desc` into the interpreter's exec stack
+/// ```
+pub fn make_sublist_descriptor(offset: u32, length: u32) -> U256 {
+    tag_bits(TAG_SUBLIST as u8)
+        | (U256::from(offset) << 216)
+        | (U256::from(length) << 184)
+        | U256::zero() // leftover
+}
+
+/// Possibly you want a more general helper that builds any descriptor:
+/// If you have other uses for leftover bits, you can pass that in:
+pub fn make_descriptor(tag: u8, offset: u32, length: u32, leftover: U256) -> U256 {
+    tag_bits(tag)
+        | (U256::from(offset) << 216)
+        | (U256::from(length) << 184)
+        | leftover
+}
+
+/// If you want to parse a descriptor, you can define getTag, getOffset, getLength, etc:
+pub fn get_tag(desc: U256) -> u8 {
+    // top 8 bits => shift right 248
+    (desc >> 248).as_u32() as u8
+}
+
+pub fn get_offset(desc: U256) -> u32 {
+    ((desc >> 216) & U256::from(u32::MAX)).as_u32()
+}
+
+pub fn get_length(desc: U256) -> u32 {
+    ((desc >> 184) & U256::from(u32::MAX)).as_u32()
+}
+
+pub fn get_low_184(desc: U256) -> U256 {
+    desc & ((U256::from(1u64) << 184) - 1)
+}

offchain/src/gp/generate.rs

@@ -0,0 +1,79 @@
+use rand::Rng;
+use crate::compiler::ast::{UntypedAst, OpCode};
+
+pub fn random_sublist_ast(rng: &mut impl Rng, max_depth: usize) -> UntypedAst {
+    // 1) Choose how many children the top-level `Sublist` will have.
+    let len = rng.gen_range(1..=3);
+
+    // 2) Build a vector of sub-ASTs by calling `random_ast` for each child
+    let mut children = Vec::with_capacity(len);
+    for _ in 0..len {
+        // We start at `depth=1` because the top-level sublist itself is `depth=0`.
+        children.push(random_ast(rng, 1, max_depth));
+    }
+
+    // 3) Return a `Sublist` as the root node
+    UntypedAst::Sublist(children)
+}
+
+/// Generate a random `UntypedAst` by recursively building sub-trees, 
+/// int literals, or instructions. 
+///
+/// - `depth` tracks how deep we are in the tree.
+/// - `max_depth` is the maximum allowed depth to prevent infinite recursion.
+pub fn random_ast(rng: &mut impl Rng, depth: usize, max_depth: usize) -> UntypedAst {
+    if depth >= max_depth {
+        // Return something "terminal," 
+        // e.g. an IntLiteral or a single Instruction
+        random_terminal(rng)
+    } else {
+        // Weighted choice: 
+        // 0 => IntLiteral, 
+        // 1 => single Instruction,
+        // 2 => Sublist with children
+        let choice = rng.gen_range(0..3);
+        match choice {
+            0 => UntypedAst::IntLiteral(rng.gen_range(-10..10)),
+            1 => UntypedAst::Instruction(random_opcode(rng)),
+            2 => {
+                // Make a sublist with 1..=3 children
+                let len = rng.gen_range(1..=3);
+                let mut children = Vec::with_capacity(len);
+                for _ in 0..len {
+                    children.push(random_ast(rng, depth + 1, max_depth));
+                }
+                UntypedAst::Sublist(children)
+            }
+            _ => unreachable!(),
+        }
+    }
+}
+
+/// Generate a random "terminal" node. 
+/// Typically either an int literal or a single instruction.
+fn random_terminal(rng: &mut impl Rng) -> UntypedAst {
+    // Weighted choice:
+    // 0 => IntLiteral
+    // 1 => single Instruction
+    let choice = rng.gen_range(0..2);
+    match choice {
+        0 => UntypedAst::IntLiteral(rng.gen_range(-10..10)),
+        1 => UntypedAst::Instruction(random_opcode(rng)),
+        _ => unreachable!(),
+    }
+}
+
+/// Generate a random `OpCode` from your known set of instructions.
+pub fn random_opcode(rng: &mut impl Rng) -> OpCode {
+    let choice = rng.gen_range(0..6); 
+    // because we have 6 variants: Noop, Plus, Minus, Mult, Dup, Pop
+    match choice {
+        0 => OpCode::Noop,
+        1 => OpCode::Plus,
+        2 => OpCode::Minus,
+        3 => OpCode::Mult,
+        4 => OpCode::Dup,
+        5 => OpCode::Pop,
+        _ => unreachable!(),
+    }
+}

offchain/src/gp/genetic_ops.rs

@@ -0,0 +1,64 @@
+use rand::Rng;
+use crate::compiler::ast::{UntypedAst, OpCode};
+use crate::gp::generate::{random_ast, random_opcode};
+
+/// Returns a new `UntypedAst` that is a mutated version of `original`.
+/// We do not modify `original`; we clone or build new pieces as needed.
+/// 
+/// - `depth`: current depth of this node,
+/// - `max_depth`: max allowed depth (to prevent infinite recursion).
+pub fn mutated_ast(original: &UntypedAst, rng: &mut impl Rng, depth: usize, max_depth: usize) -> UntypedAst {
+    // 10% chance: completely replace this node with a fresh random subtree
+    if rng.gen_range(0..100) < 10 {
+        return random_ast(rng, depth, max_depth);
+    }
+
+    match original {
+        UntypedAst::IntLiteral(val) => {
+            // Another small chance to replace the entire node with random subtree
+            if rng.gen_range(0..100) < 10 {
+                return random_ast(rng, depth, max_depth);
+            }
+
+            // Otherwise, "tweak" the int by a small offset
+            let delta = rng.gen_range(-2..=2);
+            let new_val = val.saturating_add(delta);
+            UntypedAst::IntLiteral(new_val)
+        }
+        UntypedAst::Instruction(op) => {
+            // 10% chance to replace node
+            if rng.gen_range(0..100) < 10 {
+                return random_ast(rng, depth, max_depth);
+            }
+
+            // 50% chance to pick a new opcode
+            // or else keep the same
+            if rng.gen_bool(0.5) {
+                UntypedAst::Instruction(random_opcode(rng))
+            } else {
+                // Just clone the original
+                UntypedAst::Instruction(op.clone())
+            }
+        }
+        UntypedAst::Sublist(children) => {
+            // 10% chance to replace this sublist entirely
+            if rng.gen_range(0..100) < 10 {
+                return random_ast(rng, depth, max_depth);
+            }
+
+            // Otherwise, mutate zero or more children
+            let mut new_children = children.clone();
+            if !new_children.is_empty() {
+                // Choose how many kids to mutate: 
+                // e.g., 1..=min(2, children.len())
+                let mut_count = rng.gen_range(1..=new_children.len().min(2));
+
+                for _ in 0..mut_count {
+                    let idx = rng.gen_range(0..new_children.len());
+                    new_children[idx] = mutated_ast(&new_children[idx], rng, depth+1, max_depth);
+                }
+            }
+            UntypedAst::Sublist(new_children)
+        }
+    }
+}

offchain/src/gp/mod.rs

@@ -0,0 +1,3 @@
+pub mod population;
+pub mod genetic_ops;
+pub mod generate;

offchain/src/gp/population.rs

@@ -0,0 +1,9 @@
+#[derive(Debug, Clone)]
+pub struct Individual {
+    pub fitness: f64,
+    // your Expr or bytecode or both
+}
+
+pub struct Population {
+    pub individuals: Vec<Individual>,
+}

offchain/src/helpers/artifact.rs

@@ -0,0 +1,41 @@
+//! src/helpers/artifact.rs
+//! A small helper module to read a Forge artifact JSON and extract the creation code.
+
+use anyhow::{anyhow, bail, Result};
+use serde::Deserialize;
+use std::fs;
+
+/// This mirrors the JSON structure: "bytecode": { "object": "...hex..." }
+#[derive(Debug, Deserialize)]
+struct BytecodeObject {
+    object: String,
+}
+
+/// The top-level artifact with a "bytecode" field.
+#[derive(Debug, Deserialize)]
+struct MyContractArtifact {
+    bytecode: BytecodeObject,
+}
+
+/// Reads the given JSON file (a Forge artifact) and returns the raw creation code bytes.
+///
+/// * `filename`: path to the artifact JSON (e.g. `../onchain/out/Push3Interpreter.sol/Push3Interpreter.json`)
+pub fn get_creation_code(filename: &str) -> Result<Vec<u8>> {
+    // 1) Read the JSON file
+    let creation_json = fs::read_to_string(filename)
+        .map_err(|e| anyhow!("Failed to read JSON file {}: {}", filename, e))?;
+    
+    // 2) Parse
+    let contract_artifact: MyContractArtifact = serde_json::from_str(&creation_json)
+        .map_err(|e| anyhow!("Failed to parse JSON artifact: {}", e))?;
+
+    // 3) Extract the hex code
+    let raw_hex = &contract_artifact.bytecode.object;
+    let stripped_hex = raw_hex.trim_start_matches("0x");
+
+    // 4) Convert from hex => bytes
+    match hex::decode(stripped_hex) {
+        Ok(bytes) => Ok(bytes),
+        Err(e) => bail!("Invalid hex for creation code: {e}"),
+    }
+}

offchain/src/helpers/mod.rs

@@ -0,0 +1 @@
+pub mod artifact;

offchain/src/lib.rs

@@ -0,0 +1,4 @@
+pub mod compiler;
+pub mod runner;
+pub mod gp;
+pub mod helpers;

offchain/src/main.rs

@@ -0,0 +1,118 @@
+// src/main.rs
+use std::env;
+
+// We’ll use your existing AST definitions for parsing
+use offchain::compiler::ast::{
+    parse_string_to_sexpr,
+    sexpr_to_untyped,
+    Push3Ast, // The trait
+    UntypedAst, // The untyped AST enum
+};
+
+use offchain::runner::revm_runner::{EvmRunner, Push3InterpreterOutputs}; // <--- We import our EvmRunner
+
+use anyhow::{anyhow, bail, Result};
+use hex;
+use serde::Deserialize; // For JSON artifact loading
+
+// If you still need these (not strictly required anymore):
+// use database::CacheDB;
+// use revm::{
+//     context::Context,
+//     context_interface::result::{ExecutionResult, Output},
+//     database_interface::EmptyDB,
+//     handler::EthHandler,
+//     primitives::{Bytes, TxKind},
+//     EvmCommit, MainEvm,
+// };
+use ethers::abi::{decode, ParamType};
+use ethers::types::U256;
+
+// ----------------------------------------------------------------------
+// JSON artifact struct, as before
+// ----------------------------------------------------------------------
+#[derive(Debug, Deserialize)]
+struct BytecodeObject {
+    object: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct MyContractArtifact {
+    bytecode: BytecodeObject,
+}
+
+// ----------------------------------------------------------------------
+// MAIN
+// ----------------------------------------------------------------------
+fn main() -> Result<()> {
+    // 1) Read CLI arguments for the Push3 program
+    let args: Vec<String> = env::args().collect();
+    if args.len() < 2 {
+        eprintln!("Usage: cargo run -- '<program>'");
+        eprintln!("Example: cargo run -- '((3 5 +) DUP MUL)'");
+        std::process::exit(1);
+    }
+    let program_str = &args[1];
+
+    // 2) Parse the string into an S-expression
+    let sexpr = parse_string_to_sexpr(program_str)
+        .map_err(|e| anyhow!("Error parsing S-expression: {}", e))?;
+
+    // 3) Convert SExpr => UntypedAst
+    let ast: UntypedAst = sexpr_to_untyped(&sexpr)
+        .map_err(|e| anyhow!("Error converting to UntypedAst: {}", e))?;
+
+    // 4) Convert UntypedAst => Push3 bytecode (for debugging, so we can see it)
+    let bytecode = ast.to_bytecode();
+
+    // 5) Print the resulting AST and bytecode (in hex)
+    println!("AST: {:?}", ast);
+    println!("Bytecode (hex): 0x{}", hex::encode(&bytecode));
+
+    // ----------------------------------------------------------------------
+    // Load the creation code (bytecode) from a JSON artifact
+    // ----------------------------------------------------------------------
+    let creation_hex_filename = "../onchain/out/Push3Interpreter.sol/Push3Interpreter.json";
+    let creation_json = std::fs::read_to_string(creation_hex_filename)
+        .map_err(|e| anyhow!("Failed to read JSON file {}: {}", creation_hex_filename, e))?;
+    let contract_artifact: MyContractArtifact = serde_json::from_str(&creation_json)
+        .map_err(|e| anyhow!("Failed to parse JSON artifact: {}", e))?;
+
+    let raw_hex = &contract_artifact.bytecode.object;
+    let stripped_hex = raw_hex.trim_start_matches("0x");
+
+    let creation_bytes = match hex::decode(stripped_hex) {
+        Ok(bytes) => bytes,
+        Err(e) => bail!("Invalid hex for creation code: {e}"),
+    };
+
+    println!(
+        "Loaded creation code ({} bytes) from {}",
+        creation_bytes.len(),
+        creation_hex_filename
+    );
+
+    // ----------------------------------------------------------------------
+    // 6) Deploy the interpreter in an ephemeral EVM using `EvmRunner`
+    // ----------------------------------------------------------------------
+    let mut runner = EvmRunner::new(creation_bytes)?;
+    println!("Interpreter deployed successfully in ephemeral EVM at: 0x{:x}", runner.interpreter_addr);
+
+    // ----------------------------------------------------------------------
+    // 7) Evaluate the AST in our EVM
+    // ----------------------------------------------------------------------
+    // We'll call `runner.run_ast(&ast)`, which:
+    // - Converts AST => push3 code,
+    // - Builds a sublist descriptor in the exec stack,
+    // - Calls `runInterpreter`,
+    // - Returns final stacks in a `Push3InterpreterOutputs`.
+    let outputs = runner.run_ast(&ast)?;
+    println!("Ran the AST successfully!");
+
+    // 8) Print the final stacks
+    println!("Final CODE stack: {:?}", outputs.final_code_stack);
+    println!("Final EXEC stack: {:?}", outputs.final_exec_stack);
+    println!("Final INT stack: {:?}", outputs.final_int_stack);
+
+    Ok(())
+}

offchain/src/runner/mod.rs

@@ -0,0 +1 @@
+pub mod revm_runner;

offchain/src/runner/revm_runner.rs

@@ -0,0 +1,232 @@
+//! src/evm_integration/revm_runner.rs
+//! 
+//! This module provides a thin wrapper around REVM to deploy a Push3Interpreter
+//! contract, then call its `runInterpreter(...)` function with flexible inputs/outputs,
+//! using the same style (Context::builder(), .modify_tx_chained, etc.) you had in your main.
+
+use anyhow::{anyhow, bail, Result};
+use ethers::abi::{encode, decode, Token, ParamType};
+use ethers::types::U256;
+use ethers::utils;
+use database::CacheDB;
+use revm::{
+    context::Context,
+    context::{BlockEnv, TxEnv, CfgEnv},
+    context_interface::result::{ExecutionResult, Output},
+    database_interface::EmptyDB,
+    handler::EthHandler,
+    primitives::{Bytes, TxKind}, // 4 generics
+    EvmCommit,
+    MainEvm,
+};
+
+// We import your AST definitions so we can call `ast.to_bytecode()`.
+use crate::compiler::ast::{UntypedAst, Push3Ast};
+
+// If you have a descriptor helper (like make_sublist_descriptor), bring it in:
+use crate::compiler::push3_describtor::make_sublist_descriptor;
+
+/// The input parameters for `runInterpreter(...)`: four fields (code, codeStack, execStack, intStack).
+pub struct Push3InterpreterInputs {
+    pub code: Vec<u8>,
+    pub init_code_stack: Vec<U256>,
+    pub init_exec_stack: Vec<U256>,
+    pub init_int_stack: Vec<i128>,
+}
+
+/// The outputs from `runInterpreter(...)`: three arrays for code/exec/int stacks.
+pub struct Push3InterpreterOutputs {
+    pub final_code_stack: Vec<U256>,
+    pub final_exec_stack: Vec<U256>,
+    pub final_int_stack: Vec<i128>,
+}
+
+/// A thin wrapper around REVM, parameterized by the 4 generics (DB, BLOCK, TX, CFG).
+/// - We store the ephemeral EVM instance,
+/// - We store the deployed address of your `Push3Interpreter`,
+/// - We provide `run_interpreter` and `run_ast`.
+pub struct EvmRunner {
+    /// The 4-parameter MainEvm:
+    ///   DB = CacheDB<EmptyDB>,
+    ///   BLOCK = BlockEnv,
+    ///   TX = TxEnv,
+    ///   CFG = CfgEnv
+    pub evm: MainEvm<CacheDB<EmptyDB>, BlockEnv, TxEnv, CfgEnv>,
+
+    /// The address where Push3Interpreter was deployed.
+    pub interpreter_addr: revm::primitives::Address,
+}
+
+impl EvmRunner {
+    /// Deploy a new ephemeral EVM with a "Create" transaction for the given `creation_code`.
+    ///
+    /// This matches your older style of:
+    ///  `MainEvm::new(Context::builder()... .with_db(...), EthHandler::default())`
+    pub fn new(creation_code: Vec<u8>) -> Result<Self> {
+        // 1) Create the EVM using your old style: `Context::builder()...`
+        //    Then pass to MainEvm::new(...).
+        //    The difference is that we explicitly say MainEvm<DB,BLOCK,TX,CFG>.
+        let mut evm = MainEvm::new(
+            // a) Prepare context with a chained transaction to CREATE
+            Context::builder()
+                .modify_tx_chained(|tx| {
+                    tx.transact_to = TxKind::Create;
+                    tx.data = Bytes::from(creation_code.clone());
+                })
+                // b) Provide ephemeral DB
+                .with_db(CacheDB::<EmptyDB>::default()),
+            // c) The EthHandler for block/tx environment logic
+            EthHandler::default(),
+        );
+
+        // 2) Execute the CREATE transaction
+        let creation_result = evm.exec_commit()?;
+        let ExecutionResult::Success {
+            output: Output::Create(_, Some(deployed_addr)),
+            ..
+        } = creation_result
+        else {
+            bail!("Interpreter deployment failed or no address returned: {creation_result:#?}");
+        };
+
+        // 3) Return the EvmRunner
+        Ok(Self {
+            evm,
+            interpreter_addr: deployed_addr,
+        })
+    }
+
+    /// Call `runInterpreter(bytes,uint256[],uint256[],int256[])` on the deployed contract,
+    /// returning the final code/exec/int stacks.
+    pub fn run_interpreter(
+        &mut self,
+        inputs: &Push3InterpreterInputs
+    ) -> Result<Push3InterpreterOutputs> {
+        // 1) Build function selector
+        let func_selector = &utils::id("runInterpreter(bytes,uint256[],uint256[],int256[])")[0..4];
+
+        // 2) Convert each field to `ethers::abi::Token`
+        let code_token = Token::Bytes(inputs.code.clone());
+        let init_code_stack = Token::Array(
+            inputs.init_code_stack
+                .iter()
+                .map(|&u| Token::Uint(u))
+                .collect()
+        );
+        let init_exec_stack = Token::Array(
+            inputs.init_exec_stack
+                .iter()
+                .map(|&u| Token::Uint(u))
+                .collect()
+        );
+        let init_int_stack = Token::Array(
+            inputs.init_int_stack
+                .iter()
+                .map(|&val_i128| {
+                    // store i128 as a U256. If you need negative values, do a two’s complement approach.
+                    let as_u128 = val_i128 as u128;
+                    Token::Int(U256::from(as_u128))
+                })
+                .collect()
+        );
+
+        // 3) Encode
+        let encoded_args = encode(&[
+            code_token,
+            init_code_stack,
+            init_exec_stack,
+            init_int_stack,
+        ]);
+
+        // 4) Build final call data
+        let mut call_data = Vec::from(func_selector);
+        call_data.extend_from_slice(&encoded_args);
+
+        // 5) Modify the transaction to CALL the deployed interpreter
+        self.evm.context.modify_tx(|tx| {
+            tx.transact_to = TxKind::Call(self.interpreter_addr);
+            tx.data = Bytes::from(call_data);
+            tx.nonce = 1; // increment nonce to avoid reuse
+        });
+
+        // 6) Execute the call
+        let call_result = self.evm.transact()?;
+        match &call_result.result {
+            ExecutionResult::Success {
+                output: Output::Call(return_data),
+                ..
+            } => {
+                // 7) Decode (uint256[], uint256[], int256[])
+                let param_types = &[
+                    ParamType::Array(Box::new(ParamType::Uint(256))), // finalCodeStack
+                    ParamType::Array(Box::new(ParamType::Uint(256))), // finalExecStack
+                    ParamType::Array(Box::new(ParamType::Int(256))),  // finalIntStack
+                ];
+                let decoded = decode(param_types, return_data)
+                    .map_err(|e| anyhow!("Failed to decode return data: {e}"))?;
+
+                // parse each array
+                let final_code_stack = match &decoded[0] {
+                    Token::Array(arr) => arr.iter().filter_map(|t| {
+                        if let Token::Uint(u) = t { Some(*u) } else { None }
+                    }).collect(),
+                    _ => Vec::new(),
+                };
+                let final_exec_stack = match &decoded[1] {
+                    Token::Array(arr) => arr.iter().filter_map(|t| {
+                        if let Token::Uint(u) = t { Some(*u) } else { None }
+                    }).collect(),
+                    _ => Vec::new(),
+                };
+                let final_int_stack = match &decoded[2] {
+                    Token::Array(arr) => arr.iter().filter_map(|t| {
+                        if let Token::Int(u256_val) = t {
+                            // read only the lower 128 bits => ignoring sign extension
+                            let lo = u256_val.low_u128();
+                            Some(lo as i128)
+                        } else {
+                            None
+                        }
+                    }).collect(),
+                    _ => Vec::new(),
+                };
+
+                Ok(Push3InterpreterOutputs {
+                    final_code_stack,
+                    final_exec_stack,
+                    final_int_stack,
+                })
+            }
+            ExecutionResult::Revert { gas_used, output } => {
+                bail!("Call reverted: gas used={gas_used:?}, output={output:?}")
+            }
+            other => {
+                bail!("Call failed: {other:?}")
+            }
+        }
+    }
+
+    /// A convenience method to run an `UntypedAst`:
+    /// - Convert AST => push3 code,
+    /// - Build a sublist descriptor in the exec stack,
+    /// - Call `run_interpreter`.
+    pub fn run_ast(&mut self, ast: &UntypedAst) -> Result<Push3InterpreterOutputs> {
+        // 1) Convert AST => push3 bytecode
+        let code_bytes = ast.to_bytecode();
+        let code_len = code_bytes.len() as u32;
+
+        // 2) Build a sublist descriptor
+        let descriptor = make_sublist_descriptor(0, code_len);
+
+        // 3) Put code in `code` and sublist descriptor in `execStack`
+        let inputs = Push3InterpreterInputs {
+            code: code_bytes,
+            init_code_stack: Vec::new(),
+            init_exec_stack: vec![descriptor],
+            init_int_stack: Vec::new(),
+        };
+
+        // 4) Run interpreter
+        self.run_interpreter(&inputs)
+    }
+}

tokenomics.md

@@ -1,163 +0,0 @@
-# Home of Dumplings / \$DPL Tokenomics
-
-## 1. Overview
-
-The Home of Dumplings protocol deploys AI agents that solve optimization problems for DeFi users and protocols, addressing tasks such as liquidity management and parameter tuning. The ecosystem operates through **Tasks** hosted on-chain and populations of solution programs evolved off-chain by the Optimizer Pool.
-
-**\$DPL** is the native token powering this ecosystem. Its primary roles include:
-
-1. **Payment**: Clients pay invocation or subscription fees in \$DPL.
-2. **Staking and Governance**: Token holders stake \$DPL to secure the protocol, join the optimizer pool or participate in governance.
-3. **Rewards**: Optimizer Pool nodes earn \$DPL for validated contributions to the evolution of programs.
-
----
-
-## 2. Token Supply and Distribution
-
-### Fixed Supply
-
-- **Total Supply**: \$DPL has a fixed supply (e.g., 100M tokens), minted at genesis.
-- **No Inflation**: No further token minting or emission beyond the initial allocation.
-
-### Allocation of Supply
-
-1. **Uniswap V3 Liquidity Pool**
-
-   - All of the supply is allocated to a Uniswap V3 liquidity pool over a wide price range.
-   - Multiple price ranges hold extra liquidity to ensure stable price discovery.
-
-2. **Team**
-
-   - A vesting contract purchases a small portion (e.g., 10-15%) of the cheapest tokens from the pool right after deployment and allocates them to the team.
-
-3. **Treasury**
-
-   - An NFT minting contract purchases a small portion (e.g., 5-10%) right after the vesting contract before other buyers come in. The tokens are packaged into nice-looking NFTs.
-   - These NFTs are sold on marketplaces like OpenSea, redeemable for tokens. The proceeds are transferred to the team multisig, forming the treasury.
-
----
-
-## 3. Revenue Model
-
-### Fee Structure
-
-1. **Invocation Fees**
-
-   - Charged for AI agents evolved with synthetic data.
-   - Paid in \$DPL or other currencies auto-converted into \$DPL and routed to the protocol reward pools.
-
-2. **Subscription Fees**
-
-   - Charged for AI agents evolved with synthetic data initially, but are continuously improved by backtesting with real data.
-   - Periodic payment in \$DPL or other currencies auto-converted into \$DPL and routed to the protocol reward pools.
-
-### Reward Allocation
-
-- A portion of the fees collected funds rewards for the Optimizer Pool nodes that contribute validated solutions to Tasks.
-- Governance determines the exact split between:
-  - Optimizer Pool rewards.
-  - Treasury for operational funding.
-  - Potential staking rewards.
-
----
-
-## 4. Staking
-
-### Types of Stakers
-
-1. **Council Node Stakers**
-
-   - Nodes in the Optimizer Pool stake \$DPL to become eligible for selection to the Council.
-   - Council members validate and vote on improved solutions to Tasks.
-   - **Slashing Mechanism**: If a Council member votes against the majority decision, they are penalized by slashing a portion of their staked tokens.
-
-2. **Investor Stakers**
-
-   - Investors stake \$DPL to earn a share of the protocol’s revenue.
-   - Revenue is comprised of invocation and subscription fees, a part is distributed as staking rewards.
-
-### Risk Backstop
-
-- Stakers collectively backstop potential risks associated with the AI agents.
-- If an AI agent malfunctions (e.g., outputs suboptimal or incorrect decisions due to flaws in the algorithm), affected users may be compensated via the staking pool, reducing the system’s reputational and financial risk.
-- Governance defines the conditions for such compensations, ensuring fairness and transparency.
-
----
-
-## 5. Governance
-
-Voting weight is proportional to the amount of \$DPL staked.
-
-### Governance Mechanics
-
-1. **Voting Rights**
-
-   - All stakers can participate in governance, regardless of whether they are nodes or investors.
-   - Proposals focus on:
-     - Adjusting fee parameters (e.g., invocation and subscription fees).
-     - Allocating Optimizer Pool rewards.
-     - Defining compensation rules for Risk Backstop events.
-
-2. **Council Randomness**
-
-   - Optimizer Pool nodes with staked \$DPL can be selected for the Council via a verifiable random selection process.
-   - The Council validates and votes on improved solutions to Tasks.
-
----
-
-## 6. NFT-Based Early Bird Mechanism
-
-1. **Purpose**
-
-   - Raise initial funding and incentivize early supporters.
-
-2. **Mechanics**
-
-   - NFTs represent the right to claim a specified quantity of \$DPL at a discounted rate.
-   - Sold on marketplaces like OpenSea.
-
-3. **Redemption**
-
-   - Upon redemption, the NFT is burned, and the holder receives their allocated \$DPL.
-   - Vesting or time locks may apply to align with protocol growth.
-
----
-
-## 7. Fee Usage and Distribution
-
-- **Optimizer Pool Rewards**: A fraction of collected fees funds rewards for Optimizer Pool nodes.
-- **Treasury**: Supports operations, development, and marketing initiatives.
-- **Stakers**: Receive a share of fees as staking rewards, subject to governance decisions.
-
----
-
-## 8. Launch and Go-to-Market Strategy
-
-### Initial Liquidity Deployment
-
-- Deploy a majority of \$DPL supply into Uniswap V3 pools.
-- Use multiple concentrated price ranges to establish liquidity depth and facilitate market stability.
-
-### Early Bird NFT Sale
-
-- Launch a curated NFT collection for discounted \$DPL rights.
-- Drive initial funding and engage early adopters.
-
-### Target Customers
-
-- Position DeFi protocols as key customers for SoLUSH’s optimization services.
-- Focus marketing on showcasing cost-saving and performance-enhancing use cases.
-
----
-
-## 9. Conclusion
-
-The \$DPL tokenomics framework is designed to:
-
-- Provide immediate utility through payment and staking mechanisms.
-- Incentivize Optimizer Pool participation via rewards for validated solutions.
-- Ensure sustainable growth through fixed supply, governance, and clear fee allocation.
-
-This structure ensures the long-term viability and scalability of the SoLUSH ecosystem, while fostering community involvement and alignment with protocol goals.
-
-