tokenomics draft

merge interpreter.md into readme (#4 )
Co-authored-by: JulesCrown <admin@noip.localhost> Reviewed-on: http://gitea.loseyourip.com:4000/giteadmin/SoLUSH-3/pulls/4
2024-12-27 15:40:35 +01:00 · 2024-12-26 10:30:26 +00:00 · 2024-12-24 12:02:50 +00:00 · 2024-12-24 12:02:08 +00:00 · 2024-12-24 12:00:57 +00:00
24 changed files with 309 additions and 5780 deletions
@@ -1 +0,0 @@
 use flake
@@ -1,6 +1,5 @@
 onchain/cache/
 onchain/out/
-
+out/
-offchain/target/
+cache/
-
+lib/forge-std
 .direnv
@@ -0,0 +1,47 @@
 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
 -->
@@ -1,124 +0,0 @@
 # 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!
@@ -1,6 +1,14 @@
 # **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 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.
+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.
 ## 🌟 Vision
@@ -12,19 +20,97 @@ 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
-SoLUSH 3 is in active development. To contribute or test the functionality, follow these steps:
+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 the repository:
+1. **Clone** this repo.  
-   ```bash
+2. **Check** the `test/` folder for Foundry-based tests.  
-   git clone https://github.com/your-username/SoLUSH.git
+3. **Add** or modify instructions & sublists in `parseSublist` and `runInterpreter`.  
-   cd SoLUSH
+4. **Run** `forge test --via-ir -vv` to see logs and confirm your changes.
   ```
 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:**
@@ -23,9 +23,6 @@
            # ... any other dependencies we need
            solc
            cargo
            rustc
            rust-analyzer
          ];
          # Decorative prompt override so we know when we're in a dev shell
@@ -1,22 +0,0 @@
 [package]
 name = "offchain"
 version = "0.1.0"
 edition = "2021"
 [[bin]]
 name = "gp_tester"
 path = "src/bin/gp_tester.rs"
 [dependencies]
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 rand = "0.8"
 hex = "0.4"
 # ethers = { version = "2.0", features = ["abi"] }
 anyhow = "1.0"
 revm = { git = "https://github.com/bluealloy/revm.git", rev = "03ea24bd9550e93b08f343e0b410725557c1adb4", features = ["std"] }
 database = { git = "https://github.com/bluealloy/revm.git", rev = "03ea24bd9550e93b08f343e0b410725557c1adb4", package = "revm-database" }
 ethers = "2.0"
@@ -1,91 +0,0 @@
 // src/bin/gp_tester.rs
 use anyhow::{anyhow, bail, Result};
 use rand::{thread_rng, Rng};
 // 1) We'll use the helper that reads creation code from a JSON artifact
 use offchain::helpers::artifact::get_creation_code;
 // 2) EvmRunner to deploy & run the interpreter
 use offchain::runner::revm_runner::EvmRunner;
 // 3) AST generation & mutation
 use offchain::gp::generate::random_ast;
 use offchain::gp::genetic_ops::mutated_ast;
 use offchain::compiler::ast::UntypedAst;
 fn main() -> Result<()> {
    // ----------------------------------------------------------------------
    // 1) Read the creation code (Push3Interpreter) using our helper function
    // ----------------------------------------------------------------------
    let creation_hex_filename = "../onchain/out/Push3Interpreter.sol/Push3Interpreter.json";
    let creation_bytes = get_creation_code(creation_hex_filename)?;
    println!(
        "Loaded creation code from {} ({} bytes)",
        creation_hex_filename,
        creation_bytes.len()
    );
    // 2) Create the ephemeral EVM (deploy the contract)
    let mut runner = EvmRunner::new(creation_bytes)?;
    println!("Deployed test interpreter at: 0x{:x}\n", runner.interpreter_addr);
    // 3) We'll generate random ASTs & mutate them
    let number_of_programs = 3; // how many random ASTs to try
    let max_depth = 4;         // max AST depth
    let mut rng = thread_rng();
    for i in 0..number_of_programs {
        // a) Generate a random AST
        let ast: UntypedAst = random_ast(&mut rng, 0, max_depth);
        println!("=== Program {} ===", i);
        println!("Random AST:\n{:#?}", ast);
        // b) Run the original AST
        match runner.run_ast(&ast) {
            Ok(outputs) => {
                println!("Original AST ran successfully!");
                println!("Final CODE stack: {:?}", outputs.final_code_stack);
                println!("Final EXEC stack: {:?}", outputs.final_exec_stack);
                println!("Final INT stack:  {:?}", outputs.final_int_stack);
                // c) Mutate it a few times
                let mutated1 = mutated_ast(&ast, &mut rng, 0, max_depth);
                println!("\n-- MUTATED 1 --\n{:#?}", mutated1);
                match runner.run_ast(&mutated1) {
                    Ok(m1_out) => {
                        println!("MUTATED 1 ran successfully!");
                        println!("Final INT stack: {:?}", m1_out.final_int_stack);
                    }
                    Err(e) => {
                        println!("MUTATED 1 error: {}", e);
                    }
                }
                let mutated2 = mutated_ast(&ast, &mut rng, 0, max_depth);
                println!("\n-- MUTATED 2 --\n{:#?}", mutated2);
                match runner.run_ast(&mutated2) {
                    Ok(m2_out) => {
                        println!("MUTATED 2 ran successfully!");
                        println!("Final INT stack: {:?}", m2_out.final_int_stack);
                    }
                    Err(e) => {
                        println!("MUTATED 2 error: {}", e);
                    }
                }
            }
            Err(e) => {
                // If the original fails, we won't bother mutating it
                println!("Original AST error: {}", e);
            }
        }
        println!("=== End of Program {} ===\n", i);
    }
    println!("Finished running & mutating {} random programs.", number_of_programs);
    Ok(())
 }
