{"id":24202580,"url":"https://github.com/xersky/genesisvm","last_synced_at":"2026-06-11T07:31:32.143Z","repository":{"id":213341626,"uuid":"733274425","full_name":"xersky/GenesisVM","owner":"xersky","description":"My first implementation of a virtual machine using Java, the GenesisVM. Running opcodes/instructions and interpreting bytecode with the flexibility to insert mnemonics and return the result.","archived":false,"fork":false,"pushed_at":"2024-02-19T02:43:26.000Z","size":64,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-03T11:19:24.864Z","etag":null,"topics":["java","memory","mnemonic","opcodes","stack","state","virtual-machine","vm"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xersky.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-12-19T00:44:59.000Z","updated_at":"2024-02-19T02:52:45.000Z","dependencies_parsed_at":"2024-02-19T02:32:11.155Z","dependency_job_id":null,"html_url":"https://github.com/xersky/GenesisVM","commit_stats":null,"previous_names":["xersky/genesisvm"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/xersky/GenesisVM","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xersky%2FGenesisVM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xersky%2FGenesisVM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xersky%2FGenesisVM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xersky%2FGenesisVM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xersky","download_url":"https://codeload.github.com/xersky/GenesisVM/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xersky%2FGenesisVM/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34188272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","memory","mnemonic","opcodes","stack","state","virtual-machine","vm"],"created_at":"2025-01-13T21:48:21.055Z","updated_at":"2026-06-11T07:31:32.113Z","avatar_url":"https://github.com/xersky.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GenesisVM\n\nAn implementation of a Virtual Machine using Java.\nThe virtual machine is capable of running instructions and interpreting bytecode. It also provides the flexibility to insert mnemonics and return the result accordingly.\n\n## Instruction Mnemonics\n\nThe virtual machine supports the following instructions, categorized by their functionality:\n\n```java\npublic enum Instruction {\n    PUSH(0x00),\n    POP(0x01),\n    ADD(0x02),\n    MUL(0x03),\n    DIV(0x04),\n    SUB(0x05),\n    POW(0x06),\n    MOD(0x07),\n    RETURN(0x08),\n    STOP(0x09),\n    JUMP(0x0A),\n    CJUMP(0x0B),\n    LOAD(0x0C),\n    STORE(0x0D),\n    DUP(0x0E),\n    SWAP(0x0F),\n    GT(0x10),\n    LT(0x11),\n    EQ(0x12),\n    LHS(0x13),\n    RHS(0x14),\n    NEG(0x15),\n    AND(0x16),\n    OR(0x17),\n    XOR(0x18),\n    JUMPDEST(0x19),\n    NOT(0x1A),\n    EXEC(0x1B),\n    SLOAD(0x1C),\n    SSTORE(0x1D);\n    \n    // ... (implementation details)\n}\n```\n\n### Arithmetic Operations\n`ADD`, `MUL`, `DIV`, `SUB`, `POW`, `MOD`, `NEG`\n\n### Comparison Operations\n`GT`, `LT`, `EQ`\n\n### Bitwise Operations\n`AND`, `OR`, `XOR`, `NOT`, `LHS`, `RHS`\n\n### Stack Manipulation\n`PUSH`, `POP`, `DUP`, `SWAP`\n\n### Control Flow\n`RETURN`, `STOP`, `JUMP`, `CJUMP`, `JUMPDEST`\n\n### Memory Operations\n`LOAD`, `STORE`\n\n### State Storage and Retrieval\n`SLOAD`, `SSTORE`\n\n### Special Operations\n`EXEC`\n\n\n\n## Features\n\n**Bytecode Interpretation**: \nThe virtual machine can interpret bytecode and execute the specified instructions.\n\n```java\nVirtualMachine vm = new VirtualMachine();\nbyte[] bytecode = {\n    00,00,00,00,0x17,   // PUSH 23\n    00,00,00,00,03,     // PUSH 3\n    03,                 // MUL\n    0x08,               // RETURN\n    };\n\nOptional\u003cInteger\u003e result = vm.byteInterpreter(bytecode); // result of 23 * 3 should be 69\n\nif (result.isPresent()) {\n    System.out.println(\"Result: \" + result.get()); // Result: 69\n} else {\n    System.out.println(\"No Result!\");\n}\n```\n\n**Mnemonics Execution**:\nIn addition to bytecode, the virtual machine allows you to use mnemonics for a more human-readable input.\n\n```java\n// 1 int is 4 bytes, so the representation of 23 is 00 00 00 17\nString mnemonics = \"PUSH 00 00 00 17 PUSH 00 00 00 03 MUL RETURN\" ;\n\nbyte[] bytecodeFromMnemonics = vm.mnemonicsToByteCode(mnemonics); //converting from mnemonics to bytecode\n\nOptional\u003cInteger\u003e resultFromMnemonics = vm.byteInterpreter(bytecodeFromMnemonics); // interpretating our bytecode\n\nif (resultFromMnemonics.isPresent()) {\n    System.out.println(\"Result: \" + resultFromMnemonics.get()); // Result: 69\n} else {\n    System.out.println(\"No Result!\");\n}\n```\n**Memory Operations**: \nThe virtual machine supports operations like loading and storing values in memory.\n\n**Control Flow**: \nJump and conditional jump instructions allow for control flow manipulation with a jump destination instruction for safety.\n\n**State Persistence**: \nThe state of the virtual machine, including memory, can be persisted to JSON files (`State.json`).\n\n**Dynamic Code Execution**:\nUtilize the `EXEC` instruction to execute bytecode identified by a hash stored in the `Database.json` file.\n\n`Database.json`:\n```json\n{\"23\":\"0x000000000100000000020208\",\"69\":\"0x000000000100000000020309\",\"1546833\":\"0x09\"}\n```\nWe will try to execute the bytecode with the `23` key hash value (Pushing 1 and 2 to the stack then adding them and returning the reesult)\n```java\n    VirtualMachine vm = new VirtualMachine();\n\n    // Specify the bytecode hash from the database\n    int bytecodeHashInt = 23; // We will try to execute the bytecode with the 23 key hash value\n\n    byte[] bytecodeHash = ByteBuffer.allocate(4).putInt(bytecodeHashInt).array(); // Converting from int to an array of bytes\n\n    // Creating a bytecode snippet from mnemonics using the EXEC instruction then converting it to bytecode\n    String mnemonics = \"EXEC \" +  vm.byteToString(bytecodeHash, 0, 4).trim() + \" RETURN\";\n    System.out.println(\"Bytecode representation to execute: \" + mnemonics);\n    \n    byte[] bytecodeFromDatabase = vm.mnemonicsToByteCode(mnemonics);\n\n    // Executing the bytecode from the database and printing its result\n    System.out.println(vm.byteInterpreter(bytecodeFromDatabase)); // should be 3\n```\nThe result:\n\n![exec test](exec.png)\n\n## Code Structure\nThe project is organized into three main classes:\n\n`Instruction`: Enum representing the supported instructions with their corresponding byte values.\n\n`VirtualMachine:` The core virtual machine class responsible for bytecode interpretation and execution.\n \n`State`: Represents the state of the virtual machine, including the stack and memory.\n\n\n## Fun Manipulation\n\nWe can test random algorithms using our VM by providing mnemonics or direct bytecode.\n\nSo let's try to make a test algorithm that returns `69` if the last two args of the stack are equal, and returns `23` if otherwise.\n\n```java\n    // testing if the last two elements of the stack are equal (in that case below if 7 == 7)\n    String ifMnemonics = \"PUSH 00 00 00 07 PUSH 00 00 00 00 STORE PUSH 00 00 00 00 LOAD PUSH 00 00 00 07 EQ PUSH 00 00 00 28 CJUMP PUSH 00 00 00 17 PUSH 00 00 00 2E JUMP JUMPDEST PUSH 00 00 00 45 JUMPDEST RETURN\";\n\n    System.out.println(vm.byteInterpreter(vm.mnemonicsToByteCode(ifMnemonics))); // Should return 69\n```\n\nThe result:\n\n![result 69](result69.png)\n\n```java\n    // the same thing (but in this case comparing 3 with 7)\n    String ifMnemonics = \"PUSH 00 00 00 03 PUSH 00 00 00 00 STORE PUSH 00 00 00 00 LOAD PUSH 00 00 00 07 EQ PUSH 00 00 00 28 CJUMP PUSH 00 00 00 17 PUSH 00 00 00 2E JUMP JUMPDEST PUSH 00 00 00 45 JUMPDEST RETURN\";\n\n    System.out.println(vm.byteInterpreter(vm.mnemonicsToByteCode(ifMnemonics))); // Should return 23\n```\n\nThe result:\n\n![result 23](result23.png)\n\n\n\nNow to elevate the fun, I wrote and tested a set of bytecode instructions manually to execute an algorithm that returns the summation of 11 ( ∑ 11 )\n\n```java\n        VirtualMachine vm = new VirtualMachine();\n        byte[] summationOfElevenByteArray = {\n            //push 11\n            00,00,00,00,0x0B,\n            //push 1\n            00,00,00,00,01,\n            //store 00 01\n            00,00,00,00,01,\n            0x0D,\n            //store 00 00\n            00,00,00,00,00,\n            0x0D,\n            //push 0\n            00,00,00,00,00,\n            //push 1\n            00,00,00,00,01,\n            //store 00 03\n            00,00,00,00,03,\n            0x0D,\n            //store 00 02\n            00,00,00,00,02,\n            0x0D,\n            //load 00 02 -starting the loop\n            0x19,\n            00,00,00,00,02,\n            0x0C,\n            //load 00 03\n            00,00,00,00,03,\n            0x0C,\n            //add\n            02,\n            //store 00 02\n            00,00,00,00,02,\n            0x0D,\n            //load 00 03\n            00,00,00,00,03,\n            0x0C,\n            //push 1\n            00,00,00,00,01,\n            //add\n            02,\n            //store 00 03\n            00,00,00,00,03,\n            0x0D,\n            //load 00 03\n            00,00,00,00,03,\n            0x0C,\n            //load 00 00,\n            00,00,00,00,00,\n            0x0C,\n            //eq\n            0x12,\n            0x1A,\n            00,00,00,00,0x2C,\n            //cjump - conditional jump to loop\n            0x0B,\n            //load 00 02\n            00,00,00,00,02,\n            0x0C,\n            //load 00 00\n            00,00,00,00,00,\n            0x0C,\n            //add - last argument\n            02,\n            //return\n            0x08 \n\n        };\n\n        System.out.println(vm.byteInterpreter(summationOfTwentyThreeByteArray)); // should return 66\n```\n\nThe result of the interpretation and VM execution (66):\n\n```PUSH\nPUSH\nPUSH\nSTORE\nPUSH\nSTORE\nPUSH\nPUSH\nPUSH\nSTORE\nPUSH\nSTORE\nJUMPDEST\nPUSH\nLOAD\nPUSH\nLOAD\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nLOAD\nEQ\nNOT\nPUSH\nCJUMP\n44\nPUSH\nLOAD\nPUSH\nLOAD\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nLOAD\nEQ\nNOT\nPUSH\nCJUMP\n44\nPUSH\nLOAD\nPUSH\nLOAD\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nLOAD\nEQ\nNOT\nPUSH\nCJUMP\n44\nPUSH\nLOAD\nPUSH\nLOAD\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nLOAD\nEQ\nNOT\nPUSH\nCJUMP\n44\nPUSH\nLOAD\nPUSH\nLOAD\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nLOAD\nEQ\nNOT\nPUSH\nCJUMP\n44\nPUSH\nLOAD\nPUSH\nLOAD\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nLOAD\nEQ\nNOT\nPUSH\nCJUMP\n44\nPUSH\nLOAD\nPUSH\nLOAD\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nLOAD\nEQ\nNOT\nPUSH\nCJUMP\n44\nPUSH\nLOAD\nPUSH\nLOAD\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nLOAD\nEQ\nNOT\nPUSH\nCJUMP\n44\nPUSH\nLOAD\nPUSH\nLOAD\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nLOAD\nEQ\nNOT\nPUSH\nCJUMP\n44\nPUSH\nLOAD\nPUSH\nLOAD\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nADD\nPUSH\nSTORE\nPUSH\nLOAD\nPUSH\nLOAD\nEQ\nNOT\nPUSH\nCJUMP\nPUSH\nLOAD\nPUSH\nLOAD\nADD\nRETURN\nOptional[66]\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxersky%2Fgenesisvm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxersky%2Fgenesisvm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxersky%2Fgenesisvm/lists"}