Detection

The Detector (src/detector/index.ts) is the front of the pipeline. Its job is to learn about a pump.fun → PumpSwap graduation as fast as possible, confirm it is real, and emit exactly one graduation event per token — no duplicates, no false positives.

Feeds

The detector can run several feeds in parallel for redundancy. Each feed is a source of candidate graduation notifications; the detector merges them.

Feed	Source file	Cost	Default	Notes
PumpPortal	`src/detector/pumpportal.ts`	Free	On	WebSocket migration feed; the default primary source.
Helius WS	`src/detector/heliusWs.ts`	Free (API key)	Optional	`logsSubscribe` redundancy against PumpPortal.
Yellowstone gRPC	`src/detector/grpcStream.ts`	Paid	Off	Low-latency Geyser stream via the optional `@triton-one/yellowstone-grpc` client. Additive to the free feeds; self-disables (falling back to them) if the endpoint, token, or dependency is missing.

Enabling gRPC (plug-and-play)

The gRPC feed is a drop-in latency upgrade, not a prerequisite. It is purely additive — the detector always runs it alongside PumpPortal + Helius WS and keeps whichever sees a graduation first — so it can never regress the free path. After buying a paid Helius/LaserStream plan:

Set rpc.primaryGrpc (and the token env named by rpc.primaryGrpcTokenEnvVar).
Set detector.grpcEnabled: true.
Restart. npm install already pulls the optional @triton-one/yellowstone-grpc dependency.

If any of those are absent the feed logs an actionable note, reports unhealthy once, and the free feeds carry detection unchanged — enabling it is always safe.

Feed toggles, reconnect behavior, and the dedupe window are set under the detector section of config.yaml.

Deduplication

Because multiple feeds may report the same graduation, src/detector/dedupe.ts keeps a rolling window (about 5 minutes) so the same token is only processed once, regardless of which feed saw it first. The fastest feed wins; the others are suppressed.

On-chain confirmation

A feed notification alone is not trusted. The detector confirms the graduation on-chain before emitting, so downstream stages only ever see real, settled migrations. Confirmed graduations are persisted to the graduations table.

Latency tracking

src/detector/latency.ts records detection latency (how long from the on-chain event to the bot acting), exposed as percentiles on the dashboard. This is how you tell whether your feed mix and RPC are fast enough for the sub-second exit design to be meaningful — if detection is slow, everything downstream is already behind.

Stream health

The detector emits streamHealth events. If feeds go stale or disconnect, the RiskManager can trip a STREAM_DOWN breaker that blocks new entries until connectivity recovers — you should not be opening positions blind.

Output

The detector emits a single graduation event per confirmed token, which the GuardrailPipeline picks up for enrichment and screening.