{"id":47937074,"url":"https://github.com/vicnaum/shinode","last_synced_at":"2026-04-04T07:45:48.920Z","repository":{"id":332960932,"uuid":"1135685266","full_name":"vicnaum/shinode","owner":"vicnaum","description":"Lightweight Ethereum history node — syncs headers, receipts \u0026 logs from P2P, serves eth_getLogs RPC. No EVM, no state trie. Full mainnet in ~6h.","archived":false,"fork":false,"pushed_at":"2026-03-11T14:41:51.000Z","size":17282,"stargazers_count":56,"open_issues_count":4,"forks_count":4,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-04T07:45:37.442Z","etag":null,"topics":["blockchain","devp2p","eth-logs","ethereum","history-node","indexer","p2p","reth","rpc","rust"],"latest_commit_sha":null,"homepage":"https://shinode.rs/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vicnaum.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-16T12:55:35.000Z","updated_at":"2026-03-22T17:15:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vicnaum/shinode","commit_stats":null,"previous_names":["vicnaum/stateless-history-node","vicnaum/shinode"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/vicnaum/shinode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicnaum%2Fshinode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicnaum%2Fshinode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicnaum%2Fshinode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicnaum%2Fshinode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vicnaum","download_url":"https://codeload.github.com/vicnaum/shinode/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicnaum%2Fshinode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31392187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T04:26:24.776Z","status":"ssl_error","status_checked_at":"2026-04-04T04:23:34.147Z","response_time":60,"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":["blockchain","devp2p","eth-logs","ethereum","history-node","indexer","p2p","reth","rpc","rust"],"created_at":"2026-04-04T07:45:46.741Z","updated_at":"2026-04-04T07:45:48.911Z","avatar_url":"https://github.com/vicnaum.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SHiNode (Stateless History Node)\n\n````\n   ▄████████    ▄█    █▄     ▄█  ███▄▄▄▄    ▄██████▄  ████████▄     ▄████████ \n  ███    ███   ███    ███   ███  ███▀▀▀██▄ ███    ███ ███   ▀███   ███    ███ \n  ███    █▀    ███    ███   ███▌ ███   ███ ███    ███ ███    ███   ███    █▀  \n  ███         ▄███▄▄▄▄███▄▄ ███▌ ███   ███ ███    ███ ███    ███  ▄███▄▄▄     \n▀███████████ ▀▀███▀▀▀▀███▀  ███▌ ███   ███ ███    ███ ███    ███ ▀▀███▀▀▀     \n         ███   ███    ███   ███  ███   ███ ███    ███ ███    ███   ███    █▄  \n   ▄█    ███   ███    ███   ███  ███   ███ ███    ███ ███   ▄███   ███    ███ \n ▄████████▀    ███    █▀    █▀    ▀█   █▀   ▀██████▀  ████████▀    ██████████ \n\n       \\/|\\/                                                    ▝▄     ▖ ▄▄▞▝\n       \\\\|//               STATELESS HISTORY NODE              ▝▄  ▖  ▗▘▄▄▄▄▖\n        \\|/                                                      ▄▞ ▗▞▘   ▐  \n        \\|/   |                                                ▀▀  ▀▘    ▄▘  \n     |   |   \\|/         \n────\\|/──|───\\|/─────────────────────────────────────────────────────────────\n````\n\nA lightweight Ethereum history node that syncs headers, transactions, receipts, and logs directly from the P2P network and serves them via JSON-RPC.\n\nThink of it as an **alternative to running a full node** when all you need is event logs for indexing.\n\n[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE-MIT)\n[![Rust](https://img.shields.io/badge/rust-1.82+-orange.svg)](https://www.rust-lang.org/)\n[![Ethereum](https://img.shields.io/badge/network-ETH%20Mainnet-627eea.svg)](https://ethereum.org/)\n[![Status](https://img.shields.io/badge/status-beta-yellow.svg)](ROADMAP.md)\n[![Built with AI](https://img.shields.io/badge/built%20with-Cursor%20%7C%20Claude%20%7C%20Codex-blueviolet.svg)](https://cursor.com/)\n\n\u003e **100% AI-coded.** Every line of code, documentation, and infrastructure in this project was written by AI (Cursor, Claude, Codex).\n\u003e\n\u003e Don't use in production until this is fully tested and reviewed!\n\n![SHiNode Demo](shinode_960.gif)\n\n### Why SHiNode?\n\nRunning a full Ethereum node just to index events is expensive — terabytes of state, constant maintenance through forks, and slow sync times. Paying for RPC providers costs even more. SHiNode gives you a **free, local, unlimited RPC** for event indexing without any of that.\n\n- **Fast sync** — over 1,000 blocks/sec. Full Mainnet history in ~6 hours on modern hardware with SSD, under a day even on older machines or HDDs\n- **Small disk footprint** — full Mainnet sync is under 800 GB with transactions, or ~250 GB for events only\n- **Runs on anything** — low CPU, low memory, works on HDDs. A Mac Mini, a Hetzner VPS, or that old PC in the closet\n- **Partial sync** — start from any block. Only need Uniswap V3? Start from its deployment block (default start is block 10M — Uniswap V2 deployment)\n- **Indexer-compatible** — plug in [rindexer](https://github.com/joshstevens19/rindexer), [Ponder](https://ponder.sh) (event-only mode), or any indexer that uses `eth_getLogs`\n- **Zero maintenance** — no EVM upgrades, no fork management, no pruning. Just run it\n- **Free local RPC** — no rate limits, no API keys, no monthly bills. Your data, on your machine\n\n### Known Limitations\n\n- **Ethereum Mainnet only** — L2s don't expose receipts over P2P yet. Hoping that changes\n- **No verification yet** — data is fetched from P2P peers without proof validation. Planned: receipt hash verification, and optional CL node for full integrity\n- **History may thin out** — with EIP-4444 and The Purge, historical P2P data isn't guaranteed forever. Planned: [era1](https://github.com/ethereum/go-ethereum/pull/26621) archive and [Portal Network](https://www.ethportal.net/) support\n- **Ponder: event-only mode** — Ponder works for pure event indexing (no `readContract` calls). If your indexing functions use `context.client.readContract()`, you'll need a full node for `eth_call` (or Ress stateless execution or full-RPC forwarding - both of which are planned)\n- **No SHiNode-to-SHiNode sync yet** — planned: sync sealed shards between nodes via P2P, torrents, or HTTP archives\n\n### What It Can Do\n\n- **Sync ETH Mainnet** — any block range from the Ethereum P2P network — no RPC provider needed, no beacon node required\n- **Follow the chain head** — stay synced with new blocks and handle reorgs automatically\n- **Serve event logs** — `eth_getLogs` with filtering by block range, address, and topics\n- **Serve block data** — `eth_getBlockByNumber` with transaction hashes\n- **Run indefinitely** — graceful shutdown, restart-safe checkpoints, resumes where it left off\n- **Visualize progress** — fullscreen TUI dashboard with sync speed, coverage map, and real-time stats\n\n### What It Cannot Do\n\n**By design (stateless architecture):**\n- **No `eth_call`** — requires EVM execution and state trie, which we intentionally don't maintain\n- **No traces** — same reason, requires execution\n- **No state queries** — balances, storage, contract reads all require state\n\n**Not yet implemented:**\n- **`eth_getBlockByHash`** — planned\n- **Transaction receipts endpoints** — `eth_getTransactionReceipt`, `eth_getBlockReceipts` are planned\n- **WebSocket subscriptions** — polling only for now\n- **Calldata storage** — we store all transaction fields except `input` data (to save space); planned as optional\n- **Prometheus/OpenTelemetry metrics** — planned\n\n### Current Status (v0.3.0)\n\nCore sync and RPC functionality is **stable and usable for testing indexing workloads**.\n\nSHiNode should be able to sync tens of millions of blocks and serve `eth_getLogs` queries reliably.\n\nSee [ROADMAP.md](ROADMAP.md) for detailed version history and planned features.\n\n## Philosophy\n\n![Splash Screen](splash.png)\n\n- **Stateless by design**: no EVM execution or state trie. No caring about EVM upgrades and forks.\n- **Small, auditable surface**: minimal persistence and RPC for indexers.\n- **Reuse Reth primitives**: networking, static-file storage, and safety defaults.\n\n## Quick Start\n\n### Option 1: Download a binary\n\nGrab a pre-built binary from the [latest release](https://github.com/vicnaum/shinode/releases/latest) (Linux x86_64, macOS ARM, macOS x86_64).\n\n```bash\n# Make it executable and run\nchmod +x shinode\n./shinode\n```\n\n### Option 2: Install from source\n\nRequires Rust and a C toolchain. On Ubuntu/Debian: `apt install build-essential`. See [prerequisites](docs/getting-started.md#prerequisites) for details.\n\n```bash\n# Install directly (builds from source)\ncargo install --git https://github.com/vicnaum/shinode.git --path node\n\n# Then run from anywhere\nshinode\n```\n\n### Option 3: Clone and build\n\n```bash\ngit clone https://github.com/vicnaum/shinode.git\ncd shinode\ncargo build --release\n\n# Run (syncs from block 10M to head)\ncargo run --release\n\n# Custom range\ncargo run --release -- --start-block 18000000 --end-block 18100000\n\n# Disable TUI (use legacy progress bars)\ncargo run --release -- --no-tui\n```\n\nStop with Ctrl+C. The node persists checkpoints and resumes on restart.\n\nFor detailed setup, see [docs/getting-started.md](docs/getting-started.md).\n\n## Documentation\n\n- [Getting Started](docs/getting-started.md) - Installation and first run\n- [Configuration](docs/configuration.md) - Full CLI options reference\n- [Architecture](docs/architecture.md) - System overview and design\n- [Roadmap](ROADMAP.md) - Current and planned features\n- [UI Designs](docs/UI_DESIGNS.md) - TUI dashboard design reference\n\n## CLI Options (Common)\n\n```\n--start-block \u003cu64\u003e     First block to sync (default: 10_000_000)\n--end-block \u003cu64\u003e       Optional final block to stop at\n--data-dir \u003cpath\u003e       Data directory (default: data)\n--rpc-bind \u003cip:port\u003e    RPC bind address (default: 127.0.0.1:8545)\n--shard-size \u003cu64\u003e      Blocks per shard (default: 10_000, for slow HDDs use 1_000)\n--rollback-window \u003cu64\u003e Max reorg depth (default: 64)\n--min-peers \u003cu64\u003e       Wait for N peers before sync (default: 1)\n--no-tui                Disable fullscreen TUI dashboard\n-v/-vv/-vvv             Verbosity levels\n--defer-compaction       Skip inline compaction during sync (good for slow HDDs)\n--repair                Repair storage (run as subcommand)\n--log                   Enable all log artifacts\n--log-resources         Include CPU/memory/disk metrics\n```\n\nSubcommands:\n\n```\ndb stats                Print storage statistics\ndb compact              Compact all dirty shards and seal completed ones\n  --log-json            Write JSON logs to file for debugging\n  -v/-vv/-vvv           Verbosity (info/debug/trace)\ndb rebuild-cache        Rebuild sealed shard cache for faster startup\n```\n\nExample: debug slow compaction on USB HDD:\n\n```bash\ncargo run --release -- \\\n  db compact --log-json compact.jsonl -v\n```\n\nThe JSON log includes per-shard timing breakdown (WAL index, segment I/O, fsync, swap, cleanup).\n\nSee [docs/configuration.md](docs/configuration.md) for all options.\n\n## TUI Dashboard\n\n![TUI](tui.png)\n\nThe node features a fullscreen terminal dashboard (powered by ratatui) that shows:\n\n- **Phase indicator**: Startup \u003e Sync \u003e Retry \u003e Compact \u003e Seal \u003e Follow\n- **Progress bar** with percentage and block counts\n- **Blocks coverage map** using braille characters with color gradient\n- **Speed chart** with 1-minute history, current/average/peak speeds, and ETA\n- **Network panel**: peer visualization (active/idle/stale dots), chain head\n- **Queue panel**: remaining/inflight/retry block counts\n- **Storage panel**: per-segment size breakdown, total size, write rate\n- **DB panel**: block/transaction/log counts, shard compaction status\n- **RPC panel** (follow mode): request rates, method counters, errors\n- **Log viewer**: real-time log entries with level coloring\n\nPress `q` to quit. Use `--no-tui` for headless environments.\n\n## Debugging\n\nSend `SIGUSR1` to print sync + peer-health debug dump:\n\n```bash\nkill -USR1 \u003cpid\u003e\n```\n\n## RPC Support\n\nImplemented:\n- `eth_chainId`\n- `eth_blockNumber`\n- `eth_getBlockByNumber` (with `includeTransactions=false`)\n- `eth_getLogs` (filtered by block range, address, topic0)\n\nNotes:\n- `totalDifficulty` is mocked to `0x0`.\n- `withdrawals` are always `null` (not stored).\n- All other methods return `-32601`.\n\n## Project Layout\n\n```\nnode/           Stateless history node implementation\n  src/\n    bin/        Main binary\n    cli/        CLI and config\n    run/        Orchestration (startup, sync, cleanup)\n    p2p/        devp2p networking\n    sync/       Sync pipeline and scheduling\n    storage/    Sharded static-file storage\n    rpc/        JSON-RPC server\n    ui/         TUI dashboard and progress bars\n    logging/    JSON logs, reports, metrics\ndocs/           User-facing documentation\n  spec/         Research docs and development history\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvicnaum%2Fshinode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvicnaum%2Fshinode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvicnaum%2Fshinode/lists"}