@@ -1,273 +0,0 @@
 //! src/compiler/ast.rs
 //! 
 //! This module defines an **abstract** untyped AST for our Push3-like language,
 //! plus a mapping for how to encode opcodes as bytes. We do *not* hardcode numeric
 //! values in the `OpCode` enum. Instead, we provide a trait that can map
 //! opcodes to bytes. This allows us to expand or change instructions easily
 //! (e.g., when the on-chain interpreter adds new opcodes or changes their IDs).
 /// A trait describing how to convert an AST into Push3 bytecode.
 ///
 /// This is deliberately minimal for now. In the future, we could add more methods
 /// (like parsing from bytecode or AST mutation).
 pub trait Push3Ast {
    /// Convert this AST into a bytecode vector that the on-chain interpreter
    /// can parse and execute.
    fn to_bytecode(&self) -> Vec<u8>;
 }
 /// A trait that **maps** each [`OpCode`] variant to its **single-byte** representation.
 ///
 /// By centralizing this, we can easily add or reorder instructions without rewriting
 /// big chunks of code everywhere. For example, if we add `OpCode::MyNewOp`, we just
 /// update this trait’s logic.
 pub trait OpCodeMapping {
    /// Given an `OpCode` enum variant, return the corresponding single `u8`
    /// that the interpreter expects.
    fn opcode_byte(&self, op: &OpCode) -> u8;
    // If you need reverse-lookup (byte => OpCode), you could add a method like:
    // fn from_byte(&self, b: u8) -> Option<OpCode>;
    // for now, we omit it since we only do forward mapping in this file.
 }
 /// Our untyped AST node:
 /// - `IntLiteral(i32)` holds a literal integer,
 /// - `Instruction(OpCode)` holds one opcode,
 /// - `Sublist(Vec<UntypedAst>)` holds a collection of nested AST nodes.
 #[derive(Debug, Clone, PartialEq)]
 pub enum UntypedAst {
    IntLiteral(i32),
    Instruction(OpCode),
    Sublist(Vec<UntypedAst>),
 }
 /// An **abstract** set of opcodes. We do *not* assign numeric values here.
 /// Instead, see [`OpCodeMapping::opcode_byte`] for how we convert them to bytes.
 #[derive(Debug, Clone, PartialEq)]
 pub enum OpCode {
    Noop,
    Plus,
    Minus,
    Mult,
    Dup,
    Pop,
    // Add new instructions here as needed. E.g.:
    // MyNewOp, etc.
 }
 impl UntypedAst {
    /// Encode this AST into bytecode, using a provided [`OpCodeMapping`].
    ///
    /// This method is more flexible than `to_bytecode()`, because you can pass in
    /// *any* mapping if needed. The method used by the trait’s `to_bytecode()`
    /// relies on the global `DEFAULT_OP_MAPPING`.
    pub fn to_bytecode_with_mapping<M: OpCodeMapping>(&self, mapping: &M) -> Vec<u8> {
        match self {
            // For an integer literal, we write the “tag byte” for int-literal, then 4 bytes (LE).
            UntypedAst::IntLiteral(val) => {
                // Hardcode 0x02 => INT_LITERAL. 
                // You *could* put that in the mapping if you want to make that flexible, too.
                let mut bytes = Vec::with_capacity(1 + 4);
                bytes.push(0x02);
                bytes.extend_from_slice(&val.to_be_bytes());
                bytes
            }
            UntypedAst::Instruction(op) => {
                // Use the mapping to find the correct opcode byte:
                let b = mapping.opcode_byte(op);
                vec![b]
            }
            UntypedAst::Sublist(children) => {
                // Hardcode 0x03 => SUBLIST, then big-endian length, then child payload
                let mut payload = Vec::new();
                for child in children {
                    let child_bytes = child.to_bytecode_with_mapping(mapping);
                    payload.extend(child_bytes);
                }
                let sub_len = payload.len() as u16;
                let mut bytes = Vec::with_capacity(1 + 2 + payload.len());
                bytes.push(0x03);
                bytes.extend_from_slice(&sub_len.to_be_bytes()); // big-endian length
                bytes.extend(payload);
                bytes
            }
        }
    }
 }
 /// For convenience, we implement `Push3Ast` using a *default* mapping.
 impl Push3Ast for UntypedAst {
    fn to_bytecode(&self) -> Vec<u8> {
        self.to_bytecode_with_mapping(&DEFAULT_OP_MAPPING)
    }
 }
 /// A default mapping that corresponds to your current on-chain byte definitions.
 ///
 /// This way, if your interpreter changes (e.g., `Minus` becomes 0x0A),
 /// you just update this mapping.
 pub struct DefaultOpCodeMapping;
 impl OpCodeMapping for DefaultOpCodeMapping {
    fn opcode_byte(&self, op: &OpCode) -> u8 {
        match op {
            OpCode::Noop  => 0x00, // 0x00 => NOOP
            OpCode::Plus  => 0x01, // 0x01 => INTEGER_PLUS
            OpCode::Minus => 0x04, // 0x04 => INTEGER_MINUS
            OpCode::Mult  => 0x05, // 0x05 => INTEGER_MULT
            OpCode::Dup   => 0x06, // 0x06 => INTEGER_DUP
            OpCode::Pop   => 0x07, // 0x07 => INTEGER_POP
        }
    }
 }
 /// A convenient global `const` or `static` for quick usage.
 pub const DEFAULT_OP_MAPPING: DefaultOpCodeMapping = DefaultOpCodeMapping;
 // ----------------------------------------------------------------------------
 // S-Expression Parsing Helpers
 // ----------------------------------------------------------------------------
 /// A simple S-expression tree for textual representation: either an `Atom` or a `List`.
 #[derive(Debug, Clone, PartialEq)]
 pub enum SExpr {
    Atom(String),
    List(Vec<SExpr>),
 }
 /// Tokenize a string into parentheses and symbols (atoms).
 pub fn tokenize(s: &str) -> Vec<String> {
    let mut tokens = Vec::new();
    let mut current = String::new();
    for c in s.chars() {
        match c {
            '(' | ')' => {
                if !current.trim().is_empty() {
                    tokens.push(current.trim().to_string());
                }
                current.clear();
                tokens.push(c.to_string());
            }
            ' ' | '\t' | '\n' | '\r' => {
                if !current.trim().is_empty() {
                    tokens.push(current.trim().to_string());
                    current.clear();
                }
            }
            _ => {
                current.push(c);
            }
        }
    }
    if !current.trim().is_empty() {
        tokens.push(current.trim().to_string());
    }
    tokens
 }
 /// Recursive helper to parse a single S-expression from a list of tokens, advancing `pos`.
 fn parse_sexpr_internal(tokens: &[String], pos: &mut usize) -> Result<SExpr, String> {
    if *pos >= tokens.len() {
        return Err("Unexpected end of tokens".to_string());
    }
    let token = &tokens[*pos];
    match token.as_str() {
        "(" => {
            *pos += 1; // consume '('
            let mut items = Vec::new();
            while *pos < tokens.len() && tokens[*pos] != ")" {
                let expr = parse_sexpr_internal(tokens, pos)?;
                items.push(expr);
            }
            if *pos >= tokens.len() {
                return Err("Missing closing parenthesis".to_string());
            }
            *pos += 1; // consume ')'
            Ok(SExpr::List(items))
        }
        ")" => Err("Unexpected ')'".to_string()),
        _ => {
            let atom_str = token.clone();
            *pos += 1;
            Ok(SExpr::Atom(atom_str))
        }
    }
 }
 /// Parse a full string into a single top-level `SExpr`, assuming balanced parentheses.
 pub fn parse_string_to_sexpr(s: &str) -> Result<SExpr, String> {
    let tokens = tokenize(s);
    let mut pos = 0;
    let expr = parse_sexpr_internal(&tokens, &mut pos)?;
    if pos < tokens.len() {
        Err(format!(
            "Extra tokens after parse: {:?}",
            &tokens[pos..]
        ))
    } else {
        Ok(expr)
    }
 }
 /// Convert an S-expression to an **untyped** AST node.
 pub fn sexpr_to_untyped(expr: &SExpr) -> Result<UntypedAst, String> {
    match expr {
        SExpr::Atom(text) => {
            // 1) Try parse as integer
            if let Ok(val) = text.parse::<i32>() {
                Ok(UntypedAst::IntLiteral(val))
            } else {
                // 2) Otherwise interpret as an opcode
                match text.to_uppercase().as_str() {
                    "+" => Ok(UntypedAst::Instruction(OpCode::Plus)),
                    "-" => Ok(UntypedAst::Instruction(OpCode::Minus)),
                    "*" => Ok(UntypedAst::Instruction(OpCode::Mult)),
                    "DUP" => Ok(UntypedAst::Instruction(OpCode::Dup)),
                    "POP" => Ok(UntypedAst::Instruction(OpCode::Pop)),
                    // unknown => treat as Noop
                    _ => Ok(UntypedAst::Instruction(OpCode::Noop)),
                }
            }
        }
        SExpr::List(items) => {
            let mut sub_asts = Vec::new();
            for child in items {
                sub_asts.push(sexpr_to_untyped(child)?);
            }
            Ok(UntypedAst::Sublist(sub_asts))
        }
    }
 }
 // ----------------------------------------------------------------------------
 // (Optional) Placeholder for a future typed AST
 // ----------------------------------------------------------------------------
 // /// In the future, we plan to define a `TypedAst` enum that ensures each operation
 // /// has the correct number of typed children. We might also handle errors
 // /// if an operation expects two integer children, but the user tries to attach
 // /// a sublist or zero children, etc.
 // ///
 // /// For now, the untyped AST suffices for quick prototyping, but typed checks
 // /// will be crucial in more advanced genetic programming or static analysis scenarios.
 // #[derive(Debug, Clone)]
 // pub enum TypedAst {
 //     // e.g. IntLiteral(i32),
 //     //     Instruction(InstructionKind),
 // }
 // #[derive(Debug, Clone)]
 // pub enum InstructionKind {
 //     // e.g. Plus(Box<TypedAst>, Box<TypedAst>),
 //     //     Minus(Box<TypedAst>, Box<TypedAst>),
 //     //     Mult(Box<TypedAst>, Box<TypedAst>),
 //     //     Dup,
 //     //     Pop,
 // }
 // // etc.
