completed positive unit test coverage for available bool opcodes

v1.9.5

.envrc

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

.gitignore

@@ -1,2 +1,7 @@
-cache/
+onchain/cache/
-out/
+onchain/out/
+
+offchain/target/
+
+.direnv
+.env

.gitmodules

@@ -1,3 +1,4 @@
-[submodule "lib/forge-std"]
+
-	path = lib/forge-std
+[submodule "onchain/lib/forge-std"]
+	path = onchain/lib/forge-std
 	url = https://github.com/foundry-rs/forge-std

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,18 @@
+[package]
+name = "offchain"
+version = "0.1.0"
+edition = "2021"
+
+[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/compiler/ast.rs

@@ -0,0 +1,530 @@
+// pub trait Push3Ast {
+//     /// Convert this AST into a bytecode array (Push3 tokens).
+//     fn to_bytecode(&self) -> Vec<u8>;
+
+//     // Parse an AST from bytecode (the "decompiler"), if possible.
+//     // Possibly returns a Result in case of partial/invalid parse.
+//     // fn from_bytecode(data: &[u8]) -> Self
+//     // where
+//     //     Self: Sized;
+
+//     // Randomly mutate this AST in-place (GP mutation).
+//     // fn mutate(&mut self, rng: &mut impl rand::Rng);
+
+//     // Possibly a "crossover" method, or we do it externally.
+//     // fn crossover(&self, other: &Self, rng: &mut impl rand::Rng) -> Self;
+
+//     // Evaluate the AST with some input(s).
+//     // Optionally do we want this or do we always run in EVM? 
+//     // We can stub it or do an interpret approach for local test.
+//     // fn interpret_locally(&self, inputs: &[i32]) -> Vec<i32>;
+// }
+
+
+// #[derive(Debug, Clone)]
+// pub enum TypedAst {
+//     IntLiteral(i32),
+//     Instruction(InstructionKind),
+// }
+
+// #[derive(Debug, Clone)]
+// pub enum InstructionKind {
+//     Plus(Box<TypedAst>, Box<TypedAst>),
+//     Minus(Box<TypedAst>, Box<TypedAst>),
+//     Mult(Box<TypedAst>, Box<TypedAst>),
+//     Dup,  // 0 children
+//     Pop,  // 0 children
+// }
+
+// impl Push3Ast for TypedAst {
+//     fn to_bytecode(&self) -> Vec<u8> {
+//         // do typed encoding: 
+//         // - for Plus(e1, e2): e1 -> bytecode, e2 -> bytecode, then PLUS opcode
+//         unimplemented!()
+//     }
+
+//     // fn from_bytecode(data: &[u8]) -> Self {
+//     //     // parse in a strictly typed manner; might fail or panic 
+//     //     // if the code doesn't line up properly
+//     //     unimplemented!()
+//     // }
+
+//     // fn mutate(&mut self, rng: &mut impl rand::Rng) {
+//     //     // e.g. randomly pick a node, replace it with something 
+//     //     // that respects the typed structure
+//     //     unimplemented!()
+//     // }
+
+//     // fn interpret_locally(&self, inputs: &[i32]) -> Vec<i32> {
+//     //     // do a normal expression evaluation. If a node is "Plus(a,b)",
+//     //     // interpret (a) + interpret(b).
+//     //     unimplemented!()
+//     // }
+// }
+
+// #[derive(Debug, Clone)]
+// pub enum UntypedAst {
+//     /// A single token in a list-based approach, e.g. "Integer literal"
+//     IntLiteral(i32),
+
+//     /// "Instruction" might be a simple variant with no children, 
+//     /// because the stack-based evaluation decides how many arguments it consumes.
+//     Instruction(OpCode),  
+
+//     /// A sublist of tokens, e.g. "( 2 3 DUP + )"
+//     Sublist(Vec<UntypedAst>),
+// }
+
+// /// Possibly an enum for OpCode:
+// #[derive(Debug, Clone)]
+// pub enum OpCode {
+//     Noop,
+//     Plus,
+//     Minus,
+//     Mult,
+//     Dup,
+//     Pop,
+//     // maybe Unknown => treat as no-op
+// }
+
+// // impl Push3Ast for UntypedAst {
+// //     fn to_bytecode(&self) -> Vec<u8> {
+// //         // flatten out sublists vs instructions
+// //         unimplemented!()
+// //     }
+
+// //     // fn from_bytecode(data: &[u8]) -> Self {
+// //     //     // parse "0x02 => INT_LITERAL => read next 4 bytes" 
+// //     //     // instructions might have no subchildren
+// //     //     unimplemented!()
+// //     // }
+
+// //     // fn mutate(&mut self, rng: &mut impl rand::Rng) {
+// //     //     // can randomly insert unknown tokens, reorder sublists, etc.
+// //     //     // possibly produce "invalid ops => noops"
+// //     //     unimplemented!()
+// //     // }
+
+// //     // fn interpret_locally(&self, inputs: &[i32]) -> Vec<i32> {
+// //     //     // push-based interpretation:
+// //     //     // sublist => interpret each item in sequence
+// //     //     // if an instruction sees insufficient args => no-op
+// //     //     unimplemented!()
+// //     // }
+// // }
+
+// use crate::compiler::ast::Push3Ast;
+
+// /// An untyped AST node, matching your Push3 structure.
+// #[derive(Debug, Clone)]
+// pub enum UntypedAst {
+//     /// A single integer literal.
+//     IntLiteral(i32),
+//     /// A single push instruction (no subchildren).
+//     Instruction(OpCode),
+//     /// A sublist of items, each of which is another UntypedAst.
+//     Sublist(Vec<UntypedAst>),
+// }
+
+// /// Your Push3 opcodes in an untyped form.
+// #[derive(Debug, Clone)]
+// pub enum OpCode {
+//     Noop,
+//     Plus,
+//     Minus,
+//     Mult,
+//     Dup,
+//     Pop,
+// }
+
+// /// Implementation of `Push3Ast` for `UntypedAst`.
+// ///
+// /// This will produce **bytecode** compatible with your Solidity `Push3Interpreter`:
+// /// 
+// /// - `0x00` => NOOP
+// /// - `0x01` => INTEGER_PLUS
+// /// - `0x02` => INT_LITERAL => next 4 bytes (little-endian i32)
+// /// - `0x03` => SUBLIST => next 2 bytes (big-endian `u16` length), then the sublist contents
+// /// - `0x04` => INTEGER_MINUS
+// /// - `0x05` => INTEGER_MULT
+// /// - `0x06` => INTEGER_DUP
+// /// - `0x07` => INTEGER_POP
+// ///
+// /// In the Solidity parser, `SUBLIST (0x03)` consumes two bytes to determine
+// /// how many bytes of tokens to read in that sublist.
+// impl Push3Ast for UntypedAst {
+//     /// Convert this untyped AST into a flattened push3 bytecode sequence.
+//     fn to_bytecode(&self) -> Vec<u8> {
+//         match self {
+//             UntypedAst::IntLiteral(val) => {
+//                 // 0x02 followed by 4 bytes of i32 (little-endian)
+//                 let mut bytes = Vec::with_capacity(1 + 4);
+//                 bytes.push(0x02);
+//                 bytes.extend_from_slice(&val.to_le_bytes());
+//                 bytes
+//             }
+//             UntypedAst::Instruction(op) => {
+//                 // Single opcode byte
+//                 let opcode_byte = match op {
+//                     OpCode::Noop  => 0x00,
+//                     OpCode::Plus  => 0x01,
+//                     OpCode::Minus => 0x04,
+//                     OpCode::Mult  => 0x05,
+//                     OpCode::Dup   => 0x06,
+//                     OpCode::Pop   => 0x07,
+//                 };
+//                 vec![opcode_byte]
+//             }
+//             UntypedAst::Sublist(children) => {
+//                 // 0x03 => SUBLIST
+//                 // Then 2 bytes for length (big-endian u16),
+//                 // Then the concatenated bytecode for all children.
+//                 let mut payload = Vec::new();
+//                 for child in children {
+//                     let child_bytes = child.to_bytecode();
+//                     payload.extend_from_slice(&child_bytes);
+//                 }
+//                 let sub_len = payload.len() as u16; // assume it fits in 65535
+//                 let mut bytes = Vec::with_capacity(1 + 2 + payload.len());
+//                 bytes.push(0x03);
+//                 // Store the sublist length as big-endian, because readUint16 in solidity
+//                 // does `val = uint16(word >> 240)` (effectively big-endian).
+//                 bytes.extend_from_slice(&sub_len.to_be_bytes());
+//                 // Then the actual sublist payload
+//                 bytes.extend_from_slice(&payload);
+//                 bytes
+//             }
+//         }
+//     }
+// }
+
+
+// #[derive(Debug, Clone, PartialEq)]
+// pub enum SExpr {
+//     Atom(String),          // e.g. "3", "DUP", "+"
+//     List(Vec<SExpr>),      // e.g. (3 5 +)
+// }
+
+// fn tokenize(s: &str) -> Vec<String> {
+//     let mut tokens = Vec::new();
+//     let mut current = String::new();
+
+//     for c in s.chars() {
+//         match c {
+//             '(' | ')' => {
+//                 // If we were building up an atom, push it first
+//                 if !current.trim().is_empty() {
+//                     tokens.push(current.trim().to_string());
+//                 }
+//                 current.clear();
+//                 // Then push the single-char token
+//                 tokens.push(c.to_string());
+//             }
+//             ' ' | '\t' | '\n' | '\r' => {
+//                 // Whitespace => if we have an atom, finish it
+//                 if !current.trim().is_empty() {
+//                     tokens.push(current.trim().to_string());
+//                     current.clear();
+//                 }
+//             }
+//             _ => {
+//                 // Part of an atom
+//                 current.push(c);
+//             }
+//         }
+//     }
+
+//     // If something is left in 'current' at the end
+//     if !current.trim().is_empty() {
+//         tokens.push(current.trim().to_string());
+//     }
+
+//     tokens
+// }
+
+
+// fn parse_sexpr(tokens: &[String], pos: &mut usize) -> Result<SExpr, String> {
+//     // If we’re out of tokens, error
+//     if *pos >= tokens.len() {
+//         return Err("Unexpected end of tokens".into());
+//     }
+
+//     let token = &tokens[*pos];
+//     match token.as_str() {
+//         "(" => {
+//             // Parse a list
+//             *pos += 1; // consume '('
+//             let mut list_items = Vec::new();
+
+//             while *pos < tokens.len() && tokens[*pos] != ")" {
+//                 let expr = parse_sexpr(tokens, pos)?;
+//                 list_items.push(expr);
+//             }
+
+//             if *pos >= tokens.len() {
+//                 return Err("Missing closing parenthesis".into());
+//             }
+//             // consume ")"
+//             *pos += 1;
+//             Ok(SExpr::List(list_items))
+//         }
+//         ")" => {
+//             // Should never parse_sexpr starting with ')'
+//             Err("Unexpected ')'".into())
+//         }
+//         _ => {
+//             // Atom
+//             let atom_str = token.clone();
+//             *pos += 1;
+//             Ok(SExpr::Atom(atom_str))
+//         }
+//     }
+// }
+
+// /// Parse an entire string into a single top-level `SExpr`.
+// fn parse_string_to_sexpr(s: &str) -> Result<SExpr, String> {
+//     let tokens = tokenize(s);
+//     let mut pos = 0;
+//     let expr = parse_sexpr(&tokens, &mut pos)?;
+
+//     // If there's leftover tokens, optionally check
+//     if pos < tokens.len() {
+//         return Err(format!("Extra tokens after parse: {:?}", &tokens[pos..]));
+//     }
+
+//     Ok(expr)
+// }
+
+// fn sexpr_to_untyped(expr: &SExpr) -> Result<UntypedAst, String> {
+//     match expr {
+//         SExpr::Atom(text) => {
+//             // 1) try to parse as i32
+//             if let Ok(val) = text.parse::<i32>() {
+//                 Ok(UntypedAst::IntLiteral(val))
+//             } else {
+//                 // 2) otherwise parse as OpCode symbol
+//                 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)),
+//                     // more opcodes ...
+//                     _ => Ok(UntypedAst::Instruction(OpCode::Noop))
+//                 }
+//             }
+//         }
+//         SExpr::List(list) => {
+//             // parse each child into UntypedAst
+//             let mut result = Vec::new();
+//             for child in list {
+//                 result.push(sexpr_to_untyped(child)?);
+//             }
+//             Ok(UntypedAst::Sublist(result))
+//         }
+//     }
+// }
+
+// src/compiler/ast.rs
+
+pub trait Push3Ast {
+    /// Convert this AST into a bytecode array (Push3 tokens).
+    fn to_bytecode(&self) -> Vec<u8>;
+}
+
+/* --------------------------------------------
+   1) TypedAst stubs (optional)
+-------------------------------------------- */
+
+#[derive(Debug, Clone)]
+pub enum TypedAst {
+    IntLiteral(i32),
+    Instruction(InstructionKind),
+}
+
+#[derive(Debug, Clone)]
+pub enum InstructionKind {
+    Plus(Box<TypedAst>, Box<TypedAst>),
+    Minus(Box<TypedAst>, Box<TypedAst>),
+    Mult(Box<TypedAst>, Box<TypedAst>),
+    Dup,
+    Pop,
+}
+
+// Example stub; not fully implemented
+impl Push3Ast for TypedAst {
+    fn to_bytecode(&self) -> Vec<u8> {
+        unimplemented!("TypedAst::to_bytecode not yet implemented");
+    }
+}
+
+/* --------------------------------------------
+   2) UntypedAst + OpCode
+-------------------------------------------- */
+
+#[derive(Debug, Clone)]
+pub enum UntypedAst {
+    IntLiteral(i32),
+    Instruction(OpCode),
+    Sublist(Vec<UntypedAst>),
+}
+
+#[derive(Debug, Clone)]
+pub enum OpCode {
+    Noop,
+    Plus,
+    Minus,
+    Mult,
+    Dup,
+    Pop,
+}
+
+/// Implementation of `Push3Ast` for `UntypedAst`.
+/// Matches the Solidity-based Push3Interpreter token IDs.
+impl Push3Ast for UntypedAst {
+    fn to_bytecode(&self) -> Vec<u8> {
+        match self {
+            UntypedAst::IntLiteral(val) => {
+                // 0x02 => INT_LITERAL => next 4 bytes (little-endian i32)
+                let mut bytes = Vec::with_capacity(1 + 4);
+                bytes.push(0x02);
+                bytes.extend_from_slice(&val.to_be_bytes());
+                bytes
+            }
+            UntypedAst::Instruction(op) => {
+                let opcode_byte = match op {
+                    OpCode::Noop  => 0x00,
+                    OpCode::Plus  => 0x01,
+                    OpCode::Minus => 0x04,
+                    OpCode::Mult  => 0x05,
+                    OpCode::Dup   => 0x06,
+                    OpCode::Pop   => 0x07,
+                };
+                vec![opcode_byte]
+            }
+            UntypedAst::Sublist(children) => {
+                // 0x03 => SUBLIST => next 2 bytes = big-endian length, then sub-payload
+                let mut payload = Vec::new();
+                for child in children {
+                    payload.extend(child.to_bytecode());
+                }
+                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
+                bytes.extend_from_slice(&payload);
+                bytes
+            }
+        }
+    }
+}
+
+/* --------------------------------------------
+   3) S-expression parsing helpers
+-------------------------------------------- */
+#[derive(Debug, Clone, PartialEq)]
+pub enum SExpr {
+    Atom(String),
+    List(Vec<SExpr>),
+}
+
+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
+}
+
+fn parse_sexpr_internal(tokens: &[String], pos: &mut usize) -> Result<SExpr, String> {
+    if *pos >= tokens.len() {
+        return Err("Unexpected end of tokens".into());
+    }
+
+    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".into());
+            }
+            *pos += 1; // consume ')'
+            Ok(SExpr::List(items))
+        }
+        ")" => {
+            Err("Unexpected ')'".into())
+        }
+        _ => {
+            let atom = token.clone();
+            *pos += 1;
+            Ok(SExpr::Atom(atom))
+        }
+    }
+}
+
+/// Parse an entire string into a single top-level `SExpr`.
+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() {
+        return Err(format!("Extra tokens after parse: {:?}", &tokens[pos..]));
+    }
+    Ok(expr)
+}
+
+/// Convert an SExpr => UntypedAst
+pub fn sexpr_to_untyped(expr: &SExpr) -> Result<UntypedAst, String> {
+    match expr {
+        SExpr::Atom(text) => {
+            if let Ok(val) = text.parse::<i32>() {
+                Ok(UntypedAst::IntLiteral(val))
+            } else {
+                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)),
+                    _     => 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))
+        }
+    }
+}

