Robinhood Pools is a standalone observatory for liquidity pools on Robinhood Chain (chain ID 4663). One Python process reads public RPC data, maintains a local SQLite index, serves JSON/SSE APIs, and serves the plain-HTML/CSS/JavaScript terminal and workbench. It does not require another checkout or any private application files.
The service covers reviewed V2, V3-style, Slipstream, and V4 deployments recorded in rhpools.lp_chain. Coverage is deliberately chain-specific: addresses or assumptions from other chains must not be added without review. A V4 manager address identifies the manager, not an individual pool.
Prerequisites:
Clone and run the standalone repository:
git clone https://github.com/wock9000/robinhoodpools.git
cd robinhoodpools
uv sync --locked --extra test
uv run rhpoolsOpen http://127.0.0.1:8196/. The default RPC is Robinhood Chain's official public endpoint, and the SQLite index is kept under ~/.local/share/rhpools. No credential or private companion repository is needed for the default run.
Useful overrides are explicit CLI flags:
uv run rhpools \
--host 127.0.0.1 \
--port 8196 \
--rpc-url https://rpc.mainnet.chain.robinhood.com \
--data-dir ~/.local/share/rhpools \
--database ~/.local/share/rhpools/lp_market.sqlite \
--history-days 30 \
--disk-reserve-gib 4Run uv run rhpools --help for the installed command's complete option list. --public-origin may be repeated to authorize an additional browser origin for protected POST requests. Keep the listener on loopback unless you have separately designed authentication, TLS, proxy limits, and host-level access control.
The equivalent environment settings are RHP_HTTP_HOST, RHP_HTTP_PORT, RHP_RPC_URL, RHP_DATA_DIR, RHP_DATABASE, LP_HISTORY_DAYS, and LP_DISK_RESERVE_GIB. Additional origins and preparation of supported direct-pool transactions require explicit CLI flags; there is no environment switch that silently enables preparation.
--sample-retention-days / LP_SAMPLE_RETENTION_DAYS (default 35, 0 disables) bounds the raw per-event price and V2 reserve samples. A background thread prunes older samples in small batches, keeping each pool's first sample and its newest one before the cutoff; lookups older than the cutoff read the canonical events the samples came from, so API answers and accounting are unchanged. Deleted rows go to SQLite's freelist and are reused before the file grows. See .audit/design/prune/PRUNE.md.
Token-gated features (wallet sign-in, API keys, the keyed /api/v1/stream) are configured by three settings: --gate-owner / RHP_GATE_OWNER pins the EOA whose EIP-712 signature is the only way to change the policy; --gate-rpc-url / RHP_GATE_RPC_URL (default http://127.0.0.1:8547) is the JSON-RPC endpoint the balance oracle reads balanceOf from; --gate-db / RHP_GATE_DB (default <data-dir>/gate.sqlite) holds credentials, grace anchors, policy versions and the audit log. With the owner unset or no policy applied, every gated feature refuses and the anonymous site is unchanged. The systemd unit ships these lines commented out.
Trading, liquidity management and flow tags add two settings. RHP_TX_FEE_RECIPIENT receives the 75 bps fee on holder trades; unset, /api/tx/status reports trading disabled and no quote is served. RHP_LISTENER_DSN is an optional read-only Postgres DSN for relay-listener observations (install the listener extra for psycopg); without it, PONS and FOMO tags come from chain data alone. Tags are cached in <data-dir>/tags.sqlite for 7 days.
The owner applies a policy from the terminal's wallet dialog (eth_signTypedData_v4) or from the host with the same signature:
uv run rhpools-gate policy typed-data policy.json > typed.json
cast wallet sign --data --from-file typed.json --ledger
uv run rhpools-gate policy apply policy.json --signature 0x…
uv run rhpools-gate audit --limit 20
uv run rhpools-gate keys revoke --key-id 5c1d9b2e0a7f43aapolicy.json is {"version", "token", "decimals", "threshold": {"trade","lp","api","flags"}, "grace_s", "issued_at"} with raw-unit thresholds as decimal strings; version must increase and issued_at must be within 600 s of the apply time. The API contract for keys and the stream is in docs/PUBLIC_API.md.
A successful request to / establishes only that the HTTP process can serve the installed UI. Index progress and source coverage are separate; inspect /api/lp/status and its observed head, indexed head, lag, history coverage, and provider status before treating results as current. During startup, catch-up, provider failure, or a chain reorganization, the server can remain available while indexed data is incomplete or stale.
curl -fsS http://127.0.0.1:8196/ >/dev/null
curl -fsS http://127.0.0.1:8196/api/lp/statusStores created by earlier releases can still carry indexes no query reads (events_owner_time_idx, events_custody_time_idx, lp_accounting_effects_position_tx, lp_accounting_episodes_owner_count_window). SQLite reads every page of an index to drop it, which can take minutes on a large cold store, so startup never does it. After this release has opened the store once, stop the service and run uv run rhpools --drop-legacy-indexes with the same --data-dir/--database. The command refuses while an indexer holds the store, commits each drop separately, and can be rerun after an interruption. Freed pages go to SQLite's freelist for reuse; the file does not shrink.
The default service observes and simulates; it never signs or broadcasts a transaction. Transaction preparation is disabled unless --enable-transaction-prepare is supplied. Enabling it permits generation of unsigned direct-pool remove and collect transaction data for independent inspection and external signing; it does not enable server signing or broadcasting. Add-liquidity execution through MiniRouter2 0x5295e633dfb504298d4a1896ba0738acb6c89e6a is retired because that deployment is unsafe, and the service rejects both new add requests and preparation from old add or approval quotes. Revoke any remaining token allowances to that router independently. Never give this process, its browser UI, configuration, or repository a seed phrase or private key.
RPC credentials, when needed, belong only in local mode-0600 files containing one URL per line. Point a capability-specific variable such as LP_RPC_STATE_URL_FILES or LP_RPC_TRACE_URL_FILES at the file; LP_RPC_HEAD_URL_FILES, LP_RPC_HISTORY_STATE_URL_FILES, LP_RPC_LOG_URL_FILES, and LP_RPC_RECEIPT_URL_FILES follow the same convention. Generic runtime RPC files use RHP_RPC_URL_FILES. Do not put credential-bearing URLs in CLI arguments, browser storage, committed environment files, fixtures, screenshots, or logs.
One running rhpools process owns a database. Do not point concurrent processes at the same SQLite file, inspect it with write-capable tools while the service is running, or use a live database in tests. Stop the owner before backup or migration work and copy the database together with its SQLite sidecar files when they exist.
The service writer builds pools_token0_id_idx and pools_token1_id_idx on its first upgraded start. On a copy of 482,847 live pool rows, the indexes took 2.42 and 1.78 seconds to build and occupied 51.84 and 51.89 MiB. The migration then drops the two superseded token-only indexes.
Results represent the service's indexed evidence and declared coverage, not guaranteed global truth. Unknown accounting stays null; consumers must not turn missing evidence into zero. USDG-denominated values are quote values, not an assertion that USDG equals fiat USD. Units and partial-history coverage are part of the API contract and must remain visible to consumers.
The versioned public API is described in docs/PUBLIC_API.md, with the machine-readable schema served at /api/v1/openapi.json. The browser also uses /api/lp/* and /api/workbench/* routes; these remain same-process client routes rather than a reason to expose RPC credentials to JavaScript.
src/rhpools/lp_server.py— installedrhpoolsCLI, process lifecycle, HTTP, static assets, and route boundariessrc/rhpools/lp_gate.py,lp_gate_siwe.py,lp_gate_ws.py,lp_gate_cli.py— holder gate: owner-signed policy, balance oracle, SIWE sign-in, one credential type, keyed streams,rhpools-gateCLIsrc/rhpools/lp_chain.py— side-effect-free chain ID and reviewed public deployment registrysrc/rhpools/lp_rpc.py— runtime RPC source selection and capability handlingsrc/rhpools/lp_market_protocols.py— protocol decoding and pool identity rulessrc/rhpools/lp_market_index.py— chain ingestion, catch-up, live activity, and reorganization handlingsrc/rhpools/lp_market_store.py— SQLite schema, migrations, cursors, and stored queriessrc/rhpools/lp_market_accounting.py— derived position and episode accountingsrc/rhpools/lp_market_service.py— indexed market query orchestrationsrc/rhpools/lp_public_api.py— versioned public pool and asset APIsrc/rhpools/lp_allocation.py— read-only allocation previewssrc/rhpools/workbench_market.pyandworkbench_actions.py— pool detail, simulation, and optional unsigned preparationsrc/rhpools/lp_research.pyandlp_fomo_flow.py— research and public flow viewssrc/rhpools/static/— framework-free browser UItests/— deterministic pytest coveragedocs/— public API, provenance, RPC operations, and research semantics
See CONTRIBUTING.md before changing contracts or persisted data.
Copyright 2026 RobinhoodPools contributors. Licensed under AGPL-3.0-only; see LICENSE and third-party notices. The software is provided without warranty.
If you modify the application and let users interact with it over a network, offer those users the corresponding source of your modified version as required by section 13. Preserve the visible source links and update them to your fork when deploying a modified version.
The public source is https://github.com/wock9000/robinhoodpools. Software licensing does not grant rights to external data services, trademarks, credentials, or unrelated private applications. This is independent community tooling, not an official Robinhood or Uniswap product.