@@ -1,2 +0,0 @@
 pub mod ast;
 pub mod push3_describtor;
@@ -1,67 +0,0 @@
 //! src/compiler/push3_descriptor.rs
 //! 
 //! A small module of helper functions to construct or interpret the 256-bit descriptors
 //! used by our on-chain `Push3Interpreter`. Each descriptor encodes a tag, an offset,
 //! a length, and any leftover bits (e.g., immediate data).
 use ethers::types::U256;
 /// The 256-bit descriptor layout is as follows:
 /// [  8 bits: tag  |  32 bits: offset  |  32 bits: length  |  184 bits: leftover ]
 ///
 /// We'll define small helper functions to build or parse these. 
 /// Our `make_sublist_descriptor` is an example for tag=3 (SUBLIST).
 /// Tag constants, if you want them:
 pub const TAG_SUBLIST: u8 = 3;
 pub const TAG_INT_LITERAL: u8 = 2;
 pub const TAG_INSTRUCTION: u8 = 1;
 pub const TAG_NONE: u8 = 0;
 /// A small helper to shift the tag into the top 8 bits.
 #[inline]
 fn tag_bits(tag: u8) -> U256 {
    U256::from(tag) << 248
 }
 /// Build a descriptor for a SUBLIST with the given offset and length (in bytes),
 /// leftover=0. 
 ///
 /// # Example
 /// ```
 /// let desc = make_sublist_descriptor(0, code_bytes.len() as u32);
 /// // pass `desc` into the interpreter's exec stack
 /// ```
 pub fn make_sublist_descriptor(offset: u32, length: u32) -> U256 {
    tag_bits(TAG_SUBLIST as u8)
        | (U256::from(offset) << 216)
        | (U256::from(length) << 184)
        | U256::zero() // leftover
 }
 /// Possibly you want a more general helper that builds any descriptor:
 /// If you have other uses for leftover bits, you can pass that in:
 pub fn make_descriptor(tag: u8, offset: u32, length: u32, leftover: U256) -> U256 {
    tag_bits(tag)
        | (U256::from(offset) << 216)
        | (U256::from(length) << 184)
        | leftover
 }
 /// If you want to parse a descriptor, you can define getTag, getOffset, getLength, etc:
 pub fn get_tag(desc: U256) -> u8 {
    // top 8 bits => shift right 248
    (desc >> 248).as_u32() as u8
 }
 pub fn get_offset(desc: U256) -> u32 {
    ((desc >> 216) & U256::from(u32::MAX)).as_u32()
 }
 pub fn get_length(desc: U256) -> u32 {
    ((desc >> 184) & U256::from(u32::MAX)).as_u32()
 }
 pub fn get_low_184(desc: U256) -> U256 {
    desc & ((U256::from(1u64) << 184) - 1)
 }