offchain/src/compiler/mod.rs

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

offchain/src/evm_integration/mod.rs

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

offchain/src/gp/genetic_ops.rs

@@ -0,0 +1,10 @@
+// use crate::compiler::ast::{Expr};
+
+// pub fn crossover(a: &Expr, b: &Expr) -> (Expr, Expr) {
+//     // stub
+//     (a.clone(), b.clone())
+// }
+
+// pub fn mutate(expr: &mut Expr) {
+//     // stub
+// }

offchain/src/gp/mod.rs

@@ -0,0 +1,13 @@
+pub mod population;
+pub mod genetic_ops;
+// pub mod fitness;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_dummy() {
+        assert_eq!(2+2, 4);
+    }
+}

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>,
+}

onchain/src/Push3IntAdapter.sol

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import "forge-std/console.sol";
+import {Push3Interpreter} from "../src/Push3Interpreter.sol";
+
+/**
+ * @title Push3IntAdapter
+ * @dev An adapter contract for our Push3Interpreter that provides
+ *      various integer-only I/O function overloads. We now create
+ *      a SUBLIST descriptor for the entire code array, placing it
+ *      on the EXEC stack. We ignore finalCodeStack/finalExecStack 
+ *      to avoid compiler warnings.
+ */
+contract Push3IntAdapter {
+    Push3Interpreter public interpreter;
+
+    constructor(address _interpreter) {
+        interpreter = Push3Interpreter(_interpreter);
+    }
+
+    /**
+     * @notice Utility function to build a single sublist descriptor
+     *         covering the entire `code` array, offset=0, length=code.length.
+     */
+    function _makeFullSublistDescriptor(bytes calldata code)
+        internal
+        view
+        returns (uint256)
+    {
+        // CodeTag.SUBLIST is typically enum = 4, but
+        // let's fetch it via
+        //   (uint8)Push3Interpreter.CodeTag.SUBLIST
+        // or we can directly pass 3 if we know the numeric value.
+
+        // We'll do:
+        return interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST, // the tag
+            0,                                // offset
+            uint32(code.length),             // length of entire code array
+            0                                 // leftover bits=0
+        );
+    }
+
+    /**
+     * @notice Single int input, single int output.
+     *  1) Build a sublist descriptor for the entire code,
+     *  2) Place that descriptor in the EXEC stack,
+     *  3) Preload `in1` on the integer stack,
+     *  4) Run the interpreter,
+     *  5) Return top of final int stack.
+     */
+    function run1In1Out(bytes calldata code, int256 in1)
+        external
+        view
+        returns (int256 out1)
+    {
+        // 1) Build the sublist descriptor
+        uint256 fullDesc = _makeFullSublistDescriptor(code);
+
+        // 2) EXEC stack of size 1
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = fullDesc;
+
+        // No code stack
+        uint256[] memory initCodeStack = new uint256[](0);
+
+        // 3) Preload int stack
+        int256[] memory initIntStack = new int256[](1);
+        initIntStack[0] = in1;
+
+        // No bool stack
+        bool[] memory initBoolStack = new bool[](0);
+
+        // 4) Run
+        (, , int256[] memory finalIntStack,) =
+            interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        // 5) Return top of final int stack
+        require(finalIntStack.length > 0, "No integer output produced");
+        out1 = finalIntStack[finalIntStack.length - 1];
+    }
+
+    /**
+     * @notice Two ints input, single int output
+     */
+    function run2In1Out(bytes calldata code, int256 in1, int256 in2)
+        external
+        view
+        returns (int256 out1)
+    {
+        uint256 fullDesc = _makeFullSublistDescriptor(code);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = fullDesc;
+
+        uint256[] memory initCodeStack = new uint256[](0);
+
+        int256[] memory initIntStack = new int256[](2);
+        initIntStack[0] = in1;
+        initIntStack[1] = in2;
+
+        bool[] memory initBoolStack = new bool[](0);
+
+        (, , int256[] memory finalIntStack,) =
+            interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        require(finalIntStack.length > 0, "No integer output");
+
+        out1 = finalIntStack[finalIntStack.length - 1];
+    }
+
+    /**
+     * @notice Single int input, two int outputs
+     */
+    function run1In2Out(bytes calldata code, int256 in1)
+        external
+        view
+        returns (int256 out1, int256 out2)
+    {
+        uint256 fullDesc = _makeFullSublistDescriptor(code);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = fullDesc;
+
+        uint256[] memory initCodeStack = new uint256[](0);
+
+        int256[] memory initIntStack = new int256[](1);
+        initIntStack[0] = in1;
+
+        bool[] memory initBoolStack = new bool[](0);
+
+        (, , int256[] memory finalIntStack,) =
+            interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        require(finalIntStack.length >= 2, "Not enough outputs");
+        out1 = finalIntStack[finalIntStack.length - 1];
+        out2 = finalIntStack[finalIntStack.length - 2];
+    }
+
+    /**
+     * @notice Zero int input, returns entire final int stack
+     */
+    function run0InNOut(bytes calldata code)
+        external
+        view
+        returns (int256[] memory)
+    {
+        uint256 fullDesc = _makeFullSublistDescriptor(code);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = fullDesc;
+
+        uint256[] memory initCodeStack = new uint256[](0);
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        (, , int256[] memory finalIntStack,) =
+            interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        return finalIntStack;
+    }
+}

