{"id":38969097,"url":"https://github.com/eqlabs/zksync-state-reconstruct","last_synced_at":"2026-01-17T16:35:54.580Z","repository":{"id":196976173,"uuid":"696225942","full_name":"eqlabs/zksync-state-reconstruct","owner":"eqlabs","description":"Tool to reconstruct zkSync state from commit blocks published on L1","archived":false,"fork":false,"pushed_at":"2024-08-22T13:43:29.000Z","size":395,"stargazers_count":15,"open_issues_count":9,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-08-09T19:36:44.273Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eqlabs.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}},"created_at":"2023-09-25T10:46:56.000Z","updated_at":"2025-07-06T11:38:11.000Z","dependencies_parsed_at":"2023-10-02T12:22:06.057Z","dependency_job_id":"84b34955-7706-4eea-a8e3-168eebf57289","html_url":"https://github.com/eqlabs/zksync-state-reconstruct","commit_stats":null,"previous_names":["eqlabs/zksync-state-reconstruct"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/eqlabs/zksync-state-reconstruct","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eqlabs%2Fzksync-state-reconstruct","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eqlabs%2Fzksync-state-reconstruct/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eqlabs%2Fzksync-state-reconstruct/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eqlabs%2Fzksync-state-reconstruct/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eqlabs","download_url":"https://codeload.github.com/eqlabs/zksync-state-reconstruct/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eqlabs%2Fzksync-state-reconstruct/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28511868,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-01-17T16:35:53.954Z","updated_at":"2026-01-17T16:35:54.568Z","avatar_url":"https://github.com/eqlabs.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zkSync State Reconstruction Tool\n\n\u003e Tool to reconstruct zkSync state from commit blocks published on L1.\n\n## Table of contents\n\n\u003c!--toc:start--\u003e\n- [zkSync State Reconstruction Tool](#zksync-state-reconstruction-tool)\n  - [Prerequisites \u0026 setup](#prerequisites--setup)\n  - [Usage](#usage)\n    - [Reconstruction](#reconstruction)\n    - [Snapshots](#snapshots)\n      - [Generating snapshots](#generating-snapshots)\n      - [Importing snapshots](#importing-snapshots)\n    - [Additional commands](#additional-commands)\n\u003c!--toc:end--\u003e\n\n## Prerequisites \u0026 setup\n\nCurrently there are three ways to setup the environment: using the provided Nix flake, the container image, or installing the dependencies manually.\n\n\u003cdetails\u003e\n\u003csummary\u003eNix Flake (Linux only)\u003c/summary\u003e\n\nTo use the supplied Nix development environment you need to have Nix installed. This can be done by following the official instructions \u003ca href=\"https://nixos.org/download.html\"\u003ehere\u003c/a\u003e.   \u003cbr\u003e\u003cbr\u003e\n\nOnce Nix is installed, the development environment can be activated via the following command:\n\n```nix\nnix develop --experimental-features 'nix-command flakes'\n```\n\nIf you instead want to permanently enable the experimental flakes feature, you can do so by following the instructions detailed \u003ca href=\"https://nixos.wiki/wiki/Flakes\"\u003ehere\u003c/a\u003e. The environment can then be activated via:\n\n```nix\nnix develop\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eContainer Image\u003c/summary\u003e\nTo build the container image, use:\n\u003cbr\u003e\u003cbr\u003e\n\n```fish\npodman build -t state-reconstruction:latest .\n```\n\nAnd, to run it with `podman`, please use:\n\n```fish\npodman run -it state-reconstruction:latest\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eManually\u003c/summary\u003e\nThis tool is written in nightly Rust; you can install Rust by following the official instructions \u003ca href=\"https://www.rust-lang.org/learn/get-started\"\u003ehere\u003c/a\u003e, and then running the following command to switch to the nightly toolchain:\n\u003cbr\u003e\u003cbr\u003e\n\n```fish\nrustup toolchain install nightly\n```\n\nYou also need to have `protobuf`, version `3.20` or above, installed and accessible via `PATH`. Use your preferred package manager to do this. For example, using brew:\n\n```fish\nbrew install protobuf\n```\n\n\u003c/details\u003e\n\n\u003e [!IMPORTANT]\n\u003e It is highly recommend to override the maximum number of open file descriptors. Without doing so you may eventually run into an error, halting progress. On Unix machines this can be done by using `ulimit` along with the `-n` argument:\n\u003e\n\u003e ```fish\n\u003e ulimit -n 8192\n\u003e ```\n\n## Usage\n\n### Reconstruction\n\nTo start reconstructing the state, run the following command with any valid HTTP/HTTPS Ethereum JSON-RPC endpoint, for example using `https://eth.llamarpc.com`:\n\n```fish\ncargo run --release -- reconstruct l1 --http-url https://eth.llamarpc.com\n```\n\nOnce the tool is running it will continuously output the state reconstruction progress in the following format:\n\n```fish\n2024-01-02T13:29:45.351733Z  INFO No existing database found, starting from genesis...\n2024-01-02T13:29:46.028250Z  INFO PROGRESS: [ 0%] CUR BLOCK L1: 16627460 L2: 0 TOTAL BLOCKS PROCESSED L1: 0 L2: 0\n2024-01-02T13:29:56.030022Z  INFO PROGRESS: [ 0%] CUR BLOCK L1: 16636036 L2: 11 TOTAL BLOCKS PROCESSED L1: 8451 L2: 11\n2024-01-02T13:30:06.031946Z  INFO PROGRESS: [ 0%] CUR BLOCK L1: 16644868 L2: 27 TOTAL BLOCKS PROCESSED L1: 16378 L2: 27\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eMetrics reference\u003c/summary\u003e\n\n- `CUR BLOCK`: The last block height that was processed.\n- `TOTAL BLOCKS PROCESSED`: The total number of blocks that has been processed since starting.\n\n\u003c/details\u003e\n\nOn each block insert, the tool will compare the new state root hash with that published on L1. Should they differ, the tool will panic. You can then use the `query` command to get additional information, as such:\n\n```fish\ncargo run --release -- query root-hash\n\nBatch: \u003cBATCH NUMBER where hash deviated\u003e\nRoot Hash: \u003cROOT HASH of the local state tree\u003e\n```\n\n### Snapshots\n\nAdditionally, the state reconstruction tool provides ways to interact with the upcoming [zkSync Era](https://github.com/matter-labs/zksync-era) snapshot system.\n\n#### Generating snapshots\n\nBefore being able to generate snapshots, it is necessary to first fetch the data from L1 and process it. This can be done by running the following command which will also show progress similarly to when reconstructing state from L1.\n\n```fish\ncargo run --release -- prepare-snapshot --http-url https://eth.llamarpc.com\n```\n\nOnce the tool has gathered a number of storage logs, snapshots can then be exported by using the following command, specifying where to export the snapshot directory to.\n\n```fish\ncargo run --release -- export-snapshot \u003cDIRECTORY\u003e\n```\n\n#### Importing snapshots\n\nSnapshots can also be imported directly to use as a base when reconstructing the state from L1. This can be done by using the `--snapshot \u003cDIRECTORY\u003e` argument when starting reconstruction, like so:\n\n\u003e [!WARNING]\n\u003e Importing a snapshot when reconstruction has progressed further than the snapshot has the same effect as truncating the reconstructed state to that of the snapshot.\n\n```fish\ncargo run --release -- reconstruct --snapshot \u003cDIRECTORY\u003e l1 --http-url \u003cHTTP-URL\u003e\n```\n\n### Additional commands\n\nTo view all available options, you can use the `help` command:\n\n```fish\ncargo run --release -- --help\n\nzkSync state reconstruction tool\n\nUsage: state-reconstruct \u003cCOMMAND\u003e\n\nCommands:\n  download          Download L2 state from L1 to JSON file\n  reconstruct       Reconstruct L2 state from a source\n  query             Query the local storage, and optionally, return a JSON-payload of the data\n  prepare-snapshot\n  export-snapshot\n  help              Print this message or the help of the given subcommand(s)\n\nOptions:\n  -h, --help     Print help\n  -V, --version  Print version\n```\n\nYou can also view all the options for the subcommands in a similar fashion:\n\n```fish\ncargo run --release -- reconstruct --help\n\nReconstruct L2 state from a source\n\nUsage: state-reconstruct reconstruct [OPTIONS] \u003cCOMMAND\u003e\n\nCommands:\n  l1    Fetch data from L1\n  file  Fetch data from a file\n  help  Print this message or the help of the given subcommand(s)\n\nOptions:\n  -d, --db-path \u003cDB_PATH\u003e    The path to the storage solution [env: ZK_SYNC_DB_PATH=]\n      --snapshot \u003cSNAPSHOT\u003e  If present, try to restore state from snapshot files contained in the specified directory. Note that this will only work when supplied with a fresh database\n  -h, --help                 Print help\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feqlabs%2Fzksync-state-reconstruct","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feqlabs%2Fzksync-state-reconstruct","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feqlabs%2Fzksync-state-reconstruct/lists"}