From 2a4f01481b404bfa79a2d6aa82a8ceb2d0c48b3c Mon Sep 17 00:00:00 2001 From: giteadmin Date: Thu, 26 Dec 2024 10:30:26 +0000 Subject: [PATCH] merge interpreter.md into readme (#4) Co-authored-by: JulesCrown Reviewed-on: http://gitea.loseyourip.com:4000/giteadmin/SoLUSH-3/pulls/4 --- .gitignore | 5 +- ISSUE_TEMPLATE.md | 47 ++++++++++++++++++ Interpreter.md | 124 ---------------------------------------------- README.md | 104 ++++++++++++++++++++++++++++++++++---- 4 files changed, 146 insertions(+), 134 deletions(-) create mode 100644 ISSUE_TEMPLATE.md delete mode 100644 Interpreter.md diff --git a/.gitignore b/.gitignore index c46aa2b..9051360 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,5 @@ onchain/cache/ -onchain/out/ \ No newline at end of file +onchain/out/ +out/ +cache/ +lib/forge-std diff --git a/ISSUE_TEMPLATE.md b/ISSUE_TEMPLATE.md new file mode 100644 index 0000000..ebcc27d --- /dev/null +++ b/ISSUE_TEMPLATE.md @@ -0,0 +1,47 @@ +me: Bounty +about: Bounty +title: '' +labels: bounty +assignees: '' + +--- + +# Bounty + +## Scope + + +- +- +- + +## Deliverables + + +- +- + +## Bounty Owner/Gardener + +<@your github username> as **** + +## Gain for the Role + + +## Roles +bounty gardener: <@your git username> / X DAI +bounty worker: name / share +bounty reviewer: name / share + +## Gardener checklist + +- [ ] I have attached one of the `size-` labels to this bounty + + diff --git a/Interpreter.md b/Interpreter.md deleted file mode 100644 index 3e8fcc4..0000000 --- a/Interpreter.md +++ /dev/null @@ -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! \ No newline at end of file diff --git a/README.md b/README.md index 303f5bb..d12a4e0 100644 --- a/README.md +++ b/README.md @@ -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: - ```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. +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. +### How to contribute + +Check the [Issues](../../../issues) section to find tasks to tackle. + ## 🛠️ Roadmap - **Core Features:**