{"id":28495759,"url":"https://github.com/chainbound/taikoscope","last_synced_at":"2025-07-02T10:30:47.948Z","repository":{"id":293667107,"uuid":"972515749","full_name":"chainbound/taikoscope","owner":"chainbound","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-30T10:11:44.000Z","size":3020,"stargazers_count":5,"open_issues_count":30,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-30T10:29:50.175Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://taikoscope.vercel.app","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/chainbound.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,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-25T07:50:59.000Z","updated_at":"2025-06-30T10:08:10.000Z","dependencies_parsed_at":"2025-06-23T10:21:27.922Z","dependency_job_id":null,"html_url":"https://github.com/chainbound/taikoscope","commit_stats":null,"previous_names":["chainbound/taikoscope"],"tags_count":0,"template":false,"template_full_name":"chainbound/rust-template","purl":"pkg:github/chainbound/taikoscope","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainbound%2Ftaikoscope","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainbound%2Ftaikoscope/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainbound%2Ftaikoscope/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainbound%2Ftaikoscope/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chainbound","download_url":"https://codeload.github.com/chainbound/taikoscope/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainbound%2Ftaikoscope/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263120564,"owners_count":23416841,"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-06-08T11:31:21.733Z","updated_at":"2025-07-02T10:30:47.926Z","avatar_url":"https://github.com/chainbound.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Taikoscope 🔭\n\nTaikoscope is a real‑time monitoring and analytics system for the Taiko\nblockchain. It continuously ingests events from Ethereum (L1) and Taiko (L2),\npersists time‑series metrics in ClickHouse and exposes them via a REST API and a\nReact dashboard.\n\n## Table of Contents\n\n1. [Requirements](#requirements)\n2. [Quick Start](#quick-start)\n3. [Environment](#environment)\n4. [Architecture](#architecture)\n5. [Development](#development)\n6. [Deployment](#deployment)\n7. [License](#license)\n\n## Requirements\n\n- [Rust](https://www.rust-lang.org/) (2024 edition)\n- [just](https://github.com/casey/just)\n- A running ClickHouse instance\n- Access to L1 and L2 RPC endpoints\n- Node.js (for the dashboard)\n\n## Quick Start\n\n1. Clone the repository and install dependencies.\n2. Run `just install-dashboard` to fetch dashboard packages.\n3. Copy `dev.env` and adjust the values for your setup or provide your own env\n   file via the `ENV_FILE` variable.\n4. (Optional) Start ClickHouse and the dashboard via Docker Compose:\n\n   ```bash\n   docker compose up\n   ```\n\n5. Start the extractor and API server:\n\n   ```bash\n   just dev         # runs the extractor/driver\n   just dev-api     # runs the HTTP API\n   ```\n\n6. Start the dashboard (optional if not using Docker Compose):\n\n   ```bash\n   just dev-dashboard\n   ```\n\nThe API is now available on `http://localhost:3000` and the dashboard on\n`http://localhost:5173` by default.\n\n## Environment\n\nAll configuration is provided via environment variables. The most relevant\nvariables are shown below. See [`crates/config`](crates/config) for the full\nlist.\n\n```text\nCLICKHOUSE_URL=\u003chttp://localhost:8123\u003e\nCLICKHOUSE_DB=taikoscope\nL1_RPC_URL=\u003cl1-endpoint\u003e\nL2_RPC_URL=\u003cl2-endpoint\u003e\nTAIKO_INBOX_ADDRESS=\u003c0x...\u003e\nTAIKO_PRECONF_WHITELIST_ADDRESS=\u003c0x...\u003e\nTAIKO_WRAPPER_ADDRESS=\u003c0x...\u003e\nAPI_HOST=127.0.0.1\nAPI_PORT=3000\nRATE_LIMIT_MAX_REQUESTS=1000\nRATE_LIMIT_PERIOD_SECS=60\n```\n\nThese variables map to the configuration structs defined in\n[`crates/config`](crates/config) (`ClickhouseOpts`, `RpcOpts`,\n`TaikoAddressOpts`, `ApiOpts` and `InstatusOpts`).\n\n## Architecture\n\nTaikoscope follows a layered architecture that keeps data ingestion and\npresentation concerns separate:\n\n1. **Driver and Extractor** – subscribe to L1 and L2 chains, process events\n   such as block headers and batch submissions, and write them to ClickHouse\n   via the `ClickhouseWriter`.\n2. **Storage** – a ClickHouse database holds tables like\n   `l1_head_events`, `l2_head_events`, `batches` and `proved_batches`. Reads and\n   writes use dedicated reader and writer clients.\n3. **API Server** – an Axum based service exposing 20+ REST endpoints and\n   Server‑Sent Events. `ApiState` manages database access and IP based rate\n   limiting.\n4. **Dashboard** – a React application that fetches metrics using the API\n   service layer and renders them with lazy loaded charts.\n5. **Monitoring** – background monitors trigger incidents via Instatus when\n   thresholds are exceeded.\n\nEvents flow through the system continuously. The driver handles header and\nbatch streams, inserts rows into ClickHouse and the API aggregates this data for\nthe dashboard. The UI now polls the API periodically to update metrics.\n\n## Development\n\nFormatting, linting and tests can be run via `just`:\n\n```bash\njust fmt      # format the code\njust lint     # run clippy\njust lint-dashboard # check dashboard whitespace\njust test     # run the test suite\njust ci       # runs fmt, lint, lint-dashboard and test\n```\n\n## Deployment\n\nDeployment scripts use `ssh` and `docker` to build the images remotely.\nCreate an entry in your `~/.ssh/config` (for example named `taiko`) and then run:\n\n```bash\njust deploy-remote-hekla        # deploy the extractor/driver\njust deploy-api-remote-hekla    # deploy the API server\n```\n\nTo deploy the Hekla dashboard:\n\n```bash\ngit switch hekla\ngit pull --rebase origin main\ngit push origin hekla\n```\n\nVercel automatically builds and deploys the dashboard after the push.\n\n## License\n\nLicensed under the MIT license. See [`LICENSE`](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchainbound%2Ftaikoscope","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchainbound%2Ftaikoscope","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchainbound%2Ftaikoscope/lists"}