onchain/src/Push3Interpreter.sol

@@ -0,0 +1,562 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import "forge-std/console.sol";
+
+/**
+ * @title Push3Interpreter
+ * @dev Demonstrates a minimal Push3-like interpreter that uses
+ *      a token-based bytecode approach.
+ */
+contract Push3Interpreter {
+    // ReadUint`numBits` out of the code range.
+    error ReadUintOutOfRange(uint256 numBits);
+    // -----------------------------------------------------
+    // 0. CONSTANTS
+    // -----------------------------------------------------
+    uint8 internal constant OPCODE_INTEGER_OFFSET = uint8(OpCode.INTEGER_PLUS);
+    uint8 internal constant OPCODE_BOOL_OFFSET = uint8(OpCode.BOOL_DUP);
+    uint8 internal constant OPCODE_LAST = uint8(OpCode.BOOL_RAND);
+
+    // -----------------------------------------------------
+    // 1. ENUMS
+    // -----------------------------------------------------
+    enum CodeTag {
+        NO_TAG,       // 0
+        INSTRUCTION,  // 1
+        INT_LITERAL,  // 2
+        BOOL_LITERAL, // 3
+        SUBLIST       // 4
+    }
+
+    enum OpCode {
+        NOOP,            // 0
+        NOOP_1,          // 1 - empty for INSTRUCTION
+        NOOP_2,          // 2 - empty for INT_LITERAL
+        NOOP_3,          // 3 - empty for BOOL_LITERAL
+        NOOP_4,          // 4 - empty for SUBLIST
+        INTEGER_PLUS,    // 5 - OPCODE_INTEGER_OFFSET
+        INTEGER_MINUS,   // OPCODE_INTEGER_OFFSET + 1
+        INTEGER_MULT,    // OPCODE_INTEGER_OFFSET + 2
+        INTEGER_DUP,     // OPCODE_INTEGER_OFFSET + 3
+        INTEGER_POP,     // OPCODE_INTEGER_OFFSET + 4
+        BOOL_DUP,        // 10 - OPCODE_BOOL_OFFSET
+        BOOL_POP,        // OPCODE_BOOL_OFFSET + 1
+        BOOL_SWAP,       // OPCODE_BOOL_OFFSET + 2
+        BOOL_FLUSH,      // OPCODE_BOOL_OFFSET + 3
+        BOOL_STACKDEPTH, // OPCODE_BOOL_OFFSET + 4
+        BOOL_NOT,        // OPCODE_BOOL_OFFSET + 5
+        BOOL_AND,        // OPCODE_BOOL_OFFSET + 6
+        BOOL_OR,         // OPCODE_BOOL_OFFSET + 7
+        BOOL_EQ,         // OPCODE_BOOL_OFFSET + 8
+        BOOL_FROMFLOAT,  // OPCODE_BOOL_OFFSET + 9
+        BOOL_FROMINTEGER,// OPCODE_BOOL_OFFSET + 10
+        BOOL_ROT,        // OPCODE_BOOL_OFFSET + 11
+        BOOL_SHOVE,      // OPCODE_BOOL_OFFSET + 12
+        BOOL_YANK,       // OPCODE_BOOL_OFFSET + 13
+        BOOL_YANKDUP,    // OPCODE_BOOL_OFFSET + 14
+        BOOL_DEFINE,     // OPCODE_BOOL_OFFSET + 15
+        BOOL_RAND        // OPCODE_BOOL_OFFSET + 16
+    }
+
+    // -----------------------------------------------------
+    // 2. DESCRIPTOR BIT LAYOUT
+    // -----------------------------------------------------
+    // [255..248] : tag (8 bits)
+    // [247..216] : offset (32 bits)  (for SUBLIST)
+    // [215..184] : length (32 bits)  (for SUBLIST)
+    // [183..0]   : leftover bits     (opcode or literal data)
+
+    function getTag(uint256 desc) internal pure returns (CodeTag) {
+        return CodeTag(uint8(desc >> 248));
+    }
+
+    function getOffset(uint256 desc) internal pure returns (uint32) {
+        return uint32(desc >> 216);
+    }
+
+    function getLength(uint256 desc) internal pure returns (uint32) {
+        return uint32(desc >> 184);
+    }
+
+    function getLow184(uint256 desc) internal pure returns (uint256) {
+        return desc & ((1 << 184) - 1);
+    }
+
+    // Build a descriptor
+    function makeDescriptor(
+        CodeTag tag,
+        uint32 offset,
+        uint32 length,
+        uint256 low184
+    )
+        public
+        pure
+        returns (uint256)
+    {
+        require(low184 < (1 << 184), "low184 out of range");
+        return 
+            (uint256(uint8(tag)) << 248) |
+            (uint256(offset) << 216) |
+            (uint256(length) << 184) |
+            low184;
+    }
+
+    function makeInstruction(OpCode op) internal pure returns (uint256) {
+        return makeDescriptor(CodeTag.INSTRUCTION, 0, 0, uint256(uint8(op)));
+    }
+
+    function getOpCode(uint256 desc) internal pure returns (OpCode) {
+        return OpCode(uint8(desc & 0xFF));
+    }
+
+    function makeIntLiteral(int32 val) internal pure returns (uint256) {
+        // store 32-bit integer in leftover
+        uint256 masked = uint256(uint32(val));
+        return makeDescriptor(CodeTag.INT_LITERAL, 0, 0, masked);
+    }
+
+    function makeBoolLiteral(bool val) internal pure returns (uint256) {
+        uint256 masked;
+        if (val) masked = uint256(1);
+        return makeDescriptor(CodeTag.BOOL_LITERAL, 0, 0, masked);
+    }
+
+    function extractInt32(uint256 desc) internal pure returns (int32) {
+        // read the low 32 bits
+        return int32(uint32(getLow184(desc)));
+    }
+
+    function extractBool(uint256 desc) internal pure returns (bool) {
+        return desc & 1 == 1;
+    }
+
+    // -----------------------------------------------------
+    // 3. HELPER READS
+    // -----------------------------------------------------
+
+    /**
+     * @dev Read `x` bytes from `code` at `start` as uint.
+     */
+    function readUint(bytes calldata code, uint32 start, uint256 numBytes) internal pure returns (uint256 word) {
+        uint256 numBits = numBytes * 8;
+        if (start + numBytes > code.length) revert ReadUintOutOfRange(numBits);
+        assembly {
+            let buf := mload(0x40) // free memory
+            // copy exactly x bytes from code into buf
+            calldatacopy(buf, add(code.offset, start), numBytes)
+            word := mload(buf)
+        }
+        word >>= 256 - numBits;
+    }
+
+    /**
+     * @dev Read 4 bytes from `code` at `start` as uint32.
+     */
+    function readUint32(bytes calldata code, uint32 start) internal pure returns (uint32 val) {
+        val = uint32(readUint(code, start, 4));
+    }
+
+    /**
+     * @dev Read 2 bytes from `code` at `start` as uint16.
+     */
+    function readUint16(bytes calldata code, uint32 start) internal pure returns (uint16 val) {
+        val = uint16(readUint(code, start, 2));
+    }
+
+    /**
+     * @dev Read 1 byte from `code` at `start` as uint8.
+     */
+    function readUint8(bytes calldata code, uint32 start) internal pure returns (uint8 val) {
+        val = uint8(readUint(code, start, 1));
+    }
+
+    /**
+     * @dev Read 1 byte from `code` at `start` as bool.
+     */
+    function readBool(bytes calldata code, uint32 start) internal pure returns (bool val) {
+        val = readUint(code, start, 1) & 1 == 1;
+    }
+
+    // -----------------------------------------------------
+    // 4. SUBLIST PARSING
+    // -----------------------------------------------------
+    /**
+     * Token format is combination of ordered CodeTag and OpCode:
+     *   0x00 => NOOP/NO_TAG
+     *   0x01 => INSTRUCTION => read next 1 byte => OpCode
+     *   0x02 => INT_LITERAL => read next 4 bytes => int32
+     *   0x03 => BOOL_LITERAL => read next 1 byte => bool
+     *   0x04 => SUBLIST => read next 2 bytes => subLen => parse that
+     *   0x05 => INTEGER_PLUS
+     *   0x06 => INTEGER_MINUS
+     *   ... opcode list with type offsets
+     */
+    function parseSublist(bytes calldata code, uint32 off, uint32 len)
+        internal
+        pure
+        returns (uint256[] memory descs)
+    {
+        uint256[] memory temp = new uint256[](len);
+        uint256 count = 0;
+        uint32 endPos = off + len;
+        uint32 cur = off;
+
+        while (cur < endPos) {
+            if (cur >= code.length) {
+                break;
+            }
+
+            uint8 tokenType = uint8(code[cur]);
+            cur++;
+
+            if (tokenType == 0x00) {
+                // NOOP
+                temp[count] = makeInstruction(OpCode.NOOP);
+                count++;
+            }
+            else if (tokenType == 0x01) {
+                // INSTRUCTION
+                if (cur + 1 <= endPos && (cur + 1) <= code.length) {
+                    uint8 opcode = readUint8(code,cur);
+                    if (opcode < OPCODE_INTEGER_OFFSET || opcode > OPCODE_LAST) opcode = uint8(0); // NOOP
+                    temp[count] = makeInstruction(OpCode(opcode));
+                    count++;
+                } else {
+                    break;
+                }
+            }
+            else if (tokenType == 0x02) {
+                // INT_LITERAL => 4 bytes
+                if (cur + 4 <= endPos && (cur + 4) <= code.length) {
+                    uint32 raw = readUint32(code, cur);
+                    cur += 4;
+                    int32 val = int32(raw);
+                    temp[count] = makeIntLiteral(val);
+                    count++;
+                } else {
+                    break;
+                }
+            }
+            else if (tokenType == 0x03) {
+                // BOOL_LITERAL
+                if (cur + 1 <= endPos && (cur + 1) <= code.length) {
+                    bool val = readBool(code, cur);
+                    cur += 1;
+                    temp[count] = makeBoolLiteral(val);
+                    count++;
+                } else {
+                    break;
+                }
+            }
+            else if (tokenType == 0x04) {
+                // SUBLIST => read 2 bytes => length
+                if (cur + 2 <= endPos && (cur + 2) <= code.length) {
+                    uint16 subLen = readUint16(code, cur);
+                    cur += 2;
+                    if (cur + subLen <= endPos && (cur + subLen) <= code.length) {
+                        // create descriptor
+                        temp[count] = makeDescriptor(CodeTag.SUBLIST, cur, subLen, 0);
+                        count++;
+                        // skip over that subLen chunk
+                        cur += subLen;
+                    } else {
+                        break;
+                    }
+                } else {
+                    break;
+                }
+            }
+            else if (tokenType <= OPCODE_LAST) {
+                // OPCODE
+                temp[count] = makeInstruction(OpCode(tokenType));
+                count++;
+            }
+            else {
+                // unknown => NOOP
+                temp[count] = makeInstruction(OpCode.NOOP);
+                count++;
+            }
+        }
+
+        descs = new uint256[](count);
+        for (uint256 i = 0; i < count; i++) {
+            descs[i] = temp[i];
+        }
+    }
+
+    // -----------------------------------------------------
+    // 5. MAIN INTERPRETER
+    // -----------------------------------------------------
+    function runInterpreter(
+        bytes calldata code, // non-empty - genetic agent (DNA)
+        uint256[] calldata initCodeStack, // empty
+        uint256[] calldata initExecStack, // descriptors
+        int256[] calldata initIntStack, // 32bit word
+        bool[] calldata initBoolStack // bool array
+    )
+        external
+        view
+        returns (
+            uint256[] memory finalCodeStack,
+            uint256[] memory finalExecStack,
+            int256[]  memory finalIntStack,
+            bool[] memory finalBoolStack
+        )
+    {
+        // A) CODE STACK
+        uint256[] memory codeStack = new uint256[](initCodeStack.length + 256);
+        uint256 codeTop = initCodeStack.length;
+        for (uint256 i = 0; i < initCodeStack.length; i++) {
+            codeStack[i] = initCodeStack[i];
+        }
+
+        // B) EXEC STACK
+        uint256[] memory execStack = new uint256[](initExecStack.length + 256);
+        uint256 execTop = initExecStack.length;
+        for (uint256 e = 0; e < initExecStack.length; e++) {
+            execStack[e] = initExecStack[e];
+        }
+
+        // C) INT STACK
+        int256[] memory intStack = new int256[](initIntStack.length + 256);
+        uint256 intTop = initIntStack.length;
+        for (uint256 k = 0; k < initIntStack.length; k++) {
+            intStack[k] = initIntStack[k];
+        }
+
+        // D) BOOL STACK
+        bool[] memory boolStack = new bool[](initBoolStack.length + 256);
+        uint256 boolTop = initBoolStack.length;
+        for (uint256 k = 0; k < initBoolStack.length; k++) {
+            boolStack[k] = initBoolStack[k];
+        }
+
+        // D) MAIN LOOP
+        while (execTop > 0) {
+            uint256 topDesc = execStack[execTop - 1];
+            execTop--;
+
+            CodeTag tag = getTag(topDesc);
+
+            if (tag == CodeTag.INSTRUCTION) {
+                OpCode op = getOpCode(topDesc);
+                if (uint8(op) < OPCODE_INTEGER_OFFSET) {
+                    // NOOP, do nothing
+                }
+                else if (uint8(op) < OPCODE_BOOL_OFFSET) {
+                    // INTEGER OPCODES
+                    if (op == OpCode.INTEGER_PLUS) {
+                        // pop top 2 => sum
+                        if (intTop >= 2) {
+                            int256 a = intStack[intTop - 1];
+                            int256 b = intStack[intTop - 2];
+                            intTop -= 2;
+                            intStack[intTop] = b + a;
+                            intTop++;
+                        }
+                    }
+                    else if (op == OpCode.INTEGER_MINUS) {
+                        // pop top 2 => minus
+                        if (intTop >= 2) {
+                            int256 a = intStack[intTop - 1];
+                            int256 b = intStack[intTop - 2];
+                            intTop -= 2;
+                            intStack[intTop] = b - a;
+                            intTop++;
+                        }
+                    }
+                    else if (op == OpCode.INTEGER_MULT) {
+                        // pop top 2 => minus
+                        if (intTop >= 2) {
+                            int256 a = intStack[intTop - 1];
+                            int256 b = intStack[intTop - 2];
+                            intTop -= 2;
+                            intStack[intTop] = b * a;
+                            intTop++;
+                        }
+                    }
+                    else if (op == OpCode.INTEGER_DUP) {
+                        if (intTop >= 1) {
+                            int256 a = intStack[intTop - 1];
+                            intStack[intTop] = a;
+                            intTop++;
+                        }
+                    }
+                    else if (op == OpCode.INTEGER_POP) {
+                        if (intTop >= 1) {
+                            intTop -= 1;
+                        }
+                    }
+                }
+                else if (uint8(op) <= OPCODE_LAST) {
+                    // BOOL OPCODES
+                    if (op == OpCode.BOOL_DUP) {
+                        // dup top
+                        if (boolTop > 0) {
+                            boolStack[boolTop] = boolStack[boolTop - 1];
+                            boolTop++;
+                        }
+                    }
+                    else if (op == OpCode.BOOL_POP) {
+                        // pop top
+                        if (boolTop > 0) {
+                            boolTop--;
+                        }
+                    }
+                    else if (op == OpCode.BOOL_SWAP) {
+                        // swap top 2
+                        if (boolTop > 1) {
+                            (boolStack[boolTop - 1], boolStack[boolTop - 2]) = (boolStack[boolTop - 2], boolStack[boolTop - 1]);
+                        }
+                    }
+                    else if (op == OpCode.BOOL_FLUSH) {
+                        // empty stack
+                        boolTop = 0;
+                    }
+                    else if (op == OpCode.BOOL_STACKDEPTH) {
+                        // push bool depth onto int stack
+                        intStack[intTop] = int256(boolTop);
+                        intTop++;
+                    }
+                    else if (op == OpCode.BOOL_NOT) {
+                        // push NOT of top
+                        if (boolTop > 0) {
+                            boolStack[boolTop - 1] = !boolStack[boolTop - 1];
+                        }
+                    }
+                    else if (op == OpCode.BOOL_AND) {
+                        // push AND of top 2
+                        if (boolTop > 1) {
+                            boolStack[boolTop - 2] = boolStack[boolTop - 1] && boolStack[boolTop - 2];
+                            boolTop--;
+                        }
+                    }
+                    else if (op == OpCode.BOOL_OR) {
+                        // push OR of top 2
+                        if (boolTop > 1) {
+                            boolStack[boolTop - 2] = boolStack[boolTop - 1] || boolStack[boolTop - 2];
+                            boolTop--;
+                        }
+                    }
+                    else if (op == OpCode.BOOL_EQ) {
+                        // push True if top 2 equal
+                        if (boolTop > 1) {
+                            boolStack[boolTop - 2] = boolStack[boolTop - 1] == boolStack[boolTop - 2];
+                            boolTop--;
+                        }
+                    }
+                    else if (op == OpCode.BOOL_FROMFLOAT) {
+                        // FLOAT is not implemented yet
+                    }
+                    else if (op == OpCode.BOOL_FROMINTEGER) {
+                        // push True if top int not eq 0
+                        if (intTop > 0) {
+                            boolStack[boolTop] = intStack[intTop - 1] != int256(0);
+                            boolTop++;
+                            intTop--;
+                        }
+                    }
+                    else if (op == OpCode.BOOL_ROT) {
+                        // rotate [top - 3, top - 2, top - 1] into -> [top - 2, top - 1, top - 3]
+                        if (boolTop > 2) {
+                            (boolStack[boolTop - 1], boolStack[boolTop - 2], boolStack[boolTop - 3]) = (boolStack[boolTop - 3], boolStack[boolTop - 1], boolStack[boolTop - 2]);
+                        }
+                    }
+                    else if (op == OpCode.BOOL_SHOVE) {
+                        // Task: Inserts the top BOOLEAN "deep" in the stack, at the position indexed by the top INTEGER.
+                        // Questions: what does "inserts" mean? does it mean that we pop top value and then insert it
+                        // at index? does it mean that array size does not change?
+                        // what happens with the previous element at this index?
+                        // is it correct that this element stays in array?
+                        // should it be moved in top or bottom direction from index (index + || -)?
+                        // does it mean that we need to reindex the whole stack?
+                        // is the simplest solution to reindex to iterate through the whole stack?
+                        // do we really want have such loops?
+                    }
+                    else if (op == OpCode.BOOL_YANK) {
+                        // Task: Removes an indexed item from "deep" in the stack and pushes it on top of the stack. The index is taken from the INTEGER stack.
+                        // Same question as for SHOVE is valid here.
+                        // For example, in our implementation currently we are not really poping
+                        // element from an array in POP, we only adjusting the counter.
+                        // For removing index we would need to loop over the array to reindex.
+                    }
+                    else if (op == OpCode.BOOL_YANKDUP) {
+                        // Task: Pushes a copy of an indexed item "deep" in the stack onto the top of the stack, without removing the deep item. The index is taken from the INTEGER stack.
+                        uint256 index = uint256(intStack[intTop - 1]);
+                        if (boolTop > 2) {
+                            // pop int stack
+                            intTop--;
+                            // index in range (reverse array indexes)
+                            index++; // adjust as boolTop is length, highest index is boolTop - 1
+                            if (index > boolTop) {
+                                index = 0;
+                            } else {
+                                index = boolTop - index;
+                            }
+                            // push value on bool stack
+                            boolStack[boolTop] = boolStack[index];
+                            boolTop++;
+                        }
+                    }
+                    else if (op == OpCode.BOOL_DEFINE) {
+                        // NAME is not implemented yet
+                    }
+                    else if (op == OpCode.BOOL_RAND) {
+                        // Pushes a random BOOLEAN.
+                        uint256 randomNum = uint256(keccak256(abi.encodePacked(block.prevrandao, block.timestamp, msg.sender)));
+                        boolStack[boolTop] = extractBool(randomNum);
+                        boolTop++;
+                    }
+                }
+            }
+            else if (tag == CodeTag.INT_LITERAL) {
+                int32 val = extractInt32(topDesc);
+                intStack[intTop] = int256(val);
+                intTop++;
+            }
+            else if (tag == CodeTag.BOOL_LITERAL) {
+                bool val = extractBool(topDesc);
+                boolStack[boolTop] = val;
+                boolTop++;
+            }
+            else if (tag == CodeTag.SUBLIST) {
+                // parse sublist => push in reverse
+                uint32 off = getOffset(topDesc);
+                uint32 len = getLength(topDesc);
+
+                if (off + len <= code.length) {
+                    uint256[] memory parsed = parseSublist(code, off, len);
+                    for (uint256 p = 0; p < parsed.length; p++) {       // index 0     1     2
+                        execStack[execTop] = parsed[parsed.length - 1 - p]; // [0x01, 0x20, 0x0a]
+                        execTop++;
+                    }
+                }
+            }
+            else {
+                // NO_TAG => do nothing
+            }
+        }
+
+        // E) RETURN
+        finalCodeStack = new uint256[](codeTop);
+        for (uint256 i = 0; i < codeTop; i++) {
+            finalCodeStack[i] = codeStack[i];
+        }
+
+        finalExecStack = new uint256[](execTop);
+        for (uint256 i = 0; i < execTop; i++) {
+            finalExecStack[i] = execStack[i];
+        }
+
+        finalIntStack = new int256[](intTop);
+        for (uint256 i = 0; i < intTop; i++) {
+            finalIntStack[i] = intStack[i];
+        }
+
+        finalBoolStack = new bool[](boolTop);
+        for (uint256 i = 0; i < boolTop; i++) {
+            finalBoolStack[i] = boolStack[i];
+        }
+    }
+}

