fix adapter unit tests

.envrc

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

.gitignore

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

ISSUE_TEMPLATE.md

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

Interpreter.md

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

README.md

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

flake.nix

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

offchain/Cargo.toml

@@ -0,0 +1,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

@@ -28,9 +28,9 @@ contract Push3IntAdapter {
         view
         returns (uint256)
     {
-        // CodeTag.SUBLIST is typically enum = 3, but 
-        // let's fetch it via 
-        //   (uint8)Push3Interpreter.CodeTag.SUBLIST 
+        // 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:
@@ -69,9 +69,12 @@ contract Push3IntAdapter {
         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);
+        (, , 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");
@@ -96,11 +99,13 @@ contract Push3IntAdapter {
         initIntStack[0] = in1;
         initIntStack[1] = in2;
 
-        (, , int256[] memory finalIntStack) =
-            interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack);
+        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];
     }
 
@@ -121,8 +126,10 @@ contract Push3IntAdapter {
         int256[] memory initIntStack = new int256[](1);
         initIntStack[0] = in1;
 
-        (, , int256[] memory finalIntStack) =
-            interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack);
+        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];
@@ -130,7 +137,7 @@ contract Push3IntAdapter {
     }
 
     /**
-     * @notice Zero int input, returns entire final int stack 
+     * @notice Zero int input, returns entire final int stack
      */
     function run0InNOut(bytes calldata code)
         external
@@ -143,9 +150,10 @@ contract Push3IntAdapter {
 
         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);
+        (, , int256[] memory finalIntStack,) =
+            interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
 
         return finalIntStack;
     }

onchain/src/Push3Interpreter.sol

@@ -9,6 +9,15 @@ import "forge-std/console.sol";
  *      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 = 0x05;
+    uint8 internal constant OPCODE_BOOL_OFFSET = 0x0a;
+    uint8 internal constant OPCODE_LAST = OPCODE_BOOL_OFFSET + 0x10;
+
     // -----------------------------------------------------
     // 1. ENUMS
     // -----------------------------------------------------
@@ -16,16 +25,38 @@ contract Push3Interpreter {
         NO_TAG,       // 0
         INSTRUCTION,  // 1
         INT_LITERAL,  // 2
-        SUBLIST       // 3
+        BOOL_LITERAL, // 3
+        SUBLIST       // 4
     }
 
     enum OpCode {
-        NOOP,          // 0
-        INTEGER_PLUS,  // 1
-        INTEGER_MINUS, // 2
-        INTEGER_MULT,  // 3
-        INTEGER_DUP,   // 4
-        INTEGER_POP    // 5
+        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
     }
 
     // -----------------------------------------------------
@@ -85,56 +116,81 @@ contract Push3Interpreter {
         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) {
-        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);
+        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) {
-        require(start + 2 <= code.length, "readUint16 out of range");
-        uint256 word;
-        assembly {
-            let buf := mload(0x40)
-            calldatacopy(buf, add(code.offset, start), 2)
-            word := mload(buf)
-            val := and(word, 0xffff)
-        }
-        // Not sure this is correct
-        val = uint16(word >> 240);
+        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:
-     *   0x00 => NOOP
-     *   0x01 => INTEGER_PLUS
+     * 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 => SUBLIST => read next 2 bytes => subLen => parse that
-     *   0x04 => INTEGER_MINUS
+     *   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
@@ -160,9 +216,15 @@ contract Push3Interpreter {
                 count++;
             }
             else if (tokenType == 0x01) {
-                // INTEGER_PLUS
-                temp[count] = makeInstruction(OpCode.INTEGER_PLUS);
-                count++;
+                // 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
@@ -177,6 +239,17 @@ contract Push3Interpreter {
                 }
             }
             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);
@@ -194,22 +267,9 @@ contract Push3Interpreter {
                     break;
                 }
             }