@@ -1,79 +0,0 @@
 use rand::Rng;
 use crate::compiler::ast::{UntypedAst, OpCode};
 pub fn random_sublist_ast(rng: &mut impl Rng, max_depth: usize) -> UntypedAst {
    // 1) Choose how many children the top-level `Sublist` will have.
    let len = rng.gen_range(1..=3);
    // 2) Build a vector of sub-ASTs by calling `random_ast` for each child
    let mut children = Vec::with_capacity(len);
    for _ in 0..len {
        // We start at `depth=1` because the top-level sublist itself is `depth=0`.
        children.push(random_ast(rng, 1, max_depth));
    }
    // 3) Return a `Sublist` as the root node
    UntypedAst::Sublist(children)
 }
 /// Generate a random `UntypedAst` by recursively building sub-trees, 
 /// int literals, or instructions. 
 ///
 /// - `depth` tracks how deep we are in the tree.
 /// - `max_depth` is the maximum allowed depth to prevent infinite recursion.
 pub fn random_ast(rng: &mut impl Rng, depth: usize, max_depth: usize) -> UntypedAst {
    if depth >= max_depth {
        // Return something "terminal," 
        // e.g. an IntLiteral or a single Instruction
        random_terminal(rng)
    } else {
        // Weighted choice: 
        // 0 => IntLiteral, 
        // 1 => single Instruction,
        // 2 => Sublist with children
        let choice = rng.gen_range(0..3);
        match choice {
            0 => UntypedAst::IntLiteral(rng.gen_range(-10..10)),
            1 => UntypedAst::Instruction(random_opcode(rng)),
            2 => {
                // Make a sublist with 1..=3 children
                let len = rng.gen_range(1..=3);
                let mut children = Vec::with_capacity(len);
                for _ in 0..len {
                    children.push(random_ast(rng, depth + 1, max_depth));
                }
                UntypedAst::Sublist(children)
            }
            _ => unreachable!(),
        }
    }
 }
 /// Generate a random "terminal" node. 
 /// Typically either an int literal or a single instruction.
 fn random_terminal(rng: &mut impl Rng) -> UntypedAst {
    // Weighted choice:
    // 0 => IntLiteral
    // 1 => single Instruction
    let choice = rng.gen_range(0..2);
    match choice {
        0 => UntypedAst::IntLiteral(rng.gen_range(-10..10)),
        1 => UntypedAst::Instruction(random_opcode(rng)),
        _ => unreachable!(),
    }
 }
 /// Generate a random `OpCode` from your known set of instructions.
 pub fn random_opcode(rng: &mut impl Rng) -> OpCode {
    let choice = rng.gen_range(0..6); 
    // because we have 6 variants: Noop, Plus, Minus, Mult, Dup, Pop
    match choice {
        0 => OpCode::Noop,
        1 => OpCode::Plus,
        2 => OpCode::Minus,
        3 => OpCode::Mult,
        4 => OpCode::Dup,
        5 => OpCode::Pop,
        _ => unreachable!(),
    }
 }
