{"id":26465382,"url":"https://github.com/paradigmxyz/ress","last_synced_at":"2025-06-28T05:06:05.981Z","repository":{"id":282308157,"uuid":"904294304","full_name":"paradigmxyz/ress","owner":"paradigmxyz","description":"The implementation of Stateless Ethereum client based on Reth","archived":false,"fork":false,"pushed_at":"2025-04-16T11:46:43.000Z","size":4673,"stargazers_count":161,"open_issues_count":5,"forks_count":17,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-06-27T01:42:41.127Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paradigmxyz.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,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-16T16:01:07.000Z","updated_at":"2025-05-27T07:28:10.000Z","dependencies_parsed_at":"2025-04-15T22:19:03.850Z","dependency_job_id":"305b1542-4fb6-41ba-9af6-074f4a3b733b","html_url":"https://github.com/paradigmxyz/ress","commit_stats":null,"previous_names":["paradigmxyz/ress"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/paradigmxyz/ress","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paradigmxyz%2Fress","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paradigmxyz%2Fress/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paradigmxyz%2Fress/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paradigmxyz%2Fress/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paradigmxyz","download_url":"https://codeload.github.com/paradigmxyz/ress/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paradigmxyz%2Fress/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262376658,"owners_count":23301383,"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":"2025-03-19T10:00:53.570Z","updated_at":"2025-06-28T05:06:05.974Z","avatar_url":"https://github.com/paradigmxyz.png","language":"Rust","funding_links":[],"categories":["Statelessness","Rust"],"sub_categories":[],"readme":"![image](https://github.com/user-attachments/assets/ac01e368-4872-4983-afc0-a7fd218dd342)\n\nSee the [accompanying blog on Paradigm Research](https://www.paradigm.xyz/2025/03/stateless-reth-nodes).\n\n# ress(reth stateless)\n\nRess (shorthand for: Reth Stateless) is a fully validating stateless Ethereum Execution Layer with 14GB disk requirements.\nStateless nodes matter not only for improving Ethereum’s decentralization, but also to scale the L1 gas limit,\nscaling optimistic L2s, and for implementing Native Rollups to improve the L2 ecosystem’s security \u0026 interoperability.\n\n\u003e [!CAUTION]\n\u003e Ress is an experimental software that has not been fully tested in production grade settings.\n\u003e At this moment, we do not recommend using ress nodes in validator setups.\n\n## Run\n\n### Install\n\n```bash\ncargo install --git https://github.com/paradigmxyz/ress ress --locked\n```\n\n### Run Consensus Layer client\n\nSee https://reth.rs/run/mainnet.html#running-the-consensus-layer for the instructions, they're the same as for Reth.\n\nThe only difference is that the default JWT token location is `~/.local/share/ress/NETWORK/jwt.hex`\ninstead of `~/.local/share/reth/NETWORK//jwt.hex`.\n\n### (Optional) Run stateful Reth client\n\nFollow the [instructions](https://reth.rs/run/run-a-node.html) to install Reth.\nStart a node with the `--ress.enable` flag to enable support for `ress` subprotocol.\n\n```bash\nreth --ress.enable\n```\n\n### Run Ress client\n\nWe've hosted several public nodes that you can peer with if you don't have an ability to run a Reth node yourself.\n\n```bash\nress --trusted-peers \\\n    \"enode://04bcda1f0a750ce5fd986187825ffcd7aa1ad3641027f646707c2121443e85ae309e047f228c0067aac382f0c0cab21e91a2852e10b4f7724187b0185bb78b2b@100.126.2.26:30303,\\\n    enode://04e4e548eee6f042685ad0b6793de36a4c5c6a3107cdf54cbfeedbeb0df4138d4c65b534fb700072341098644eb5a6b125e63c36464d8f57c19b6e26ca36ae7c@100.75.245.88:30303,\\\n    enode://2c464310c41c2a9d7be44783d38ab2b8517e4c5133719de1a4b605294cfd201f33b2c5b4158054b171a3ba26837f85a97f6a8553622ea1033d70c98fc1b70fa0@69.67.151.138:30303,\\\n    enode://065cffdc5c824d42c23f933ca615daad8b887f2330b1313e8c1a5d850be93d3b6e95698d4f774bbf7b2639ac6d6d870645156eeb805bd3448107806cc0a6e5f9@69.67.151.138:30303\"\n```\n\nIf you've started a Reth node yourself in the previous step, you can fetch the enode from it\nand use it as an argument to the `--trusted-peers` flag.\n```bash\ncast rpc admin_nodeInfo -r http://localhost:9545 | jq .enode\n```\n\n## How it works\n\nLive sync works like any other stateful node: Ress receives a new payload from the consensus client\nand fetches necessary state data (witness, block, bytecodes) from a stateful reth client\nvia [RLPx subprotocol dedicated to Ress](https://github.com/paradigmxyz/reth/tree/main/crates/ress/protocol).\nIt verifies payload and calculates the new state root all in memory.\n\n```mermaid\nsequenceDiagram\n    CL-\u003e\u003eRess: NewPayload\n    Ress-\u003e\u003eReth: GetWitness\n    Reth--\u003e\u003eRess: Witness\n    Ress-\u003e\u003eReth: GetBytecode\n    Note over Ress,Reth: (only missing)\n    Reth--\u003e\u003eRess: Bytecode\n    Ress-\u003e\u003eRess: Validate Payload\n    Ress--\u003e\u003eCL: PayloadStatus\n```\n\n### Components\n\nTo run a ress node successfully you need the following components:\n1. Ress node (stateless) connected to a Consensus Client\n2. Reth node (stateful) connected to a Consensus Client\n\n```mermaid\nflowchart TB\n    subgraph Stateful[\"Stateful Client Pair\"]\n        SFCL[\"Consensus Layer\"]\n        Reth[\"Reth Node\"]\n        SFCL --\u003e|Engine API| Reth\n    end\n    \n    subgraph Stateless[\"Stateless Client Pair\"]\n        SLCL[\"Consensus Layer\"]\n        Ress[\"Ress Node\"]\n        SLCL --\u003e|Engine API| Ress\n    end\n\n    Ress --\u003e|ress RLPx subprotocol| Reth\n```\n\n## How it was tested\n\n### Hive Tests \n\nRess was tested with [hive](https://github.com/ethereum/hive).\nA simulator sends requests to `adapter`, which proxies `engine/*` request to `ress`, and other requests to `reth`. \n\n- `reth`: auth port(8651), rpc port(8544), subnetwork(30303)\n- `ress`: auth port(8552), rpc port(-), subnetwork(61398)\n\nWe ran the cancun test suite and from the 226 tests, ress passes `206` hive tests successfully:\n```\nMar 13 09:46:28.033 INF simulation ethereum/engine finished suites=1 tests=226 failed=20\n```\n\n### Holesky validators\nFor our proof of concept, we successfully [ran Ress-backed Ethereum validators](https://light-holesky.beaconcha.in/validator/1919380?v=attestations) on Holesky testnet and correctly attested to block validity.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparadigmxyz%2Fress","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparadigmxyz%2Fress","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparadigmxyz%2Fress/lists"}