onchain/test/Push3IntAdapter.t.sol

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity ^0.8.20;
+
+import {Test} from "forge-std/Test.sol";
+import {Push3Interpreter} from "../src/Push3Interpreter.sol";
+import {Push3IntAdapter} from "../src/Push3IntAdapter.sol";
+
+/**
+ * @title Push3IntAdapterTest
+ * @dev Foundry test for the Push3IntAdapter contract, 
+ *      which composes with the Push3Interpreter.
+ */
+contract Push3IntAdapterTest is Test {
+    Push3Interpreter public interpreter;
+    Push3IntAdapter public adapter;
+
+    function setUp() public {
+        // 1) Deploy the interpreter
+        interpreter = new Push3Interpreter();
+
+        // 2) Deploy the adapter, referencing the interpreter address
+        adapter = new Push3IntAdapter(address(interpreter));
+    }
+
+    /**
+     * @notice Test run1In1Out with a minimal code array.
+     * For example, we might do a program that just leaves its input unchanged
+     * (like a NOOP).
+     */
+    function test_run1In1Out_noop() public view {
+        bytes memory code = hex"04000100";
+
+        int256 inputVal = 123;
+        int256 result = adapter.run1In1Out(code, inputVal);
+
+        // We expect the code does nothing => output == input
+        assertEq(result, inputVal, "Expected same value out");
+    }
+
+    /**
+     * @notice Test run2In1Out. We'll push 5, 7, do an op that leaves 12.
+     */
+    function test_run2In1Out_plus() public view {
+        bytes memory code = hex"04000105";
+
+        int256 in1 = 5;
+        int256 in2 = 7;
+        int256 result = adapter.run2In1Out(code, in1, in2);
+
+        assertEq(result, 12, "Expected 5 + 7 = 12");
+    }
+
+    /**
+     * @notice Test run1In2Out. Push a constant to a stack with 1.
+     * For now, we do a placeholder code.
+     */
+    function test_run1In2Out() public view {
+        bytes memory code = hex"0400050200000003";
+
+        int256 inVal = 42;
+        (int256 top, int256 secondTop) = adapter.run1In2Out(code, inVal);
+
+        assertEq(top, 3, "top stack val mismatch");
+        assertEq(secondTop, 42, "second top stack val mismatch");
+    }
+
+    /**
+     * @notice Test run0InNOut.
+     * We'll feed a code that pushes some constants, and see the final stack.
+     */
+    function test_run0InNOut() public view {
+
+        bytes memory code = hex"04000A02000000030200000005";
+
+        int256[] memory stackResult = adapter.run0InNOut(code);
+
+        assertEq(stackResult.length, 2, "Expected 2 final stack items");
+        assertEq(stackResult[0], 3, "Item 0 mismatch");
+        assertEq(stackResult[1], 5, "Item 1 mismatch");
+    }
+}