@@ -1,64 +0,0 @@
 use rand::Rng;
 use crate::compiler::ast::{UntypedAst, OpCode};
 use crate::gp::generate::{random_ast, random_opcode};
 /// Returns a new `UntypedAst` that is a mutated version of `original`.
 /// We do not modify `original`; we clone or build new pieces as needed.
 /// 
 /// - `depth`: current depth of this node,
 /// - `max_depth`: max allowed depth (to prevent infinite recursion).
 pub fn mutated_ast(original: &UntypedAst, rng: &mut impl Rng, depth: usize, max_depth: usize) -> UntypedAst {
    // 10% chance: completely replace this node with a fresh random subtree
    if rng.gen_range(0..100) < 10 {
        return random_ast(rng, depth, max_depth);
    }
    match original {
        UntypedAst::IntLiteral(val) => {
            // Another small chance to replace the entire node with random subtree
            if rng.gen_range(0..100) < 10 {
                return random_ast(rng, depth, max_depth);
            }
            // Otherwise, "tweak" the int by a small offset
            let delta = rng.gen_range(-2..=2);
            let new_val = val.saturating_add(delta);
            UntypedAst::IntLiteral(new_val)
        }
        UntypedAst::Instruction(op) => {
            // 10% chance to replace node
            if rng.gen_range(0..100) < 10 {
                return random_ast(rng, depth, max_depth);
            }
            // 50% chance to pick a new opcode
            // or else keep the same
            if rng.gen_bool(0.5) {
                UntypedAst::Instruction(random_opcode(rng))
            } else {
                // Just clone the original
                UntypedAst::Instruction(op.clone())
            }
        }
        UntypedAst::Sublist(children) => {
            // 10% chance to replace this sublist entirely
            if rng.gen_range(0..100) < 10 {
                return random_ast(rng, depth, max_depth);
            }
            // Otherwise, mutate zero or more children
            let mut new_children = children.clone();
            if !new_children.is_empty() {
                // Choose how many kids to mutate: 
                // e.g., 1..=min(2, children.len())
                let mut_count = rng.gen_range(1..=new_children.len().min(2));
                for _ in 0..mut_count {
                    let idx = rng.gen_range(0..new_children.len());
                    new_children[idx] = mutated_ast(&new_children[idx], rng, depth+1, max_depth);
                }
            }
            UntypedAst::Sublist(new_children)
        }
    }
 }
@@ -1,3 +0,0 @@
 pub mod population;
 pub mod genetic_ops;
 pub mod generate;
@@ -1,9 +0,0 @@
 #[derive(Debug, Clone)]
 pub struct Individual {
    pub fitness: f64,
    // your Expr or bytecode or both
 }
 pub struct Population {
    pub individuals: Vec<Individual>,
 }
@@ -1,41 +0,0 @@
 //! src/helpers/artifact.rs
 //! A small helper module to read a Forge artifact JSON and extract the creation code.
 use anyhow::{anyhow, bail, Result};
 use serde::Deserialize;
 use std::fs;
 /// This mirrors the JSON structure: "bytecode": { "object": "...hex..." }
 #[derive(Debug, Deserialize)]
 struct BytecodeObject {
    object: String,
 }
 /// The top-level artifact with a "bytecode" field.
 #[derive(Debug, Deserialize)]
 struct MyContractArtifact {
    bytecode: BytecodeObject,
 }
 /// Reads the given JSON file (a Forge artifact) and returns the raw creation code bytes.
 ///
 /// * `filename`: path to the artifact JSON (e.g. `../onchain/out/Push3Interpreter.sol/Push3Interpreter.json`)
 pub fn get_creation_code(filename: &str) -> Result<Vec<u8>> {
    // 1) Read the JSON file
    let creation_json = fs::read_to_string(filename)
        .map_err(|e| anyhow!("Failed to read JSON file {}: {}", filename, e))?;
    // 2) Parse
    let contract_artifact: MyContractArtifact = serde_json::from_str(&creation_json)
        .map_err(|e| anyhow!("Failed to parse JSON artifact: {}", e))?;
    // 3) Extract the hex code
    let raw_hex = &contract_artifact.bytecode.object;
    let stripped_hex = raw_hex.trim_start_matches("0x");
    // 4) Convert from hex => bytes
    match hex::decode(stripped_hex) {
        Ok(bytes) => Ok(bytes),
        Err(e) => bail!("Invalid hex for creation code: {e}"),
    }
 }
