Per request from a member of Domain Allocators for Developer Tooling, we are submitting a final report on our work for the Stylus grant.
Project: Stylus Cache Sentinel — automated cache-bid management for Arbitrum Stylus contracts
Questbook — Resubmission: Stylus Sentinel
Delivered a complete, self-hostable automation layer for Arbitrum’s Stylus CacheManager: an indexer that reconstructs cache state from chain history, a CLI for configuration and manual operation, and an autonomous monitor that keeps watched contracts cached without human intervention.
The tool is chain-agnostic by construction — it resolves the chain id and the active CacheManager address from the RPC rather than hardcoding either, so the same build runs on Arbitrum One, Nova, and any Orbit chain with Stylus enabled. It is language-agnostic for the same reason, operating on codehashes rather than contract source, so it manages Rust, C, and C++ Stylus contracts identically.
List of Milestones Delivered
M1: Indexer Core Development + Local Database Setup ($13,000) — 2026-03-27
- Event indexer backfilling CacheManager history from Stylus genesis to head in resumable paged batches, then tailing live events.
- SQLite local database with checkpointing, gap recording, and crash-safe resume.
- Chain and CacheManager address both discovered from the RPC, never hardcoded.
- Result: A complete, self-hosted replica of cache-bid state that resumes correctly after any interruption.
M2: Data Transformation and Database Enhancement ($5,000) — 2026-04-17
- Normalized v2 schema with BLOB keys and foreign-key dimension tables, replacing the v1 hex-text layout.
- Idempotent writes via UNIQUE(tx_hash, log_index) — re-persisting the same logs inserts zero rows.
- reconcile command performing a byte-level comparison of DB-derived state against on-chain getEntries(), exiting non-zero on any drift.
- Result: Verifiable data integrity — the indexer proves its own correctness against chain truth rather than asserting it.
M3: CLI Implementation ($7,000) — 2026-05-29
- Zero-dependency subcommand CLI covering every service: indexer, configuration, watchlist, wallet, inspect, manual bid, and history.
- Validated user configuration, enforced on both write and load.
- Env-only wallet integration — the signing key is read from SENTINEL_PRIVATE_KEY and never persisted to disk. Read-only commands require no wallet at all.
- Cross-platform on Linux, macOS, and Windows across Node 20 and 22, including a native SQLite addon and shell-agnostic npm scripts.
- Result: Full operational control of the system from a single command surface, on every major platform.
M4: Sentinel Monitoring System ($5,000) — 2026-05-29
- Autonomous monitor and bidder with correct decay-inflated bid accounting. CacheManager stores bids in a decay-inflated space; the loop normalizes to msg.value space before comparing against the eviction floor.
- Pure, unit-tested bid decision policy, isolated from chain and database access so it is testable in full.
- Ordered fail-safe stack: per-bid ceiling, per-window spend cap, per-target cooldown, dry-run by default, and halt-on-drift.
- Full audit trail — every decision, dry run, block, and submission is written to a bid_actions table.
- Multi-contract management with bounded read concurrency to stay inside RPC rate limits.
- Result: Contracts stay cached without human intervention, and no configuration path can spend without an explicit --live flag.
M5: System Documentation ($2,500) — 2026-08-20
- Complete documentation set: installation, quickstart, configuration, command reference, architecture, bidding internals, troubleshooting, and deployment.
- CONTRIBUTING.md for development setup and code conventions; README reduced to a landing page.
- JSDoc on every exported symbol plus module headers across src/.
- Both documentation KPIs are measured by scripts rather than asserted: scripts/doc-coverage.js verifies every module header and exported declaration carries a documentation block, and scripts/readability.js scores prose-only Flesch Reading Ease with code fences, tables, and link targets stripped. npm run docs:check runs both and exits non-zero below target.
- Result: 100% inline documentation coverage against an 80% target, and Flesch Reading Ease of 70.5 overall against a 60 target, with every file above the floor.
M6: Mainnet Deployment ($4,000) — 2026-08-20
- End-to-end validation suite exercising the full stack against Arbitrum One: CacheManager resolution, live state reads, backfill and resume over a pinned historical block window, deduplication on re-persist, reconcile drift detection, target resolution by both the indexed and the on-chain-code path, live cache-entry classification, a dry sentinel tick against live targets, and CLI response times — with the milestone timing budgets asserted as test assertions that print each measured value.
- The suite is read-only and dry-run throughout, and deletes SENTINEL_PRIVATE_KEY before importing any module, so no test in it can spend.
- Deployable container image: a three-stage Dockerfile on a digest-pinned Alpine base, running unprivileged and writing only to a mounted volume, with production dependencies pruned of the TypeScript optional peer, better-sqlite3’s bundled sources, and type declarations.
- docker-compose.yml with log rotation, memory and CPU limits, and a healthcheck.
- Liveness infrastructure: a health command reading a heartbeat stamped by run, sync, and backfill, plus an in-process watchdog that exits when progress stalls so a restart policy can recover a wedged loop. Its threshold is derived from the bid receipt timeout so it can never fire while a live bid is awaiting confirmation, and the per-target cooldown reads from the persisted audit trail so it survives those restarts.
- Result: The full stack is validated against Arbitrum One mainnet and ships as a deployable, unprivileged container that recovers itself from a stalled loop.
Total: $36,500 across six milestones, delivered within the 180-day timeline.
Quick Start and Testing
Prerequisites: Node.js 20 or 22, and an Arbitrum RPC endpoint. A private endpoint is recommended — the public one rate-limits a full backfill.
git clone GitHub - SOMMIERSHOP/StylusCacheSentinel · GitHub
cd StylusCacheSentinel
npm ci && npm run build
node dist/index.js config init
node dist/index.js watch add 0xYourStylusProgram --label my-app --max-bid 0.01
node dist/index.js run # dry-run: assesses and logs what it would bid
run simulates unless --live is passed, and bid simulates unless --yes is passed. Every outcome, including dry runs and blocked bids, is recorded to the audit log — inspect it with node dist/index.js history.
As a service:
docker build -t stylus-cache-sentinel:latest .
docker run -d -v sentinel-data:/data \
-e ARB_RPC_URL=“https://your-rpc” \
stylus-cache-sentinel:latest run
Project Resources
- Repository: GitHub - SOMMIERSHOP/StylusCacheSentinel · GitHub
- Documentation: StylusCacheSentinel/docs at main · SOMMIERSHOP/StylusCacheSentinel · GitHub
- Milestone commits: a9e5c0c (M1), 9b22876 (M2), 330932d (M3/M4), 0d58170 (M5/M6)