0xhamssog / pons-token-scanner

# Pons Token Scanner
Real-time Pons token discovery and market-state indexing on Robinhood Chain.
This repository is a read-only discovery/indexing system.
It does not custody funds or execute trades.
## What It Does
The scanner watches the Pons launch factories on Robinhood Chain (chain id 4663). It backfills historical launches, follows new ones over WebSocket or HTTP polling, normalizes V1 and V2 into one token model, stores curve trades from the events that actually settled, and exposes that state over a REST API.
When a token matches the configured filters it is marked `ELIGIBLE`. That state is a record and, optionally, a webhook. The process never signs or sends a transaction.
## Architecture
 [code] 
 [code] 
V1 and V2 stay behind adapters. The rest of the application uses normalized launches, phases, and trades.
## Pons V1 / V2
Pons V2 is the current launch protocol: a token is created, traded on its own bonding curve, swept, and graduated into a Uniswap v4 pool. The factory used here is `0x7eD598BcEf8bd9Edd8C97A195C6d13f40801EC7e`. Event and read ABIs follow the current V2 builder docs at docs.ponsfamily.com/v2. Curve trade amounts are taken from `CurveBuy` and `CurveSell`, not from the quantity a caller requested.
V2 market phase is read from `getLaunchedToken` on the factory:
| Contract phase | Scanner phase | Meaning |
| --- | --- | --- |
| 0 NotGraduated | `CURVE` | Still trading on the bonding curve |
| 1 Swept | `SWEPT` | Curve closed, pool not created yet |
| 2 PoolCreated | `POOL` | Trading on the Uniswap v4 pool |
| 3 Rescued | `RESCUED` | Recovery path |
A V2 pool does not have its own contract address. The scanner stores a derived Uniswap v4 pool id when the launch record supplies fee, tick spacing, and the configured hook. `quoteReserve`, `realQuoteReserve`, `tokenReserve`, and `sellableTokens` are raw curve reads. The spot ratio is labeled display-only. It is not an executable quote and it is not a USD price.
Pons V1 is a separate factory (`0xA5aAb3F0c6EeadF30Ef1D3Eb997108E976351feB`). Its `TokenLaunched` event creates a Uniswap V3 pool immediately and does not emit V2 curve events. The V1 adapter decodes that event and reads `getLaunchedToken`. It does not invent curve reserves.
`LaunchGraduationRescued` is recognized by its verified topic so reconciliation can refresh contract state. Its argument names are not in the official V2 docs, so those fields are not decoded into domain data.
## Features
- Resumable historical backfill in configurable block chunks
- WebSocket live listener, with HTTP polling when `WS_URL` is empty
- Reconnect overlap and idempotent replay
- V1 and V2 protocol adapters
- Token identity as `chainId + address`
- Event identity as `chainId + transactionHash + logIndex`
- ERC-20 and Pons metadata, best-effort
- V2 curve buys, sells, refunds, completion, and factory sweep/graduation events
- Filter engine and opportunity states `DETECTED`, `WATCHING`, `ELIGIBLE`, `REJECTED`, `EXPIRED`
- Optional webhook