@@ -1 +0,0 @@
 pub mod artifact;
@@ -1,4 +0,0 @@
 pub mod compiler;
 pub mod runner;
 pub mod gp;
 pub mod helpers;
@@ -1,118 +0,0 @@
 // src/main.rs
 use std::env;
 // We’ll use your existing AST definitions for parsing
 use offchain::compiler::ast::{
    parse_string_to_sexpr,
    sexpr_to_untyped,
    Push3Ast, // The trait
    UntypedAst, // The untyped AST enum
 };
 use offchain::runner::revm_runner::{EvmRunner, Push3InterpreterOutputs}; // <--- We import our EvmRunner
 use anyhow::{anyhow, bail, Result};
 use hex;
 use serde::Deserialize; // For JSON artifact loading
 // If you still need these (not strictly required anymore):
 // use database::CacheDB;
 // use revm::{
 //     context::Context,
 //     context_interface::result::{ExecutionResult, Output},
 //     database_interface::EmptyDB,
 //     handler::EthHandler,
 //     primitives::{Bytes, TxKind},
 //     EvmCommit, MainEvm,
 // };
 use ethers::abi::{decode, ParamType};
 use ethers::types::U256;
 // ----------------------------------------------------------------------
 // JSON artifact struct, as before
 // ----------------------------------------------------------------------
 #[derive(Debug, Deserialize)]
 struct BytecodeObject {
    object: String,
 }
 #[derive(Debug, Deserialize)]
 struct MyContractArtifact {
    bytecode: BytecodeObject,
 }
 // ----------------------------------------------------------------------
 // MAIN
 // ----------------------------------------------------------------------
 fn main() -> Result<()> {
    // 1) Read CLI arguments for the Push3 program
    let args: Vec<String> = env::args().collect();
    if args.len() < 2 {
        eprintln!("Usage: cargo run -- '<program>'");
        eprintln!("Example: cargo run -- '((3 5 +) DUP MUL)'");
        std::process::exit(1);
    }
    let program_str = &args[1];
    // 2) Parse the string into an S-expression
    let sexpr = parse_string_to_sexpr(program_str)
        .map_err(|e| anyhow!("Error parsing S-expression: {}", e))?;
    // 3) Convert SExpr => UntypedAst
    let ast: UntypedAst = sexpr_to_untyped(&sexpr)
        .map_err(|e| anyhow!("Error converting to UntypedAst: {}", e))?;
    // 4) Convert UntypedAst => Push3 bytecode (for debugging, so we can see it)
    let bytecode = ast.to_bytecode();
    // 5) Print the resulting AST and bytecode (in hex)
    println!("AST: {:?}", ast);
    println!("Bytecode (hex): 0x{}", hex::encode(&bytecode));
    // ----------------------------------------------------------------------
    // Load the creation code (bytecode) from a JSON artifact
    // ----------------------------------------------------------------------
    let creation_hex_filename = "../onchain/out/Push3Interpreter.sol/Push3Interpreter.json";
    let creation_json = std::fs::read_to_string(creation_hex_filename)
        .map_err(|e| anyhow!("Failed to read JSON file {}: {}", creation_hex_filename, e))?;
    let contract_artifact: MyContractArtifact = serde_json::from_str(&creation_json)
        .map_err(|e| anyhow!("Failed to parse JSON artifact: {}", e))?;
    let raw_hex = &contract_artifact.bytecode.object;
    let stripped_hex = raw_hex.trim_start_matches("0x");
    let creation_bytes = match hex::decode(stripped_hex) {
        Ok(bytes) => bytes,
        Err(e) => bail!("Invalid hex for creation code: {e}"),
    };
    println!(
        "Loaded creation code ({} bytes) from {}",
        creation_bytes.len(),
        creation_hex_filename
    );
    // ----------------------------------------------------------------------
    // 6) Deploy the interpreter in an ephemeral EVM using `EvmRunner`
    // ----------------------------------------------------------------------
    let mut runner = EvmRunner::new(creation_bytes)?;
    println!("Interpreter deployed successfully in ephemeral EVM at: 0x{:x}", runner.interpreter_addr);
    // ----------------------------------------------------------------------
    // 7) Evaluate the AST in our EVM
    // ----------------------------------------------------------------------
    // We'll call `runner.run_ast(&ast)`, which:
    // - Converts AST => push3 code,
    // - Builds a sublist descriptor in the exec stack,
    // - Calls `runInterpreter`,
    // - Returns final stacks in a `Push3InterpreterOutputs`.
    let outputs = runner.run_ast(&ast)?;
    println!("Ran the AST successfully!");
    // 8) Print the final stacks
    println!("Final CODE stack: {:?}", outputs.final_code_stack);
    println!("Final EXEC stack: {:?}", outputs.final_exec_stack);
    println!("Final INT stack: {:?}", outputs.final_int_stack);
    Ok(())
 }