onchain/test/Push3Interpreter.t.sol

@@ -0,0 +1,907 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity ^0.8.20;
+
+import {Test} from "forge-std/Test.sol";
+import "forge-std/console.sol";
+import {Push3Interpreter} from "../src/Push3Interpreter.sol";
+
+/**
+ * @title Push3InterpreterTest
+ * @dev Foundry test contract for the updated Push3Interpreter
+ */
+contract Push3InterpreterTest is Test {
+    Push3Interpreter public interpreter;
+
+    function setUp() public {
+        interpreter = new Push3Interpreter();
+    }
+
+    /**
+     * @notice Test a small program that:
+     *   1) Pushes literal 10 (int32)
+     *   2) Pushes literal 32 (int32)
+     *   3) Calls INTEGER_PLUS
+     *
+     *  We'll store everything in a single SUBLIST:
+     *  0x04 => SUBLIST
+     *  0x00 0x0B => subLen=11
+     *  Then the next 11 bytes are:
+     *    0x02 + (00 00 00 0A) => INT_LITERAL(10)
+     *    0x02 + (00 00 00 20) => INT_LITERAL(32)
+     *    0x05 => INTEGER_PLUS
+     *
+     *  So total = 1 + 2 + (1+4 + 1+4 + 1) = 14 bytes
+     *  => 0x04 00 0B 02 00 00 00 0A 02 00 00 00 20 05
+     */
+    function test_LiteralsAndPlus() public view {
+        // The final code array (14 bytes):
+        //  [0] = 0x04
+        //  [1..2] = 0x000B
+        //  [3] =  0x02
+        //  [4..7] = 0x0000000A => 10
+        //  [8] =  0x02
+        //  [9..12] = 0x00000020 => 32
+        //  [13] = 0x05 => plus
+
+        bytes memory code = hex"04000B020000000A020000002005";
+
+        // Or fully concatenated:
+        // 0x04 00 0B 02 00 00 00 0A 02 00 00 00 20 05
+
+        // We'll parse offset=0, length=14
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,   // offset
+            14,  // length
+            0
+        );
+
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        // Run it
+        (
+            ,
+            ,
+            int256[] memory finalIntStack
+            ,
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        // Should produce finalIntStack = [42]
+        assertEq(finalIntStack.length, 1, "finalIntStack should have length 1");
+        assertEq(finalIntStack[0], 42, "Should be 10+32=42");
+    }
+
+    /**
+     * @notice Test pushing literal 10, literal 3, then INTEGER_MINUS => (10 - 3) = 7
+     *
+     * The plan:
+     *  0x04 => SUBLIST token
+     *  0x00 0x0B => subLen=11
+     *
+     *  Then 11 bytes:
+     *    0x02 + (00 00 00 0A) => INT_LITERAL(10)
+     *    0x02 + (00 00 00 03) => INT_LITERAL(3)
+     *    0x06 => INTEGER_MINUS (assuming 0x06 is assigned to minus)
+     */
+    function test_Minus() public view {
+        // We'll produce 14 total bytes, same structure as the plus example
+        // Format: [0x04, 0x000B, 0x02(10), 0x03(3), 0x06 => minus]
+
+        bytes memory code = hex"04000B020000000A020000000306";
+        // Breaking it down:
+        // 0x04          => SUBLIST
+        // 0x00 0x0B     => length=11
+        // 0x02 0000000A => INT_LITERAL(10)
+        // 0x02 00000003 => INT_LITERAL(3)
+        // 0x06          => INTEGER_MINUS
+
+        // We'll parse offset=0, length=14
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,   // offset
+            14,  // length
+            0
+        );
+
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        // Run
+        (
+            ,
+            ,
+            int256[] memory finalIntStack
+            ,
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        // Check final result => should be [7]
+        assertEq(finalIntStack.length, 1, "finalIntStack should have length 1");
+        assertEq(finalIntStack[0], 7, "Should be 10 - 3 = 7");
+    }
+
+    /**
+     * @notice Test pushing literal 10, literal 3, then INTEGER_MULT => (10 * 3) = 30
+     *
+     * The plan:
+     *  0x04 => SUBLIST token
+     *  0x00 0x0B => subLen=11
+     *
+     *  Then 11 bytes:
+     *    0x02 + (00 00 00 0A) => INT_LITERAL(10)
+     *    0x02 + (00 00 00 03) => INT_LITERAL(3)
+     *    0x07 => INTEGER_MULT
+     */
+    function test_Mult() public view {
+        // We'll produce 14 total bytes, same structure as the plus example
+        // Format: [0x04, 0x000B, 0x02(10), 0x02(3), 0x07 => mul]
+
+        bytes memory code = hex"04000B020000000A020000000307";
+        // Breaking it down:
+        // 0x04          => SUBLIST
+        // 0x00 0x0B     => length=11
+        // 0x02 0000000A => INT_LITERAL(10)
+        // 0x02 00000003 => INT_LITERAL(3)
+        // 0x07          => INTEGER_MUL
+
+        // We'll parse offset=0, length=14
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,   // offset
+            14,  // length
+            0
+        );
+
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        // Run
+        (
+            ,
+            ,
+            int256[] memory finalIntStack
+            ,
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        // Check final result => should be [30]
+        assertEq(finalIntStack.length, 1, "finalIntStack should have length 1");
+        assertEq(finalIntStack[0], 30, "Should be 10 * 3 = 30");
+    }
+
+    function test_Dup() public view {
+
+        bytes memory code = hex"040009020000000A0803010A";
+
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,
+            12,
+            0
+        );
+
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        // Run
+        (
+            ,
+            ,
+            int256[] memory finalIntStack,
+            bool[] memory finalBoolStack
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        assertEq(finalIntStack.length, 2, "finalIntStack should have length 1");
+        assertEq(finalIntStack[0], finalIntStack[1], "The top 2 values on the int stack should be equal.");
+        assertEq(finalBoolStack.length, 2, "finalBoolStack should have length 2");
+        assertEq(finalBoolStack[0], finalBoolStack[1], "The top 2 values on the bool stack should be equal.");
+    }
+
+    function test_Pop() public view {
+
+        bytes memory code = hex"040009020000000A0903010B";
+
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,
+            12,
+            0
+        );
+
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        // Run
+        (
+            ,
+            ,
+            int256[] memory finalIntStack,
+            bool[] memory finalBoolStack
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        assertEq(finalIntStack.length, 0, "finalIntStack should be empty");
+        assertEq(finalBoolStack.length, 0, "finalBoolStack should be empty");
+    }
+
+    /**
+     * @notice Test with an unknown token (0xF0).
+     * We expect the parser to treat it as "unknown => NOOP"
+     * and produce a NOOP instruction descriptor.
+     * We'll confirm finalIntStack remains empty (or unchanged).
+     */
+    function test_UnknownToken() public view {
+        // We'll create a 5-byte code:
+        //  0x04 => SUBLIST
+        //  0x00 0x01 => length=1
+        //  0xF0 => unknown token
+        bytes memory code = hex"040001F0";
+
+        // We'll parse offset=0, length=4
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,   // offset
+            4,   // length
+            0
+        );
+
+        // init stacks
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        (
+            ,
+            ,
+            int256[] memory finalIntStack
+            ,
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        // finalIntStack should remain empty => no literal was pushed
+        assertEq(finalIntStack.length, 0, "Expected finalIntStack to remain empty with unknown token => NOOP");
+    }
+
+    /**
+     * @notice Test a partial literal: we claim to have 4 bytes, but the code array ends early.
+     * This should trigger the `else { break; }` branch in parseSublist
+     * when trying to read 4 bytes for the INT_LITERAL.
+     */
+    function test_OutOfRangeLiteral() public view {
+        //  0x04 => SUBLIST
+        //  0x00 0x04 => length=4
+        //  0x02 => INT_LITERAL token
+        // Then we have only 1 byte left instead of 4 => insufficient
+        //
+        // total = 1 + 2 + 1 + 1 = 5 bytes
+        // The parser tries to read 4 bytes after seeing 0x04, fails, hits break.
+        bytes memory code = hex"04000402FF";
+
+        // parse offset=0, length=5
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,
+            5,
+            0
+        );
+
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        (
+            ,
+            ,
+            int256[] memory finalIntStack
+            ,
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        // Because the parse breaks early, we expect finalIntStack is empty or unchanged
+        assertEq(finalIntStack.length, 0, "Expected parse to break on out-of-range literal => no ints pushed");
+    }
+
+    /**
+     * @notice Test "not enough int args" scenario:
+     * We'll push only 1 literal, then do INTEGER_PLUS which needs 2 integers on the stack.
+     * In the main loop, it sees intTop < 2 => it does nothing.
+     */
+    function test_NotEnoughIntArgs() public view {
+        bytes memory code = hex"040006020000000307";
+        // Breaking it down:
+        // 0x04          => SUBLIST
+        // 0x00 0x06     => length=6
+        // 0x02 00000003 => INT_LITERAL(3)
+        // 0x07          => INTEGER_MUL
+
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,
+            9,
+            0
+        );
+
+        // set up stacks
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        (
+            ,
+            ,
+            int256[] memory finalIntStack
+            ,
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        // We expect finalIntStack => [5],
+        // because the PLUS instruction sees only 1 int => does nothing => 5 remains
+        assertEq(finalIntStack.length, 1, "Should have 1 int left");
+        assertEq(finalIntStack[0], 3, "Expected stack top=3 after insufficient-args plus");
+    }
+
+    /**
+     * @notice Test sublist length overflow:
+     * subLen claims bigger than the code array. Should trigger else { break; }
+     * in the sublist parsing for that sublist.
+     */
+    function test_SublistLengthOverflow() public view {
+
+        bytes memory code = hex"050010FFFFFF";
+
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,
+            6,
+            0
+        );
+
+        // init
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        (
+            ,
+            ,
+            int256[] memory finalIntStack
+            ,
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        // Expect no items pushed => finalIntStack empty
+        assertEq(finalIntStack.length, 0, "Expected empty stack if sublist length is out of range => parse break");
+    }
+
+    // BOOL STACK
+
+    /**
+     * @notice Test pushing literal True, literal False, then BOOL_SWAP => [False, True]
+     *
+     * The plan:
+     *  0x04 => SUBLIST token
+     *  0x00 0x05 => subLen=5
+     *
+     *  Then 5 bytes:
+     *    0x03 + (01) => BOOL_LITERAL(True)
+     *    0x03 + (00) => BOOL_LITERAL(False)
+     *    0x0C => BOOL_SWAP
+     */
+    function test_BoolSwap() public view {
+        // We'll produce 8 total bytes, same structure
+        // Format: [0x04, 0x0005, 0x03(01), 0x03(00), 0x0C => bool_swap]
+
+        bytes memory code = hex"040005030103000C";
+        // Breaking it down:
+        // 0x04          => SUBLIST
+        // 0x00 0x05     => length=5
+        // 0x03 0x01     => BOOL_LITERAL(True)
+        // 0x03 0x00     => BOOL_LITERAL(False)
+        // 0x0C          => BOOL_SWAP
+
+        // We'll parse offset=0, length=8
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,   // offset
+            8,  // length
+            0
+        );
+
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        // Run
+        (
+            ,
+            ,
+            ,
+            bool[] memory finalBoolStack
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        // Check final result => should be [True, False] swapped into [False, True]
+        assertEq(finalBoolStack.length, 2, "finalBoolStack should have length 2");
+        assertEq(finalBoolStack[0], false, "Should be False");
+        assertEq(finalBoolStack[1], true, "Should be True");
+    }
+
+    /**
+     * @notice Test pushing literal True, literal False, then BOOL_FLUSH => []
+     *         Result should be empty stack.
+     */
+    function test_BoolFlush() public view {
+        // We'll produce 8 total bytes, same structure
+        // Format: [0x04, 0x0005, 0x03(01), 0x03(00), 0x0D => bool_flush]
+
+        bytes memory code = hex"040005030103000D";
+        // Breaking it down:
+        // 0x04          => SUBLIST
+        // 0x00 0x05     => length=5
+        // 0x03 0x01     => BOOL_LITERAL(True)
+        // 0x03 0x00     => BOOL_LITERAL(False)
+        // 0x0D          => BOOL_FLUSH
+
+        // We'll parse offset=0, length=8
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,   // offset
+            8,  // length
+            0
+        );
+
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        // Run
+        (
+            ,
+            ,
+            ,
+            bool[] memory finalBoolStack
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        // Check final result => should be empty bool stack
+        assertEq(finalBoolStack.length, 0, "finalBoolStack should have length 0");
+    }
+
+    /**
+     * @notice Test pushing literal True, literal False, then BOOL_STACKDEPTH => intStack[2]
+     *         Result should be number of pushed literals as intStack top.
+     */
+    function test_BoolStackDepth() public view {
+        // We'll produce 8 total bytes, same structure
+        // Format: [0x04, 0x0005, 0x03(01), 0x03(00), 0x0E => bool_stackdepth]
+
+        bytes memory code = hex"040005030103000E";
+        // Breaking it down:
+        // 0x04          => SUBLIST
+        // 0x00 0x05     => length=5
+        // 0x03 0x01     => BOOL_LITERAL(True)
+        // 0x03 0x00     => BOOL_LITERAL(False)
+        // 0x0E          => BOOL_STACKDEPTH
+
+        // We'll parse offset=0, length=8
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,   // offset
+            8,  // length
+            0
+        );
+
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        // Run
+        (
+            ,
+            ,
+            int256[] memory finalIntStack,
+            bool[] memory finalBoolStack
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        // Check final result => should be empty bool stack
+        assertEq(finalIntStack.length, 1, "finalIntStack should have length 1");
+        assertEq(finalBoolStack.length, 2, "finalBoolStack should have length 2");
+        assertEq(finalIntStack[0], 2, "IntStack top value should be 2, as we pushed 2 literals onto bool stack");
+    }
+
+    /**
+     * @notice Test pushing literal True, then BOOL_NOT => boolStack[False]
+     *         Result should be False on top of bool stack.
+     */
+    function test_BoolNot() public view {
+        // We'll produce 6 total bytes, same structure
+        // Format: [0x04, 0x0003, 0x03(01), 0x0F => bool_not]
+
+        bytes memory code = hex"04000303010F";
+        // Breaking it down:
+        // 0x04          => SUBLIST
+        // 0x00 0x03     => length=3
+        // 0x03 0x01     => BOOL_LITERAL(True)
+        // 0x0F          => BOOL_NOT
+
+        // We'll parse offset=0, length=6
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,   // offset
+            6,  // length
+            0
+        );
+
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        // Run
+        (
+            ,
+            ,
+            ,
+            bool[] memory finalBoolStack
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        // Check final result => should be False on top of bool stack
+        assertEq(finalBoolStack.length, 1, "finalBoolStack should have length 1");
+        assertEq(finalBoolStack[0], false, "Expected to be False after logical NOT on True");
+    }
+
+    /**
+     * @notice Test pushing literal True, literal True, then BOOL_AND => boolStack[True]
+     *         Result should be True on top of bool stack.
+     */
+    function test_BoolAnd() public view {
+        // We'll produce 8 total bytes, same structure
+        // Format: [0x04, 0x0005, 0x03(01), 0x03(01) 0x10 => bool_and]
+
+        bytes memory code = hex"0400050301030110";
+        // Breaking it down:
+        // 0x04          => SUBLIST
+        // 0x00 0x05     => length=5
+        // 0x03 0x01     => BOOL_LITERAL(True)
+        // 0x03 0x01     => BOOL_LITERAL(True)
+        // 0x10          => BOOL_AND
+
+        // We'll parse offset=0, length=8
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,   // offset
+            8,  // length
+            0
+        );
+
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        // Run
+        (
+            ,
+            ,
+            ,
+            bool[] memory finalBoolStack
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        // Check final result => should be True on top of bool stack
+        assertEq(finalBoolStack.length, 1, "finalBoolStack should have length 1");
+        assertEq(finalBoolStack[0], true, "Expected to be True after logical AND on True and True");
+    }
+
+    /**
+     * @notice Test pushing literal True, literal False, then BOOL_OR => boolStack[True]
+     *         Result should be True on top of bool stack.
+     */
+    function test_BoolOr() public view {
+        // We'll produce 8 total bytes, same structure
+        // Format: [0x04, 0x0005, 0x03(01), 0x03(00) 0x11 => bool_or]
+
+        bytes memory code = hex"0400050301030011";
+        // Breaking it down:
+        // 0x04          => SUBLIST
+        // 0x00 0x05     => length=5
+        // 0x03 0x01     => BOOL_LITERAL(True)
+        // 0x03 0x00     => BOOL_LITERAL(False)
+        // 0x11          => BOOL_OR
+
+        // We'll parse offset=0, length=8
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,   // offset
+            8,  // length
+            0
+        );
+
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        // Run
+        (
+            ,
+            ,
+            ,
+            bool[] memory finalBoolStack
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        // Check final result => should be True on top of bool stack
+        assertEq(finalBoolStack.length, 1, "finalBoolStack should have length 1");
+        assertEq(finalBoolStack[0], true, "Expected to be True after logical OR on True and False");
+    }
+
+    /**
+     * @notice Test pushing literal True, literal False, then BOOL_EQ => boolStack[False]
+     *         Result should be False on top of bool stack.
+     */
+    function test_BoolEq() public view {
+        // We'll produce 8 total bytes, same structure
+        // Format: [0x04, 0x0005, 0x03(01), 0x03(00) 0x12 => bool_eq]
+
+        bytes memory code = hex"0400050301030012";
+        // Breaking it down:
+        // 0x04          => SUBLIST
+        // 0x00 0x05     => length=5
+        // 0x03 0x01     => BOOL_LITERAL(True)
+        // 0x03 0x00     => BOOL_LITERAL(False)
+        // 0x12          => BOOL_EQ
+
+        // We'll parse offset=0, length=8
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,   // offset
+            8,  // length
+            0
+        );
+
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        // Run
+        (
+            ,
+            ,
+            ,
+            bool[] memory finalBoolStack
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        // Check final result => should be False on top of bool stack
+        assertEq(finalBoolStack.length, 1, "finalBoolStack should have length 1");
+        assertEq(finalBoolStack[0], false, "Expected to be False as True is not equal False");
+    }
+
+    /**
+     * @notice Test pushing literal 0x2145, then BOOL_FROMINTEGER => boolStack[True]
+     *         Result should be True on top of bool stack.
+     */
+    function test_BoolFromInteger() public view {
+        // We'll produce 9 total bytes, same structure
+        // Format: [0x04, 0x0004, 0x02(0x00002145), 0x14 => bool_frominteger]
+
+        bytes memory code = hex"040006020000214514";
+        // Breaking it down:
+        // 0x04            => SUBLIST
+        // 0x00 0x04       => length=6
+        // 0x02 0x00002145 => INT_LITERAL(0x2145)
+        // 0x14            => BOOL_FROMINTEGER
+
+        // We'll parse offset=0, length=9
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,   // offset
+            9,  // length
+            0
+        );
+
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        // Run
+        (
+            ,
+            ,
+            int256[] memory finalIntStack,
+            bool[] memory finalBoolStack
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        // Check final result => should be True on bool stack
+        assertEq(finalIntStack.length, 0, "finalIntStack should have length 0");
+        assertEq(finalBoolStack.length, 1, "finalBoolStack should have length 1");
+        assertEq(finalBoolStack[0], true, "boolStack top value should be True, as we pushed non-zero literal onto int stack");
+    }
+
+    /**
+     * @notice Test pushing literal True, literal False, literal True, then BOOL_ROT => boolStack[False, True, True]
+     *         Result should be rotated bool stack from [True, False, True] into [False, True, True].
+     */
+    function test_BoolRot() public view {
+        // We'll produce 10 total bytes, same structure
+        // Format: [0x04, 0x0007, 0x03(01), 0x03(00), 0x03(01), 0x15 => bool_rot]
+
+        bytes memory code = hex"04000703010300030115";
+        // Breaking it down:
+        // 0x04          => SUBLIST
+        // 0x00 0x07     => length=7
+        // 0x03 0x01     => BOOL_LITERAL(True)
+        // 0x03 0x00     => BOOL_LITERAL(False)
+        // 0x03 0x01     => BOOL_LITERAL(True)
+        // 0x15          => BOOL_ROT
+
+        // We'll parse offset=0, length=10
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,   // offset
+            10,  // length
+            0
+        );
+
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        // Run
+        (
+            ,
+            ,
+            ,
+            bool[] memory finalBoolStack
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        // Check final result => should be [False, True, True] bool stack
+        assertEq(finalBoolStack.length, 3, "finalBoolStack should have length 3");
+        assertEq(finalBoolStack[0], false, "Expected to be False as value from middle position moved to bottom of the stack");
+        assertEq(finalBoolStack[1], true, "Expected to be True as value from top position moved to middle of the stack");
+        assertEq(finalBoolStack[2], true, "Expected to be True as value from bottom position moved to top of the stack");
+    }
+
+    /**
+     * @notice Test pushing literal 0x02, literal True, literal False, literal True, then BOOL_YANKDUP => boolStack[True, False, True, True]
+     *         Result should be copied True on top of bool stack [True, False, True, True]
+     */
+    function test_BoolYankDup() public view {
+        // We'll produce 15 total bytes, same structure
+        // Format: [0x04, 0x000C, 0x02(00 00 00 02) 0x03(01), 0x03(00), 0x03(01), 0x18 => bool_yankdup]
+
+        bytes memory code = hex"04000C020000000203010300030118";
+        // Breaking it down:
+        // 0x04          => SUBLIST
+        // 0x00 0x0C     => length=12
+        // 0x02 0x00000002 => INT_LITERAL(0x02)
+        // 0x03 0x01     => BOOL_LITERAL(True)
+        // 0x03 0x00     => BOOL_LITERAL(False)
+        // 0x03 0x01     => BOOL_LITERAL(True)
+        // 0x18          => BOOL_YANKDUP
+
+        // We'll parse offset=0, length=15
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,   // offset
+            15,  // length
+            0
+        );
+
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        // Run
+        (
+            ,
+            ,
+            ,
+            bool[] memory finalBoolStack
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        // Check final result => should be [True, False, True, True] bool stack
+        assertEq(finalBoolStack.length, 4, "finalBoolStack should have length 4");
+        assertEq(finalBoolStack[0], true, "Expected to be True as first value from bool literal");
+        assertEq(finalBoolStack[1], false, "Expected to be False as second value from bool literal");
+        assertEq(finalBoolStack[2], true, "Expected to be True as third value from bool literal");
+        assertEq(finalBoolStack[3], true, "Expected to be True as copied value at index 2, which is index 0 for an array");
+    }
+
+    /**
+     * @notice Test pushing BOOL_RAND => boolStack[True] or boolStack[False]
+     *         Result should be either False or True on top of bool stack.
+     */
+    function test_BoolRand() public {
+        // We'll produce 4 total bytes, same structure
+        // Format: [0x04, 0x0001, 0x1A => bool_rand]
+
+        bytes memory code = hex"0400011A";
+        // Breaking it down:
+        // 0x04          => SUBLIST
+        // 0x00 0x01     => length=1
+        // 0x1A          => BOOL_RAND
+
+        // We'll parse offset=0, length=4
+        uint256 sublistDesc = interpreter.makeDescriptor(
+            Push3Interpreter.CodeTag.SUBLIST,
+            0,   // offset
+            4,  // length
+            0
+        );
+
+        uint256[] memory initCodeStack = new uint256[](0);
+        uint256[] memory initExecStack = new uint256[](1);
+        initExecStack[0] = sublistDesc;
+
+        int256[] memory initIntStack = new int256[](0);
+        bool[] memory initBoolStack = new bool[](0);
+
+        // Run
+        (
+            ,
+            ,
+            ,
+            bool[] memory finalBoolStack
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+
+        // Check final result => should be random bool on top of bool stack
+        assertEq(finalBoolStack.length, 1, "finalBoolStack should have length 1");
+        assertEq(finalBoolStack[0], false, "Expected to be False for default prevrandao, timestamp and msg.sender");
+        // move to another timestamp to get different random result
+        vm.warp(1736055577);
+        (
+            ,
+            ,
+            ,
+            finalBoolStack
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
+        assertEq(finalBoolStack.length, 1, "finalBoolStack should have length 1");
+        assertEq(finalBoolStack[0], true, "Expected to be True for configured timestamp and default prevrandao, msg.sender");
+    }
+}

src/Push3Interpreter.sol

@@ -1,303 +0,0 @@
-// SPDX-License-Identifier: MIT
-pragma solidity ^0.8.20;
-
-import "forge-std/console.sol";
-
-/**
- * @title Push3Interpreter
- * @dev Demonstrates a minimal Push3-like interpreter that uses
- *      a token-based bytecode approach. We fix the assembly
- *      endianness issues by copying exact bytes for 2- and 4-byte reads.
- */
-contract Push3Interpreter {
-    // -----------------------------------------------------
-    // 1. ENUMS
-    // -----------------------------------------------------
-    enum CodeTag {
-        NO_TAG,       // 0
-        INSTRUCTION,  // 1
-        INT_LITERAL,  // 2
-        SUBLIST       // 3
-    }
-
-    enum OpCode {
-        NOOP,         // 0
-        INTEGER_PLUS  // 1
-    }
-
-    // -----------------------------------------------------
-    // 2. DESCRIPTOR BIT LAYOUT
-    // -----------------------------------------------------
-    // [255..248] : tag (8 bits)
-    // [247..216] : offset (32 bits)  (for SUBLIST)
-    // [215..184] : length (32 bits)  (for SUBLIST)
-    // [183..0]   : leftover bits     (opcode or literal data)
-
-    function getTag(uint256 desc) internal pure returns (CodeTag) {
-        return CodeTag(uint8(desc >> 248));
-    }
-
-    function getOffset(uint256 desc) internal pure returns (uint32) {
-        return uint32(desc >> 216);
-    }
-
-    function getLength(uint256 desc) internal pure returns (uint32) {
-        return uint32(desc >> 184);
-    }
-
-    function getLow184(uint256 desc) internal pure returns (uint256) {
-        return desc & ((1 << 184) - 1);
-    }
-
-    // Build a descriptor
-    function makeDescriptor(
-        CodeTag tag,
-        uint32 offset,
-        uint32 length,
-        uint256 low184
-    )
-        public
-        pure
-        returns (uint256)
-    {
-        require(low184 < (1 << 184), "low184 out of range");
-        return 
-            (uint256(uint8(tag)) << 248) |
-            (uint256(offset) << 216) |
-            (uint256(length) << 184) |
-            low184;
-    }
-
-    function makeInstruction(OpCode op) internal pure returns (uint256) {
-        return makeDescriptor(CodeTag.INSTRUCTION, 0, 0, uint256(uint8(op)));
-    }
-
-    function getOpCode(uint256 desc) internal pure returns (OpCode) {
-        return OpCode(uint8(desc & 0xFF));
-    }
-
-    function makeIntLiteral(int32 val) internal pure returns (uint256) {
-        // store 32-bit integer in leftover
-        uint256 masked = uint256(uint32(val));
-        return makeDescriptor(CodeTag.INT_LITERAL, 0, 0, masked);
-    }
-
-    function extractInt32(uint256 desc) internal pure returns (int32) {
-        // read the low 32 bits
-        return int32(uint32(getLow184(desc)));
-    }
-
-    // -----------------------------------------------------
-    // 3. HELPER READS
-    // -----------------------------------------------------
-
-    /**
-     * @dev Read 4 bytes from `code` at `start` as uint32.
-     */
-    function readUint32(bytes calldata code, uint32 start) internal pure returns (uint32 val) {
-        require(start + 4 <= code.length, "readUint32 out of range");
-        uint256 word;
-        assembly {
-            let buf := mload(0x40) // free memory
-            // copy exactly 4 bytes from code into buf
-            calldatacopy(buf, add(code.offset, start), 4)
-            word := mload(buf)
-        }
-        val = uint32(word >> 224);
-    }
-
-    /**
-     * @dev Read 2 bytes from `code` at `start` as uint16.
-     */
-    function readUint16(bytes calldata code, uint32 start) internal pure returns (uint16 val) {
-        require(start + 2 <= code.length, "readUint16 out of range");
-        assembly {
-            let buf := mload(0x40)
-            calldatacopy(buf, add(code.offset, start), 2)
-            let word := mload(buf)
-            val := and(word, 0xffff)
-        }
-    }
-
-    // -----------------------------------------------------
-    // 4. SUBLIST PARSING
-    // -----------------------------------------------------
-    /**
-     * Token format:
-     *   0x00 => NOOP
-     *   0x01 => INTEGER_PLUS
-     *   0x02 => INT_LITERAL => read next 4 bytes => int32
-     *   0x03 => SUBLIST => read next 2 bytes => subLen => parse that
-     */
-    function parseSublist(bytes calldata code, uint32 off, uint32 len)
-        internal
-        pure
-        returns (uint256[] memory descs)
-    {
-        uint256[] memory temp = new uint256[](len);
-        uint256 count = 0;
-        uint32 endPos = off + len;
-        uint32 cur = off;
-
-        while (cur < endPos) {
-            if (cur >= code.length) {
-                break;
-            }
-
-            uint8 tokenType = uint8(code[cur]);
-            cur++;
-
-            if (tokenType == 0x00) {
-                // NOOP
-                temp[count] = makeInstruction(OpCode.NOOP);
-                count++;
-            }
-            else if (tokenType == 0x01) {
-                // INTEGER_PLUS
-                temp[count] = makeInstruction(OpCode.INTEGER_PLUS);
-                count++;
-            }
-            else if (tokenType == 0x02) {
-                // INT_LITERAL => 4 bytes
-                if (cur + 4 <= endPos && (cur + 4) <= code.length) {
-                    uint32 raw = readUint32(code, cur);
-                    cur += 4;
-                    int32 val = int32(raw);
-                    temp[count] = makeIntLiteral(val);
-                    count++;
-                } else {
-                    break;
-                }
-            }
-            else if (tokenType == 0x03) {
-                // SUBLIST => read 2 bytes => length
-                if (cur + 2 <= endPos && (cur + 2) <= code.length) {
-                    uint16 subLen = readUint16(code, cur);
-                    cur += 2;
-                    if (cur + subLen <= endPos && (cur + subLen) <= code.length) {
-                        // create descriptor
-                        temp[count] = makeDescriptor(CodeTag.SUBLIST, cur, subLen, 0);
-                        count++;
-                        // skip over that subLen chunk
-                        cur += subLen;
-                    } else {
-                        break;
-                    }
-                } else {
-                    break;
-                }
-            }
-            else {
-                // unknown => NOOP
-                temp[count] = makeInstruction(OpCode.NOOP);
-                count++;
-            }
-        }
-
-        descs = new uint256[](count);
-        for (uint256 i = 0; i < count; i++) {
-            descs[i] = temp[i];
-        }
-    }
-
-    // -----------------------------------------------------
-    // 5. MAIN INTERPRETER
-    // -----------------------------------------------------
-    function runInterpreter(
-        bytes calldata code,
-        uint256[] calldata initCodeStack,
-        uint256[] calldata initExecStack,
-        int256[] calldata initIntStack
-    )
-        external
-        pure
-        returns (
-            uint256[] memory finalCodeStack,
-            uint256[] memory finalExecStack,
-            int256[]  memory finalIntStack
-        )
-    {
-        // A) CODE STACK
-        uint256[] memory codeStack = new uint256[](initCodeStack.length + 256);
-        uint256 codeTop = initCodeStack.length;
-        for (uint256 i = 0; i < initCodeStack.length; i++) {
-            codeStack[i] = initCodeStack[i];
-        }
-
-        // B) EXEC STACK
-        uint256[] memory execStack = new uint256[](initExecStack.length + 256);
-        uint256 execTop = initExecStack.length;
-        for (uint256 e = 0; e < initExecStack.length; e++) {
-            execStack[e] = initExecStack[e];
-        }
-
-        // C) INT STACK
-        int256[] memory intStack = new int256[](initIntStack.length + 256);
-        uint256 intTop = initIntStack.length;
-        for (uint256 k = 0; k < initIntStack.length; k++) {
-            intStack[k] = initIntStack[k];
-        }
-
-        // D) MAIN LOOP
-        while (execTop > 0) {
-            uint256 topDesc = execStack[execTop - 1];
-            execTop--;
-
-            CodeTag tag = getTag(topDesc);
-
-            if (tag == CodeTag.INSTRUCTION) {
-                OpCode op = getOpCode(topDesc);
-                if (op == OpCode.NOOP) {
-                    // do nothing
-                }
-                else if (op == OpCode.INTEGER_PLUS) {
-                    // pop top 2 => sum
-                    if (intTop >= 2) {
-                        int256 a = intStack[intTop - 1];
-                        int256 b = intStack[intTop - 2];
-                        intTop -= 2;
-                        intStack[intTop] = b + a;
-                        intTop++;
-                    }
-                }
-            }
-            else if (tag == CodeTag.INT_LITERAL) {
-                int32 val = extractInt32(topDesc);
-                intStack[intTop] = int256(val);
-                intTop++;
-            }
-            else if (tag == CodeTag.SUBLIST) {
-                // parse sublist => push in reverse
-                uint32 off = getOffset(topDesc);
-                uint32 len = getLength(topDesc);
-
-                if (off + len <= code.length) {
-                    uint256[] memory parsed = parseSublist(code, off, len);
-                    for (uint256 p = 0; p < parsed.length; p++) {
-                        execStack[execTop] = parsed[parsed.length - 1 - p];
-                        execTop++;
-                    }
-                }
-            }
-            else {
-                // NO_TAG => do nothing
-            }
-        }
-
-        // E) RETURN
-        finalCodeStack = new uint256[](codeTop);
-        for (uint256 i = 0; i < codeTop; i++) {
-            finalCodeStack[i] = codeStack[i];
-        }
-
-        finalExecStack = new uint256[](execTop);
-        for (uint256 i = 0; i < execTop; i++) {
-            finalExecStack[i] = execStack[i];
-        }
-
-        finalIntStack = new int256[](intTop);
-        for (uint256 i = 0; i < intTop; i++) {
-            finalIntStack[i] = intStack[i];
-        }
-    }
-}

test/Push3Interpreter.t.sol

@@ -1,75 +0,0 @@
-// SPDX-License-Identifier: UNLICENSED
-pragma solidity ^0.8.20;
-
-import {Test} from "forge-std/Test.sol";
-import {Push3Interpreter} from "../src/Push3Interpreter.sol";
-
-/**
- * @title Push3InterpreterTest
- * @dev Foundry test contract for the updated Push3Interpreter
- */
-contract Push3InterpreterTest is Test {
-    Push3Interpreter public interpreter;
-
-    function setUp() public {
-        interpreter = new Push3Interpreter();
-    }
-
-    /**
-     * @notice Test a small program that:
-     *   1) Pushes literal 10 (int32)
-     *   2) Pushes literal 32 (int32)
-     *   3) Calls INTEGER_PLUS
-     *
-     *  We'll store everything in a single SUBLIST:
-     *  0x03 => SUBLIST
-     *  0x00 0x0B => subLen=11
-     *  Then the next 11 bytes are:
-     *    0x02 + (00 00 00 0A) => INT_LITERAL(10)
-     *    0x02 + (00 00 00 20) => INT_LITERAL(32)
-     *    0x01 => INTEGER_PLUS
-     *
-     *  So total = 1 + 2 + (1+4 + 1+4 + 1) = 14 bytes
-     *  => 0x03 00 0B 02 00 00 00 0A 02 00 00 00 20 01
-     */
-    function test_LiteralsAndPlus() public {
-        // The final code array (14 bytes):
-        //  [0] = 0x03
-        //  [1..2] = 0x000B
-        //  [3] =  0x02
-        //  [4..7] = 0x0000000A => 10
-        //  [8] =  0x02
-        //  [9..12] = 0x00000020 => 32
-        //  [13] = 0x01 => plus
-
-        bytes memory code = hex"03000B020000000A020000002001";        
-
-        // Or fully concatenated:
-        // 0x03 00 0B 02 00 00 00 0A 02 00 00 00 20 01
-
-        // We'll parse offset=0, length=14
-        uint256 sublistDesc = interpreter.makeDescriptor(
-            Push3Interpreter.CodeTag.SUBLIST,
-            0,   // offset
-            14,  // length
-            0
-        );
-
-        uint256[] memory initCodeStack = new uint256[](0);
-        uint256[] memory initExecStack = new uint256[](1);
-        initExecStack[0] = sublistDesc;
-
-        int256[] memory initIntStack = new int256[](0);
-
-        // Run it
-        (
-            uint256[] memory finalCodeStack,
-            uint256[] memory finalExecStack,
-            int256[] memory finalIntStack
-        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack);
-
-        // Should produce finalIntStack = [42]
-        assertEq(finalIntStack.length, 1, "finalIntStack should have length 1");
-        assertEq(finalIntStack[0], 42, "Should be 10+32=42");
-    }
-}