-            else if (tokenType == 0x04) {
-                // INTEGER_PLUS
-                temp[count] = makeInstruction(OpCode.INTEGER_MINUS);
-                count++;
-            }
-            else if (tokenType == 0x05) {
-                // INTEGER_PLUS
-                temp[count] = makeInstruction(OpCode.INTEGER_MULT);
-                count++;
-            }
-            else if (tokenType == 0x06) {
-                temp[count] = makeInstruction(OpCode.INTEGER_DUP);
-                count++;
-            }
-            else if (tokenType == 0x07) {
-                temp[count] = makeInstruction(OpCode.INTEGER_POP);
+            else if (tokenType <= OPCODE_LAST) {
+                // OPCODE
+                temp[count] = makeInstruction(OpCode(tokenType));
                 count++;
             }
             else {
@@ -229,17 +289,19 @@ contract Push3Interpreter {
     // 5. MAIN INTERPRETER
     // -----------------------------------------------------
     function runInterpreter(
-        bytes calldata code,
-        uint256[] calldata initCodeStack,
-        uint256[] calldata initExecStack,
-        int256[] calldata initIntStack
+        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
         pure
         returns (
             uint256[] memory finalCodeStack,
             uint256[] memory finalExecStack,
-            int256[]  memory finalIntStack
+            int256[]  memory finalIntStack,
+            bool[] memory finalBoolStack
         )
     {
         // A) CODE STACK
@@ -263,6 +325,13 @@ contract Push3Interpreter {
             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];
@@ -272,50 +341,56 @@ contract Push3Interpreter {
 
             if (tag == CodeTag.INSTRUCTION) {
                 OpCode op = getOpCode(topDesc);
-                if (op == OpCode.NOOP) {
-                    // do nothing
+                if (uint8(op) < OPCODE_INTEGER_OFFSET) {
+                    // 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 (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 (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
                 }
             }
             else if (tag == CodeTag.INT_LITERAL) {
@@ -323,6 +398,11 @@ contract Push3Interpreter {
                 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);
@@ -330,8 +410,8 @@ contract Push3Interpreter {
 
                 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];
+                    for (uint256 p = 0; p < parsed.length; p++) {       // index 0     1     2
+                        execStack[execTop] = parsed[parsed.length - 1 - p]; // [0x01, 0x20, 0x0a]
                         execTop++;
                     }
                 }
@@ -356,5 +436,10 @@ contract Push3Interpreter {
         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

@@ -23,12 +23,12 @@ contract Push3IntAdapterTest is Test {
     }
 
     /**
-     * @notice Test run1In1Out with a minimal code array. 
-     * For example, we might do a program that just leaves its input unchanged 
-     * (like a NOOP). 
+     * @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"03000100";
+        bytes memory code = hex"04000100";
 
         int256 inputVal = 123;
         int256 result = adapter.run1In1Out(code, inputVal);
@@ -41,21 +41,21 @@ contract Push3IntAdapterTest is Test {
      * @notice Test run2In1Out. We'll push 5, 7, do an op that leaves 12.
      */
     function test_run2In1Out_plus() public view {
-        bytes memory code = hex"03000101";
+        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. 
+     * For now, we do a placeholder code.
      */
     function test_run1In2Out() public view {
-        bytes memory code = hex"0300050200000003";
+        bytes memory code = hex"0400050200000003";
 
         int256 inVal = 42;
         (int256 top, int256 secondTop) = adapter.run1In2Out(code, inVal);
@@ -65,12 +65,12 @@ contract Push3IntAdapterTest is Test {
     }
 
     /**
-     * @notice Test run0InNOut. 
+     * @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"03000A02000000030200000005";
+
+        bytes memory code = hex"04000A02000000030200000005";
 
         int256[] memory stackResult = adapter.run0InNOut(code);
 

onchain/test/Push3Interpreter.t.sol

@@ -23,30 +23,30 @@ contract Push3InterpreterTest is Test {
      *   3) Calls INTEGER_PLUS
      *
      *  We'll store everything in a single SUBLIST:
-     *  0x03 => 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)
-     *    0x01 => INTEGER_PLUS
+     *    0x05 => 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
+     *  => 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] = 0x03
+        //  [0] = 0x04
         //  [1..2] = 0x000B
         //  [3] =  0x02
         //  [4..7] = 0x0000000A => 10
         //  [8] =  0x02
         //  [9..12] = 0x00000020 => 32
-        //  [13] = 0x01 => plus
+        //  [13] = 0x05 => plus
 
-        bytes memory code = hex"03000B020000000A020000002001";        
+        bytes memory code = hex"04000B020000000A020000002005";
 
         // Or fully concatenated:
-        // 0x03 00 0B 02 00 00 00 0A 02 00 00 00 20 01
+        // 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(
@@ -61,13 +61,15 @@ contract Push3InterpreterTest is Test {
         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);
+            ,
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
 
         // Should produce finalIntStack = [42]
         assertEq(finalIntStack.length, 1, "finalIntStack should have length 1");
@@ -78,25 +80,25 @@ contract Push3InterpreterTest is Test {
      * @notice Test pushing literal 10, literal 3, then INTEGER_MINUS => (10 - 3) = 7
      *
      * The plan:
-     *  0x03 => SUBLIST token
+     *  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)
-     *    0x04 => INTEGER_MINUS (assuming 0x04 is assigned to minus)
+     *    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: [0x03, 0x000B, 0x02(10), 0x03(3), 0x04 => minus]
+        // Format: [0x04, 0x000B, 0x02(10), 0x03(3), 0x06 => minus]
 
-        bytes memory code = hex"03000B020000000A020000000304";
+        bytes memory code = hex"04000B020000000A020000000306";
         // Breaking it down:
-        // 0x03          => SUBLIST
+        // 0x04          => SUBLIST
         // 0x00 0x0B     => length=11
         // 0x02 0000000A => INT_LITERAL(10)
         // 0x02 00000003 => INT_LITERAL(3)
-        // 0x04          => INTEGER_MINUS
+        // 0x06          => INTEGER_MINUS
 
         // We'll parse offset=0, length=14
         uint256 sublistDesc = interpreter.makeDescriptor(
@@ -111,13 +113,15 @@ contract Push3InterpreterTest is Test {
         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);
+            ,
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
 
         // Check final result => should be [7]
         assertEq(finalIntStack.length, 1, "finalIntStack should have length 1");
@@ -128,25 +132,25 @@ contract Push3InterpreterTest is Test {
      * @notice Test pushing literal 10, literal 3, then INTEGER_MULT => (10 * 3) = 30
      *
      * The plan:
-     *  0x03 => SUBLIST token
+     *  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)
-     *    0x05 => INTEGER_MULT
+     *    0x07 => INTEGER_MULT
      */
     function test_Mult() public view {
         // We'll produce 14 total bytes, same structure as the plus example
-        // Format: [0x03, 0x000B, 0x02(10), 0x03(3), 0x05 => mul]
+        // Format: [0x04, 0x000B, 0x02(10), 0x02(3), 0x07 => mul]
 
-        bytes memory code = hex"03000B020000000A020000000305";
+        bytes memory code = hex"04000B020000000A020000000307";
         // Breaking it down:
-        // 0x03          => SUBLIST
+        // 0x04          => SUBLIST
         // 0x00 0x0B     => length=11
         // 0x02 0000000A => INT_LITERAL(10)
         // 0x02 00000003 => INT_LITERAL(3)
-        // 0x05          => INTEGER_MUL
+        // 0x07          => INTEGER_MUL
 
         // We'll parse offset=0, length=14
         uint256 sublistDesc = interpreter.makeDescriptor(
@@ -161,13 +165,15 @@ contract Push3InterpreterTest is Test {
         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);
+            ,
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
 
         // Check final result => should be [30]
         assertEq(finalIntStack.length, 1, "finalIntStack should have length 1");
@@ -176,12 +182,12 @@ contract Push3InterpreterTest is Test {
 
     function test_Dup() public view {
 
-        bytes memory code = hex"030006020000000A06";
+        bytes memory code = hex"040006020000000A08";
 
         uint256 sublistDesc = interpreter.makeDescriptor(
             Push3Interpreter.CodeTag.SUBLIST,
-            0,  
-            9, 
+            0,
+            9,
             0
         );
 
@@ -190,13 +196,15 @@ contract Push3InterpreterTest is Test {
         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);
+            ,
+        ) = 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 stack should be equal.");
@@ -204,12 +212,12 @@ contract Push3InterpreterTest is Test {
 
     function test_Pop() public view {
 
-        bytes memory code = hex"030006020000000A07";
+        bytes memory code = hex"040006020000000A09";
 
         uint256 sublistDesc = interpreter.makeDescriptor(
             Push3Interpreter.CodeTag.SUBLIST,
-            0,  
-            9, 
+            0,
+            9,
             0
         );
 
@@ -218,33 +226,35 @@ contract Push3InterpreterTest is Test {
         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);
+            ,
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
 
         assertEq(finalIntStack.length, 0, "finalIntStack should be empty");
     }
 
     /**
      * @notice Test with an unknown token (0xF0).
-     * We expect the parser to treat it as "unknown => NOOP" 
+     * 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:
-        //  0x03 => SUBLIST
+        //  0x04 => SUBLIST
         //  0x00 0x01 => length=1
         //  0xF0 => unknown token
-        bytes memory code = hex"030001F0";
+        bytes memory code = hex"040001F0";
 
         // We'll parse offset=0, length=4
         uint256 sublistDesc = interpreter.makeDescriptor(
-            Push3Interpreter.CodeTag.SUBLIST, 
+            Push3Interpreter.CodeTag.SUBLIST,
             0,   // offset
             4,   // length
             0
@@ -255,12 +265,14 @@ contract Push3InterpreterTest is Test {
         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);
+            ,
+        ) = 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");
@@ -268,18 +280,18 @@ contract Push3InterpreterTest is Test {
 
     /**
      * @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 
+     * This should trigger the `else { break; }` branch in parseSublist
      * when trying to read 4 bytes for the INT_LITERAL.
      */
     function test_OutOfRangeLiteral() public view {
-        //  0x03 => SUBLIST
+        //  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"03000402FF";
+        bytes memory code = hex"04000402FF";
 
         // parse offset=0, length=5
         uint256 sublistDesc = interpreter.makeDescriptor(
@@ -293,12 +305,14 @@ contract Push3InterpreterTest is Test {
         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);
+            ,
+        ) = 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");
@@ -310,12 +324,12 @@ contract Push3InterpreterTest is Test {
      * In the main loop, it sees intTop < 2 => it does nothing.
      */
     function test_NotEnoughIntArgs() public view {
-        bytes memory code = hex"030006020000000305";
+        bytes memory code = hex"040006020000000307";
         // Breaking it down:
-        // 0x03          => SUBLIST
+        // 0x04          => SUBLIST
         // 0x00 0x06     => length=6
         // 0x02 00000003 => INT_LITERAL(3)
-        // 0x05          => INTEGER_MUL
+        // 0x07          => INTEGER_MUL
 
         uint256 sublistDesc = interpreter.makeDescriptor(
             Push3Interpreter.CodeTag.SUBLIST,
@@ -329,14 +343,16 @@ contract Push3InterpreterTest is Test {
         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);
+            ,
+        ) = interpreter.runInterpreter(code, initCodeStack, initExecStack, initIntStack, initBoolStack);
 
-        // We expect finalIntStack => [5], 
+        // 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");
@@ -344,12 +360,12 @@ contract Push3InterpreterTest is Test {
 
     /**
      * @notice Test sublist length overflow:
-     * subLen claims bigger than the code array. Should trigger else { break; } 
+     * 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"; 
+
+        bytes memory code = hex"050010FFFFFF";
 
         uint256 sublistDesc = interpreter.makeDescriptor(
             Push3Interpreter.CodeTag.SUBLIST,
@@ -363,12 +379,14 @@ contract Push3InterpreterTest is Test {
         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);
+            ,
+        ) = 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");

tokenomics.md

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