<p align=center>
<img src="https://avatars.githubusercontent.com/u/90545451?s=200&v=4"/>
</p>
# EVM Storage Layout Extractor
This project is a library that is able to ingest [EVM](https://ethereum.org/en/developers/docs/evm/)
[bytecode](https://ethereum.org/en/developers/docs/evm/opcodes/) and discover an approximate storage
layout for the contract described by that bytecode. It is _not_ intended to be a full decompiler,
but is instead a tool **highly** specialised for performing this discovery process.
See our [announcement](https://blog.smlxl.io/announcing-bytecode-generated-storage-layouts-on-evm-storage-96761758d397) for more details
or check the [deepdive post on our blog.](https://blog.smlxl.io/a-deep-dive-into-our-storage-layout-extractor-51554185d8af)
This discovery process is performed, in broad strokes, as follows:
1. Bytecode is ingested and disassembled into an instruction stream that is amenable to analysis.
This is a sequence of Opcodes that is equivalent to the bytecode.
2. The stream of instructions is executed symbolically on a specialised EVM implementation. This
execution is both **speculative** and **total**, exploring all possible code paths that can
influence the type attributed to a given storage location.
3. For each value seen in the program during execution, the VM builds a **symbolic value** (a little
tree structure) that represents the operations performed to that particular piece of "data".
4. These execution trees are passed to a type inference process. This process starts by _lifting_,
which turns low-level constructs into more-general high-level ones. The results of this are then
fed to _inference rules_ that output **type inference judgements** about the trees they analyse.
Finally, these inferences are combined with a _unifier_ to perform whole-program type inference.
5. The resolved types associated with each storage slot are then turned into a **storage layout**
that describes the type of each storage slot that was encountered.
For more information on the process with specific reference to concrete pieces of code, see the
documentation in [`lib.rs`](src/lib.rs). This also provides a basic usage example for the library,
though more complex ones can be found in the [tests](tests).
## Extending the Library
The primary means of extending this library to get better layouts is by extending the type inference
engine. This is done by either writing new **lifting passes** or **inference rules**, and you can
find more information on this process in the documentation
on [extending the library](./docs/Extending%20the%20Library.md).
## Contributing
If you want to contribute code or documentation (non-code contributions are _always_ welcome) to
this project, please take a look at our [contributing](./docs/CONTRIBUTING.md) documentation. It
provides an overview of how to get up and running, as well as what the contribution process looks
like for the library.
We are also available on our [Telegram group](https://t.me/+zw0fuNoYg39hZWRh) if you have any questions.
Raw data
{
"_id": null,
"home_page": "https://github.com/smlxlio/storage-layout-extractor",
"name": "storage-layout-extractor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ethereum, evm, storage, layout, smart-contracts, bytecode, analysis",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/94/78/91c9dd1633a7703cc8645044ea937f963cba913cf1f16d4b587e95734e24/storage_layout_extractor-0.6.3.tar.gz",
"platform": null,
"description": "<p align=center>\n <img src=\"https://avatars.githubusercontent.com/u/90545451?s=200&v=4\"/>\n</p>\n\n# EVM Storage Layout Extractor\n\nThis project is a library that is able to ingest [EVM](https://ethereum.org/en/developers/docs/evm/)\n[bytecode](https://ethereum.org/en/developers/docs/evm/opcodes/) and discover an approximate storage\nlayout for the contract described by that bytecode. It is _not_ intended to be a full decompiler,\nbut is instead a tool **highly** specialised for performing this discovery process. \n\nSee our [announcement](https://blog.smlxl.io/announcing-bytecode-generated-storage-layouts-on-evm-storage-96761758d397) for more details\nor check the [deepdive post on our blog.](https://blog.smlxl.io/a-deep-dive-into-our-storage-layout-extractor-51554185d8af)\n\nThis discovery process is performed, in broad strokes, as follows:\n\n1. Bytecode is ingested and disassembled into an instruction stream that is amenable to analysis.\n This is a sequence of Opcodes that is equivalent to the bytecode.\n2. The stream of instructions is executed symbolically on a specialised EVM implementation. This\n execution is both **speculative** and **total**, exploring all possible code paths that can\n influence the type attributed to a given storage location.\n3. For each value seen in the program during execution, the VM builds a **symbolic value** (a little\n tree structure) that represents the operations performed to that particular piece of \"data\".\n4. These execution trees are passed to a type inference process. This process starts by _lifting_,\n which turns low-level constructs into more-general high-level ones. The results of this are then\n fed to _inference rules_ that output **type inference judgements** about the trees they analyse.\n Finally, these inferences are combined with a _unifier_ to perform whole-program type inference.\n5. The resolved types associated with each storage slot are then turned into a **storage layout**\n that describes the type of each storage slot that was encountered.\n\nFor more information on the process with specific reference to concrete pieces of code, see the\ndocumentation in [`lib.rs`](src/lib.rs). This also provides a basic usage example for the library,\nthough more complex ones can be found in the [tests](tests).\n\n## Extending the Library\n\nThe primary means of extending this library to get better layouts is by extending the type inference\nengine. This is done by either writing new **lifting passes** or **inference rules**, and you can\nfind more information on this process in the documentation\non [extending the library](./docs/Extending%20the%20Library.md).\n\n## Contributing\n\nIf you want to contribute code or documentation (non-code contributions are _always_ welcome) to\nthis project, please take a look at our [contributing](./docs/CONTRIBUTING.md) documentation. It\nprovides an overview of how to get up and running, as well as what the contribution process looks\nlike for the library. \nWe are also available on our [Telegram group](https://t.me/+zw0fuNoYg39hZWRh) if you have any questions.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Python bindings for storage-layout-extractor - EVM bytecode storage layout analysis",
"version": "0.6.3",
"project_urls": {
"Homepage": "https://github.com/jalbrekt85/storage-layout-extractor-py",
"Issues": "https://github.com/jalbrekt85/storage-layout-extractor-py/issues",
"Repository": "https://github.com/jalbrekt85/storage-layout-extractor-py"
},
"split_keywords": [
"ethereum",
" evm",
" storage",
" layout",
" smart-contracts",
" bytecode",
" analysis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a47b0e143e10195d4c3c5bf87cbf9143285eb715f6d668a5fc7b81e6e2abf020",
"md5": "78d3d73515707c30aca69c4b1785f490",
"sha256": "f4ee5ffb17ebf89875810f84e4cd872e184fed578066ab2cd58e9fdcb32678fc"
},
"downloads": -1,
"filename": "storage_layout_extractor-0.6.3-cp310-cp310-macosx_10_12_x86_64.whl",
"has_sig": false,
"md5_digest": "78d3d73515707c30aca69c4b1785f490",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 604138,
"upload_time": "2025-09-10T05:36:03",
"upload_time_iso_8601": "2025-09-10T05:36:03.105866Z",
"url": "https://files.pythonhosted.org/packages/a4/7b/0e143e10195d4c3c5bf87cbf9143285eb715f6d668a5fc7b81e6e2abf020/storage_layout_extractor-0.6.3-cp310-cp310-macosx_10_12_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "087e4cac060dc5c2233b6c922a92b84021cc97cb9535284c5893cfc7ef75afed",
"md5": "1c3a740956fdd875b08e020ed60d775d",
"sha256": "08d696eba7558c006f146e1cd7a45ff361dd851ce4dbc36d959575f79d403d5c"
},
"downloads": -1,
"filename": "storage_layout_extractor-0.6.3-cp310-cp310-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "1c3a740956fdd875b08e020ed60d775d",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 579863,
"upload_time": "2025-09-10T05:36:04",
"upload_time_iso_8601": "2025-09-10T05:36:04.631404Z",
"url": "https://files.pythonhosted.org/packages/08/7e/4cac060dc5c2233b6c922a92b84021cc97cb9535284c5893cfc7ef75afed/storage_layout_extractor-0.6.3-cp310-cp310-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fc77bcd9dfe2c98cbc56a04c31fb61613dc7f6afec3a8003218642f56a70a662",
"md5": "115d07587805d6e628fbc4ad24a50482",
"sha256": "f6f47c8ee242418738d21d5a30bf5f4c72ed623b52cee58588f8478d505bb0d8"
},
"downloads": -1,
"filename": "storage_layout_extractor-0.6.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "115d07587805d6e628fbc4ad24a50482",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 4026325,
"upload_time": "2025-09-10T05:36:06",
"upload_time_iso_8601": "2025-09-10T05:36:06.360426Z",
"url": "https://files.pythonhosted.org/packages/fc/77/bcd9dfe2c98cbc56a04c31fb61613dc7f6afec3a8003218642f56a70a662/storage_layout_extractor-0.6.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8d3d9426573339aad6feb9b112ef841765438348d6728a0ae1b7bab3bcbc6da3",
"md5": "42209b5b239ffb2869a05a98c61ba6ae",
"sha256": "4760e6330937c220f5156aecbc968b9399a40765afe44c01b1b75a3216179e15"
},
"downloads": -1,
"filename": "storage_layout_extractor-0.6.3-cp310-cp310-win_amd64.whl",
"has_sig": false,
"md5_digest": "42209b5b239ffb2869a05a98c61ba6ae",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 450957,
"upload_time": "2025-09-10T05:36:08",
"upload_time_iso_8601": "2025-09-10T05:36:08.324960Z",
"url": "https://files.pythonhosted.org/packages/8d/3d/9426573339aad6feb9b112ef841765438348d6728a0ae1b7bab3bcbc6da3/storage_layout_extractor-0.6.3-cp310-cp310-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "39ad3bdbea7830a7bb452e3aa1f8181ab3fa16683f80e71cfb5b2a847d273c57",
"md5": "aa28c2e4f454a85461a1d39db9d23545",
"sha256": "1e08afdc2687a1d76a5b1ebef0f1b56ef29eb9d81bb790929112ea3ec7d9ad10"
},
"downloads": -1,
"filename": "storage_layout_extractor-0.6.3-cp311-cp311-macosx_10_12_x86_64.whl",
"has_sig": false,
"md5_digest": "aa28c2e4f454a85461a1d39db9d23545",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 604141,
"upload_time": "2025-09-10T05:36:10",
"upload_time_iso_8601": "2025-09-10T05:36:10.232631Z",
"url": "https://files.pythonhosted.org/packages/39/ad/3bdbea7830a7bb452e3aa1f8181ab3fa16683f80e71cfb5b2a847d273c57/storage_layout_extractor-0.6.3-cp311-cp311-macosx_10_12_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2d086b2018756715adfce634506dedc21414083f2fa5296dc8eb1b3450fe7a0a",
"md5": "734c82c6b56626647843769e5f038957",
"sha256": "860469bb6c9dacefcfa7953c2885c49b558b5812f77a965a25fb8e1824e7a804"
},
"downloads": -1,
"filename": "storage_layout_extractor-0.6.3-cp311-cp311-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "734c82c6b56626647843769e5f038957",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 579864,
"upload_time": "2025-09-10T05:36:11",
"upload_time_iso_8601": "2025-09-10T05:36:11.712723Z",
"url": "https://files.pythonhosted.org/packages/2d/08/6b2018756715adfce634506dedc21414083f2fa5296dc8eb1b3450fe7a0a/storage_layout_extractor-0.6.3-cp311-cp311-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3e2450d3837ab9b45bacb46fef88b44af1cb88d86026c960207eda19430781d8",
"md5": "6e37c67b2884c23b1d0cf2f36a52d4eb",
"sha256": "d40bf552b7bd92b01a812acbd4feb23cbf52bfc0797668e7ed9b5a36850ac52e"
},
"downloads": -1,
"filename": "storage_layout_extractor-0.6.3-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "6e37c67b2884c23b1d0cf2f36a52d4eb",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 4025921,
"upload_time": "2025-09-10T05:36:13",
"upload_time_iso_8601": "2025-09-10T05:36:13.383100Z",
"url": "https://files.pythonhosted.org/packages/3e/24/50d3837ab9b45bacb46fef88b44af1cb88d86026c960207eda19430781d8/storage_layout_extractor-0.6.3-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fa4cac7094c0ed84adeafd643a5cf8c29530f6bd4e7553e29d04127cb9804866",
"md5": "641e324659670a9d6b3c8403d621cc3f",
"sha256": "3fe4d5b858637d8718a766c8597bc46a79680c8b23dd4055848bccf371897c8e"
},
"downloads": -1,
"filename": "storage_layout_extractor-0.6.3-cp311-cp311-win_amd64.whl",
"has_sig": false,
"md5_digest": "641e324659670a9d6b3c8403d621cc3f",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 450961,
"upload_time": "2025-09-10T05:36:15",
"upload_time_iso_8601": "2025-09-10T05:36:15.342482Z",
"url": "https://files.pythonhosted.org/packages/fa/4c/ac7094c0ed84adeafd643a5cf8c29530f6bd4e7553e29d04127cb9804866/storage_layout_extractor-0.6.3-cp311-cp311-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f9211a6357dfd4f7420995b173fec31ce3baf2f7882f968faa52945877287c20",
"md5": "fa7fd934c4f6a7d8f31c233da94d7e2d",
"sha256": "d10e0def72fb75651660891950447a6c28d3618b71dc9f8f9bcf0a64b863602e"
},
"downloads": -1,
"filename": "storage_layout_extractor-0.6.3-cp312-cp312-macosx_10_12_x86_64.whl",
"has_sig": false,
"md5_digest": "fa7fd934c4f6a7d8f31c233da94d7e2d",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 602136,
"upload_time": "2025-09-10T05:36:17",
"upload_time_iso_8601": "2025-09-10T05:36:17.030695Z",
"url": "https://files.pythonhosted.org/packages/f9/21/1a6357dfd4f7420995b173fec31ce3baf2f7882f968faa52945877287c20/storage_layout_extractor-0.6.3-cp312-cp312-macosx_10_12_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ece58a76b6ed41bb41dcdcd0ee452606e2429e250669e1869d1fd2205f857bb9",
"md5": "61835025dfdd7a759a9712893bcd3b90",
"sha256": "c69b9fb973c7064a9040b7ab4905294407c88d4368e8c87dc32cf26258f7489f"
},
"downloads": -1,
"filename": "storage_layout_extractor-0.6.3-cp312-cp312-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "61835025dfdd7a759a9712893bcd3b90",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 578863,
"upload_time": "2025-09-10T05:36:19",
"upload_time_iso_8601": "2025-09-10T05:36:19.410216Z",
"url": "https://files.pythonhosted.org/packages/ec/e5/8a76b6ed41bb41dcdcd0ee452606e2429e250669e1869d1fd2205f857bb9/storage_layout_extractor-0.6.3-cp312-cp312-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "87965af10346ac9df9494d77bcb1fe9277a06835f14f7988a53156f0f35e2075",
"md5": "df87f2a15926f4af57c1357fa37a50ab",
"sha256": "8313291061fd77e78486cf70babce2b832d355a3593d22ca0657265cc1f9965a"
},
"downloads": -1,
"filename": "storage_layout_extractor-0.6.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "df87f2a15926f4af57c1357fa37a50ab",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 4021363,
"upload_time": "2025-09-10T05:36:21",
"upload_time_iso_8601": "2025-09-10T05:36:21.075143Z",
"url": "https://files.pythonhosted.org/packages/87/96/5af10346ac9df9494d77bcb1fe9277a06835f14f7988a53156f0f35e2075/storage_layout_extractor-0.6.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "17e187d94f22114c31e1486d48646c56e8be8ff547b882166d9e7cc3a5f6e661",
"md5": "6aaf6e59681f9242e1099ccbb6dd9a0d",
"sha256": "9eef79fd9c81635b52913d62d17c266baffadae52664a7e6eb1af859510f9a14"
},
"downloads": -1,
"filename": "storage_layout_extractor-0.6.3-cp312-cp312-win_amd64.whl",
"has_sig": false,
"md5_digest": "6aaf6e59681f9242e1099ccbb6dd9a0d",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 450451,
"upload_time": "2025-09-10T05:36:22",
"upload_time_iso_8601": "2025-09-10T05:36:22.657163Z",
"url": "https://files.pythonhosted.org/packages/17/e1/87d94f22114c31e1486d48646c56e8be8ff547b882166d9e7cc3a5f6e661/storage_layout_extractor-0.6.3-cp312-cp312-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "947891c9dd1633a7703cc8645044ea937f963cba913cf1f16d4b587e95734e24",
"md5": "e74242f9dce6f1e33f35a69acfecfdb3",
"sha256": "bf64e54862987df538e40dac57a57c5e39309e06abf0fc5119f03b37a4e86352"
},
"downloads": -1,
"filename": "storage_layout_extractor-0.6.3.tar.gz",
"has_sig": false,
"md5_digest": "e74242f9dce6f1e33f35a69acfecfdb3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 374846,
"upload_time": "2025-09-10T05:36:24",
"upload_time_iso_8601": "2025-09-10T05:36:24.162401Z",
"url": "https://files.pythonhosted.org/packages/94/78/91c9dd1633a7703cc8645044ea937f963cba913cf1f16d4b587e95734e24/storage_layout_extractor-0.6.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-10 05:36:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "smlxlio",
"github_project": "storage-layout-extractor",
"github_not_found": true,
"lcname": "storage-layout-extractor"
}
JSON
