{"id":15634232,"url":"https://github.com/leonardoalt/yools","last_synced_at":"2025-06-20T23:08:08.879Z","repository":{"id":59674355,"uuid":"521596466","full_name":"leonardoalt/yools","owner":"leonardoalt","description":"Tools for Yul.","archived":false,"fork":false,"pushed_at":"2023-03-29T09:46:54.000Z","size":456,"stargazers_count":138,"open_issues_count":7,"forks_count":6,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-06-20T23:07:28.223Z","etag":null,"topics":["ethereum","evm","formal-verification","hacktoberfest","solidity","yul"],"latest_commit_sha":null,"homepage":"","language":"SMT","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leonardoalt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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-08-05T10:29:38.000Z","updated_at":"2025-02-06T14:43:06.000Z","dependencies_parsed_at":"2024-10-23T02:50:43.957Z","dependency_job_id":null,"html_url":"https://github.com/leonardoalt/yools","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/leonardoalt/yools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardoalt%2Fyools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardoalt%2Fyools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardoalt%2Fyools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardoalt%2Fyools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leonardoalt","download_url":"https://codeload.github.com/leonardoalt/yools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardoalt%2Fyools/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261032097,"owners_count":23100050,"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":["ethereum","evm","formal-verification","hacktoberfest","solidity","yul"],"created_at":"2024-10-03T10:53:04.453Z","updated_at":"2025-06-20T23:08:03.866Z","avatar_url":"https://github.com/leonardoalt.png","language":"SMT","funding_links":[],"categories":[],"sub_categories":[],"readme":"# yools - tools for Yul\n\nYools is [so far] an experimental symbolic execution engine for Yul.\nIt translates Yul programs into sets of SMT constraints and queries\nan SMT solver to detect reachability of a certain program state.\nCurrently the only user facing approach is to detect whether a program\nmay revert or not.\n\n## What's supported\n\nNOT THAT MUCH PLEASE BE PATIENT\n\nYul's entire syntax is supported, but not all EVM builtin functions are.\nThe SMT encoding follows the usual BMC-style unrolling of loops up to a\ncertain constant bound which can be chosen by the user. This means that\nresults are not always sound in the presence of loops, and in such case\nresults are always under the assumption that loops do not iterate over\nthe given bound.\n\n## Usage\n\nCurrently there is one subcommand `symbolic` which contains the available\nfeatures.\n\n```bash\n$ yools symbolic --help\nyools-symbolic\nSymbolically execute Yul programs checking for revert reachability\n\nUSAGE:\n    yools symbolic [OPTIONS] --input \u003cFILE.yul\u003e\n\nOPTIONS:\n    -h, --help                         Print help information\n    -i, --input \u003cFILE.yul\u003e             Yul source file\n    -l, --loop-unroll \u003cLOOP_UNROLL\u003e    Loop unrolling limit [default: 10]\n    -s, --solver \u003cSOLVER\u003e              SMT solver [default: cvc5]\n```\n\nToy example:\n\n```yul\n// switch.yul\n{\n\tlet t := 0\n\tswitch calldataload(0)\n\tcase 0 { t := add(t, 10) }\n\tcase 1 { t := add(t, 10) }\n\tcase 2 { t := add(t, 10) }\n\tdefault { t := add(t, 10) }\n\n\tif iszero(eq(t, 10)) { revert(0, 0) }\n}\n```\n\n```bash\n$ yools symbolic -i switch.yul\nAll reverts are unreachable.\n```\n\n## Why this\n\nMost Formal Verification tools for Ethereum smart contracts focus on EVM\nbytecode, understandably.  A few others target Solidity source code. Verifying\nYul instead has some particular advantages over the 2 approaches:\n\n- Writing and maintaining a tool for Yul is much easier than Solidity\ndue to the high level and complex types and language changes. The Yul\nto EVM compiler is also much simpler, so much less trust is required\nin the compiler.\n- Yul has a lot more structured information than EVM bytecode, such as\nfunctions, loops, ifs, switches, structured storage access for state\nvariables, structured ABI encoding/decoding and much more. This makes\nit much easier to reason about the code and prove/disprove statements.\nTools that reason about bytecode try to infer and lift all this information\nup from the bytecode to a higher level, but this process is not always\nsuccessful and requires extra effort.\n\nOf course the approach used here also has disadvantages over the 2:\n\n- Solidity has even more structured information and thus can be used\nto find contract invariants more easily, for example.\n- Analysing bytecode means there is no compiler involved from that point\nto deployment, so what you verify is what's deployed.\n\nAll approaches are valuable and can/should be used together.\n\n## Features\n\nPlease check the open issues to see what features are still not supported\nor are planned.\n\n## Research\n\nOne of the goals of this project is to allow for highly customizable semantics\nwhen generating the SMT constraints that represent the program. For example,\nthere are different ways to represent calldata, memory, and storage symbolically.\nIt is hard to tell in advance which might be better, and ultimately that can be\nalso highly dependent on the analyzed Yul program as well. It is important\nto experiment with different approaches, and this is what we want to achieve.\n\nA few potential directions are given below:\n\n### Calldata/Memory/Storage encoding\n\nThere are many different ways one may want to encode these memory regions\nsymbolically. For example, storage is often encoded as an SMT Array from BV256\nto BV256, which is convenient given that `SLOAD` and `STORE` always handle\nentire words. Memory, however, requires different handling due to single bytes\nbeing read/written. We would like to eventually experiment with different\napproaches to encode the 3 memory regions.\n\n\n### Function/loop summaries\n\nTODO\n\n### ABI encoding/decoding abstraction\n\nTODO\n\n### Parallelism\n\nTODO\n\n### State variable abstraction\n\nTODO\n\n### Revert data abstraction\n\nTODO\n\n### External calls\n\nTODO\n\n## Contributing\n\nIf you're interested in contributing please reach out! There are lots of\nexciting thing to do in different levels of Rust/SMT/Yul.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonardoalt%2Fyools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleonardoalt%2Fyools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonardoalt%2Fyools/lists"}