@@ -1 +0,0 @@
 pub mod revm_runner;
@@ -1,232 +0,0 @@
 //! src/evm_integration/revm_runner.rs
 //! 
 //! This module provides a thin wrapper around REVM to deploy a Push3Interpreter
 //! contract, then call its `runInterpreter(...)` function with flexible inputs/outputs,
 //! using the same style (Context::builder(), .modify_tx_chained, etc.) you had in your main.
 use anyhow::{anyhow, bail, Result};
 use ethers::abi::{encode, decode, Token, ParamType};
 use ethers::types::U256;
 use ethers::utils;
 use database::CacheDB;
 use revm::{
    context::Context,
    context::{BlockEnv, TxEnv, CfgEnv},
    context_interface::result::{ExecutionResult, Output},
    database_interface::EmptyDB,
    handler::EthHandler,
    primitives::{Bytes, TxKind}, // 4 generics
    EvmCommit,
    MainEvm,
 };
 // We import your AST definitions so we can call `ast.to_bytecode()`.
 use crate::compiler::ast::{UntypedAst, Push3Ast};
 // If you have a descriptor helper (like make_sublist_descriptor), bring it in:
 use crate::compiler::push3_describtor::make_sublist_descriptor;
 /// The input parameters for `runInterpreter(...)`: four fields (code, codeStack, execStack, intStack).
 pub struct Push3InterpreterInputs {
    pub code: Vec<u8>,
    pub init_code_stack: Vec<U256>,
    pub init_exec_stack: Vec<U256>,
    pub init_int_stack: Vec<i128>,
 }
 /// The outputs from `runInterpreter(...)`: three arrays for code/exec/int stacks.
 pub struct Push3InterpreterOutputs {
    pub final_code_stack: Vec<U256>,
    pub final_exec_stack: Vec<U256>,
    pub final_int_stack: Vec<i128>,
 }
 /// A thin wrapper around REVM, parameterized by the 4 generics (DB, BLOCK, TX, CFG).
 /// - We store the ephemeral EVM instance,
 /// - We store the deployed address of your `Push3Interpreter`,
 /// - We provide `run_interpreter` and `run_ast`.
 pub struct EvmRunner {
    /// The 4-parameter MainEvm:
    ///   DB = CacheDB<EmptyDB>,
    ///   BLOCK = BlockEnv,
    ///   TX = TxEnv,
    ///   CFG = CfgEnv
    pub evm: MainEvm<CacheDB<EmptyDB>, BlockEnv, TxEnv, CfgEnv>,
    /// The address where Push3Interpreter was deployed.
    pub interpreter_addr: revm::primitives::Address,
 }
 impl EvmRunner {
    /// Deploy a new ephemeral EVM with a "Create" transaction for the given `creation_code`.
    ///
    /// This matches your older style of:
    ///  `MainEvm::new(Context::builder()... .with_db(...), EthHandler::default())`
    pub fn new(creation_code: Vec<u8>) -> Result<Self> {
        // 1) Create the EVM using your old style: `Context::builder()...`
        //    Then pass to MainEvm::new(...).
        //    The difference is that we explicitly say MainEvm<DB,BLOCK,TX,CFG>.
        let mut evm = MainEvm::new(
            // a) Prepare context with a chained transaction to CREATE
            Context::builder()
                .modify_tx_chained(|tx| {
                    tx.transact_to = TxKind::Create;
                    tx.data = Bytes::from(creation_code.clone());
                })
                // b) Provide ephemeral DB
                .with_db(CacheDB::<EmptyDB>::default()),
            // c) The EthHandler for block/tx environment logic
            EthHandler::default(),
        );
        // 2) Execute the CREATE transaction
        let creation_result = evm.exec_commit()?;
        let ExecutionResult::Success {
            output: Output::Create(_, Some(deployed_addr)),
            ..
        } = creation_result
        else {
            bail!("Interpreter deployment failed or no address returned: {creation_result:#?}");
        };
        // 3) Return the EvmRunner
        Ok(Self {
            evm,
            interpreter_addr: deployed_addr,
        })
    }
    /// Call `runInterpreter(bytes,uint256[],uint256[],int256[])` on the deployed contract,
    /// returning the final code/exec/int stacks.
    pub fn run_interpreter(
        &mut self,
        inputs: &Push3InterpreterInputs
    ) -> Result<Push3InterpreterOutputs> {
        // 1) Build function selector
        let func_selector = &utils::id("runInterpreter(bytes,uint256[],uint256[],int256[])")[0..4];
        // 2) Convert each field to `ethers::abi::Token`
        let code_token = Token::Bytes(inputs.code.clone());
        let init_code_stack = Token::Array(
            inputs.init_code_stack
                .iter()
                .map(|&u| Token::Uint(u))
                .collect()
        );
        let init_exec_stack = Token::Array(
            inputs.init_exec_stack
                .iter()
                .map(|&u| Token::Uint(u))
                .collect()
        );
        let init_int_stack = Token::Array(
            inputs.init_int_stack
                .iter()
                .map(|&val_i128| {
                    // store i128 as a U256. If you need negative values, do a two’s complement approach.
                    let as_u128 = val_i128 as u128;
                    Token::Int(U256::from(as_u128))
                })
                .collect()
        );
        // 3) Encode
        let encoded_args = encode(&[
            code_token,
            init_code_stack,
            init_exec_stack,
            init_int_stack,
        ]);
        // 4) Build final call data
        let mut call_data = Vec::from(func_selector);
        call_data.extend_from_slice(&encoded_args);
        // 5) Modify the transaction to CALL the deployed interpreter
        self.evm.context.modify_tx(|tx| {
            tx.transact_to = TxKind::Call(self.interpreter_addr);
            tx.data = Bytes::from(call_data);
            tx.nonce = 1; // increment nonce to avoid reuse
        });
        // 6) Execute the call
        let call_result = self.evm.transact()?;
        match &call_result.result {
            ExecutionResult::Success {
                output: Output::Call(return_data),
                ..
            } => {
                // 7) Decode (uint256[], uint256[], int256[])
                let param_types = &[
                    ParamType::Array(Box::new(ParamType::Uint(256))), // finalCodeStack
                    ParamType::Array(Box::new(ParamType::Uint(256))), // finalExecStack
                    ParamType::Array(Box::new(ParamType::Int(256))),  // finalIntStack
                ];
                let decoded = decode(param_types, return_data)
                    .map_err(|e| anyhow!("Failed to decode return data: {e}"))?;
                // parse each array
                let final_code_stack = match &decoded[0] {
                    Token::Array(arr) => arr.iter().filter_map(|t| {
                        if let Token::Uint(u) = t { Some(*u) } else { None }
                    }).collect(),
                    _ => Vec::new(),
                };
                let final_exec_stack = match &decoded[1] {
                    Token::Array(arr) => arr.iter().filter_map(|t| {
                        if let Token::Uint(u) = t { Some(*u) } else { None }
                    }).collect(),
                    _ => Vec::new(),
                };
                let final_int_stack = match &decoded[2] {
                    Token::Array(arr) => arr.iter().filter_map(|t| {
                        if let Token::Int(u256_val) = t {
                            // read only the lower 128 bits => ignoring sign extension
                            let lo = u256_val.low_u128();
                            Some(lo as i128)
                        } else {
                            None
                        }
                    }).collect(),
                    _ => Vec::new(),
                };
                Ok(Push3InterpreterOutputs {
                    final_code_stack,
                    final_exec_stack,
                    final_int_stack,
                })
            }
            ExecutionResult::Revert { gas_used, output } => {
                bail!("Call reverted: gas used={gas_used:?}, output={output:?}")
            }
            other => {
                bail!("Call failed: {other:?}")
            }
        }
    }
    /// A convenience method to run an `UntypedAst`:
    /// - Convert AST => push3 code,
    /// - Build a sublist descriptor in the exec stack,
    /// - Call `run_interpreter`.
    pub fn run_ast(&mut self, ast: &UntypedAst) -> Result<Push3InterpreterOutputs> {
        // 1) Convert AST => push3 bytecode
        let code_bytes = ast.to_bytecode();
        let code_len = code_bytes.len() as u32;
        // 2) Build a sublist descriptor
        let descriptor = make_sublist_descriptor(0, code_len);
        // 3) Put code in `code` and sublist descriptor in `execStack`
        let inputs = Push3InterpreterInputs {
            code: code_bytes,
            init_code_stack: Vec::new(),
            init_exec_stack: vec![descriptor],
            init_int_stack: Vec::new(),
        };
        // 4) Run interpreter
        self.run_interpreter(&inputs)
    }
 }
@@ -0,0 +1,163 @@
 # 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.
Author	SHA1	Message	Date
JulesCrown	e3b6352eb8	tokenomics draft	2024-12-27 15:40:35 +01:00
giteadminandJulesCrown	2a4f01481b	merge interpreter.md into readme (#4 ) Co-authored-by: JulesCrown <admin@noip.localhost> Reviewed-on: http://gitea.loseyourip.com:4000/giteadmin/SoLUSH-3/pulls/4	2024-12-26 10:30:26 +00:00
giteadmin	1079129e48	Merge pull request 'scaffolding' (#1 ) from scaffolding into main reviewed scaffolding	2024-12-24 12:02:50 +00:00
giteadmin	e668fcf9a0	Merge pull request 'interpreter-expansion' (#2 ) from interpreter-expansion into scaffolding reviewed bunch of new int operations	2024-12-24 12:02:08 +00:00
giteadmin	a1890e650b	Merge pull request 'refactor-dirs' (#3 ) from refactor-dirs into interpreter-expansion reviewed logic move to dir	2024-12-24 12:00:57 +00:00