{"id":13759549,"url":"https://github.com/oguimbal/HyVM","last_synced_at":"2025-05-10T09:33:01.590Z","repository":{"id":60727459,"uuid":"544905089","full_name":"oguimbal/HyVM","owner":"oguimbal","description":"Run arbitrary code on the EVM","archived":false,"fork":false,"pushed_at":"2024-02-21T09:31:07.000Z","size":1630,"stargazers_count":252,"open_issues_count":3,"forks_count":17,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-11-14T07:04:19.656Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Solidity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oguimbal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"publiccode":null,"codemeta":null}},"created_at":"2022-10-03T12:46:59.000Z","updated_at":"2024-11-13T18:12:58.000Z","dependencies_parsed_at":"2024-08-03T13:13:30.375Z","dependency_job_id":null,"html_url":"https://github.com/oguimbal/HyVM","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oguimbal%2FHyVM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oguimbal%2FHyVM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oguimbal%2FHyVM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oguimbal%2FHyVM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oguimbal","download_url":"https://codeload.github.com/oguimbal/HyVM/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224941037,"owners_count":17395813,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-08-03T13:00:55.255Z","updated_at":"2024-11-16T16:31:05.698Z","avatar_url":"https://github.com/oguimbal.png","language":"Solidity","funding_links":[],"categories":["dApps directory","Projects using Huff in the wild"],"sub_categories":["EVM Tools"],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003eHyVM\u003c/h1\u003e\n  \u003cimg height=\"60\" alt=\"logo\" src=\"./static/eth.png\"\u003e\n  \u003cspan style=\"margin: 10px;\"\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;✕\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n  \u003cimg src=\"./static/mass.png\" height=\"60\" /\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch3\u003e...the execution core of \u003ca href=\"https://mass.money\"\u003emass.money\u003c/a\u003e\u003c/h3\u003e\n  \u003cbr\u003e\n  HyVM is an Ethereum Virtual Machine (EVM) Hypervisor written in \u003ca href=\"https://huff.sh/\"\u003eHuff\u003c/a\u003e, allowing the execution of arbitrary EVM Bytecode.\n  \u003cbr\u003e\n  \u003cbr\u003e\n  \u003ch3\u003e 👉 See it in action with \u003ca href=\"https://hyvm.mass.money/\"\u003eHyVM live playground\u003c/a\u003e\u003c/h3\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n\n\n```solidity\nfunction execute() public returns (uint256 result) {\n    // Bytecode for “3 + 4\" and return the result\n    (bool success, bytes memory data) = HyVM.delegatecall(hex”600360040160005260ff6000f3\");\n    result = abi.decode(data, (uint256));\n}\n```\n\n***\n\n## What is a hypervisor?\n\nAccording to [vmware](https://www.vmware.com/topics/glossary/content/hypervisor.html)\n\n\u003e A hypervisor, also known as a virtual machine monitor or VMM, is software that creates and runs virtual machines (VMs). A hypervisor allows one host computer to support multiple guest VMs by virtually sharing its resources, such as memory and processing.\n\nIn our case, the HyVM allows to run an **EVM on top the EVM** and execute [opcodes](https://www.evm.codes/) directly.\n\n## Why?\n\nUsing the HyVM gives a maximum of flexibility, it replaces using specific scripts to interact with external protocols.\nThere is no limit on which interactions that can be created.\nCustom and complex logic with chained calls can be executed by the HyVM opening a lot possibilities.\nRepetitive intructions and common ones could also be called as helper contract if needed.\n\n## How to use the HyVM\n\nThe way to use the HyVM is to use it as a library called with delegatecall.\nAs shown below, a [contract wallet](https://decommas.io/blog/smart-contract-wallets-explained) allows to execute a delegatecall (or several), and thus to call the HyVM. The DApp managing the contract wallet gives the bytecode for the HyVM to execute. For example:\n* Swap multiple assets.\n* Approve \u0026 deposit.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg width=\"600\" alt=\"image\" src=\"./static/hyvmAsLibrary.png\"\u003e\n\u003c/div\u003e\n\n## How it works?\n\n### Calling the HyVM\n\nThe HyVM ingests raw bytecode (as input) via `delegateCall`, then processes the opcodes and executes them.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg width=\"600\" alt=\"image\" src=\"./static/processBytecode.png\"\u003e\n\u003c/div\u003e\n\n### Bytecode processing\n\nA pointer reads an opcode from the bytecode (extracted from calldata), translates it into a HyVM opcode implementation (more details below), executes and moves on to the next opcode.\nThe pointer is stored in memory and updated each time it moves.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg width=\"600\" alt=\"image\" src=\"./static/opcodesReadAndProcess.png\"\u003e\n\u003c/div\u003e\n\nEach opcode is re-implemented to fit the HyVM memory layout and logic.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg width=\"800\" alt=\"image\" src=\"./static/opcodeMemory.png\"\u003e\n\u003c/div\u003e\n\n### Memory Layout\n\nWhen running a smart contract, you have the whole memory available (from 0x00 to infinity).\nHowever, the HyVM needs some memory for its internals.\nThis memory is taken from the 0x00 offset. Every opcode call that accesses memory (ran by the host) will be fixed to skip this reserved memory.\n\nThe HyVM private memory layout is as follows:\n\n- `[0x00-0x20]` 👉 Execution pointer\n- `[0x20-0x220]` 👉 Jump table\n- `[0x220-0x340]` 👉 Memory reserved for debug purposes (see debug-utils.huff)\n- `[0x220-0x460]` **(when contract contract verifier is enabled)** 👉 Memory used to store contract verification call args \u0026 result. nb: It overlaps debug memory (because we dont need them both at the same time)\n\nThus, the actual memory of the host is starting at either 0x340 or 0x460 depending on the chosen configuration.\n\n## Disclaimer on jumpdest validity\n\n⚠️ The HyVM skips `jumpdest` (0x5B) validations that might appear in `push` opcodes values. This is OK if the executed bytecode is well formed (for instance, if you compiled it using `solc` or equivalent). But if you feed broken bytecode to the HyVM, this could lead to some discrepancies between the HyVM and the actual EVM behaviour.  \nThere is an open issue to implement the validation if needed [here](https://github.com/oguimbal/HyVM/issues/16).\n\n## Compatibility\n\nThe HyVM supports `PUSH0`. It possible to execute bytecode compiled with `Shanghai` EVM version.\nAs the HyVM is deployed with the `Paris` EVM version, it will be converted to `PUSH1 0x00` during the execution.\nThis is due to the fact that most chains do not support `PUSH0` yet.\n\n## HyVM / EVM divergence\n\nThe HyVM consistently behaves as if the executed code did not receive any calldata.  \nThe calldata in the delegatecall to the HyVM is the code to be executed.  \nConsequently, there are some opcodes divergence:\n- `calldataload`: pushes 0 on stack\n- `calldatasize`: pushes 0 on stack\n- `calldatacopy`: copies zeros in the specified location\n- `selfdestruct`: reverts to prevent malicious or erroneous selfdestruct\n- `jumpdest`: as mentioned in the disclaimer, there is no check to ensure the validity of the opcode.\n- `codesize`: returns the calldatasize, not the VM size\n- `callcode` will revert : it is deprecated and generally considered unsafe.\n- `codecopy`: copies from the calldata, not the code\n\n## Addresses\n\nDeployed at `0xCBD19f5728BE69c76e14473fFDe478170Be91eEb` on [Polygon](https://polygonscan.com/address/0xCBD19f5728BE69c76e14473fFDe478170Be91eEb)\n\n## Getting Started\n\nYou will need:\n* [Huff](https://docs.huff.sh/get-started/installing/) (`huffc 0.3.2` / `nightly-813b6b683dd214dfca71d49284afd885dd9eef09`)\nThis is the last version with which the HyVM was tested.\nIt is not possible to pin the Huffc version in CI consistently as pre-released versions are pruned and only the 3 newest nightlies are kept.\n* [Foundry/Forge](https://github.com/foundry-rs/foundry)\n\nYou can find `easm`, the basic EVM assembly compiler that is used to compile tests [here](https://github.com/oguimbal/EVM-Assembler).  \nYou can use [pyevmasm](https://github.com/crytic/pyevmasm) to disassemble bytecode.\n\n### How to test\n\nIt is possible to test for different versions of solidity or different EVM versions.\nIt is set to `paris` by default in the `foundry.toml` file but it is also\ncompatible with `shanghai`.\n\n```bash\nforge test\n```\n\n### How to deploy\n\nExample of how to deploy to Polygon:\n\n```bash\nforge script script/Deploy.s.sol --private-key XXXXXXXXXXXXX --chain-id 137 --rpc-url https://polygon-rpc.com --broadcast\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foguimbal%2FHyVM","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foguimbal%2FHyVM","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foguimbal%2FHyVM/lists"}