refactor: rename block handlers to semantic namespaced names (COW-1000)

[lgahdl]

Grant Review Finding

[F7] Rename C1–C5 block handlers to semantic names with contract namespace — NIT (DX/readability) (COW-1000)

The [COW:Cx] log prefixes and config names (ContractPoller, StatusUpdater, …) describe mechanism, not purpose. The C-numbering implies a strict sequence that isn't real — these are actually two pipelines + a one-shot. More importantly, the names lack namespacing: as more contracts get indexed alongside ComposableCoW, these flat names will keep absorbing unrelated concerns. Suggested renames: C1 → composableCow.OrderDiscoveryPoller, C2 → composableCow.CandidateConfirmer, C3 → composableCow.OrderStatusTracker, C4 → composableCow.OwnerBackfill, C5 → composableCow.CancellationWatcher.

---

Summary

• Renames all 5 Ponder block-handler entries from opaque C1–C5 shorthand to composableCow.* names that match their responsibility (OrderDiscoveryPoller, CandidateConfirmer, OrderStatusTracker, OwnerBackfill, CancellationWatcher)
• Updates ponder.config.ts block keys and ponder.on() call names in blockHandler.ts
• Updates section header comments, log prefixes ([COW:C1] → [COW:OrderDiscoveryPoller]), and all in-file cross-references to old names

Test plan

• pnpm typecheck — passes
• pnpm test — 19/19 passing
• Handler names in config match ponder.on() names exactly

🤖 Generated with Claude Code

[linear-code]

COW-1000

[lgahdl]

The handler rename is consistent throughout ponder.config.ts and blockHandler.ts, but docs/deployment.md still uses the old names in the Debug / Performance Flags table (this file is untouched by both this PR and #85):

• DISABLE_POLL_RESULT_CHECK description reads: "Disables the C1 ContractPoller block handler"
• DISABLE_DETERMINISTIC_CANCEL_SWEEP description reads: "Disables the C5 DeterministicCancellationSweeper"
• MAX_GENERATORS_PER_BLOCK_<chainId> description reads: "how many generators C1 and C5 will touch"

These should be updated to OrderDiscoveryPoller, CancellationWatcher, and OrderDiscoveryPoller and CancellationWatcher respectively to match the rename.

[lgahdl]

Code review — block handler rename (COW-1000)

Ponder app fingerprint / schema drop risk

Ponder 0.16.x tracks block sources by name in its internal _ponder_sync tables. Renaming all five block handler entries (ContractPoller → OrderDiscoveryPoller, CandidateConfirmer unchanged, StatusUpdater → OrderStatusTracker, HistoricalBootstrap → OwnerBackfill, DeterministicCancellationSweeper → CancellationWatcher) will look to Ponder like five sources were removed and five new ones were added. On a fresh deploy against an existing database Ponder will treat the old named sources as gone and start the new ones from their configured startBlock ("latest"). Since all five handlers use startBlock: "latest", no historical re-index is triggered — live block processing just resumes under the new names. No schema drop is required for this rename. Worth verifying in staging before the mainnet deploy regardless.

Name consistency

ponder.config.ts and blockHandler.ts are fully aligned:

• OrderDiscoveryPoller:block ✓
• CandidateConfirmer:block ✓ (no rename here)
• OrderStatusTracker:block ✓
• OwnerBackfill:block ✓
• CancellationWatcher:block ✓

Leftover old names

src/constants.ts still references the old identifiers in JSDoc comments (lines 22, 50, 55, 70, 76, 78). These are comments only and do not affect runtime, but they will drift from the log output the handlers now emit. Recommend a follow-up pass to update the JSDoc to use the new names; it's a small doc hygiene item, not a blocker.

Overall: PR is operationally safe. No schema changes, no logic changes, no orphaned ponder.on(...) registrations. Good to merge after confirming the staging deploy succeeds.

[lgahdl]

Documentation / CI review

docs/deployment.md — Debug/Performance Flags table still uses old names. Must fix before merge.

Lines 33–35 of docs/deployment.md still read:

• DISABLE_POLL_RESULT_CHECK — "Disables the C1 ContractPoller block handler."
• DISABLE_DETERMINISTIC_CANCEL_SWEEP — "Disables the C5 DeterministicCancellationSweeper."
• MAX_GENERATORS_PER_BLOCK_<chainId> — "how many generators C1 and C5 will touch…"

This PR renames those handlers to OrderDiscoveryPoller and CancellationWatcher. The table descriptions need to be updated to match, otherwise ops will grep for C1/C5 in the codebase and find nothing.

docs/api-reference.md — one stale reference.
Line 129: candidateDiscreteOrder.creationDate — "Block timestamp at C1 discovery." Should say OrderDiscoveryPoller.

Breaking change / schema drop notice missing from PR body.
The rename changes the Ponder block handler keys in ponder.config.ts (e.g. ContractPoller → OrderDiscoveryPoller). Ponder tracks block handler progress by name in its internal checkpoint. Renaming a handler key on an existing deployment causes Ponder to treat it as a new handler and re-run it from startBlock — for handlers with startBlock: "latest" this is harmless (they fire once at the next live block), but it is worth calling out in the PR body so operators know no schema drop is required, but the first restart will re-run all five handlers' initial blocks.

CLAUDE.md / agent_docs not affected. The code-patterns.md timeout label example ([COW:Cx]) is the only spot that references old shorthand — worth a follow-on update but not a merge blocker.

[yvesfracari]

This PR applies the suggestions but didn't answer other questions of Anxo with my take bellow them:

1. The flashloan orders flow aren't well documented. Shouldn't we have different handlers for composable cow and aave flash loan orders?

Flash loan orders are not handle by block handlers, we monitor directly events for it. However, we need to improve the documentation about it. The blockhandlers that have specific composable cow logic should mention it to make sure we separate what is generic (e.g. order status change that is valid for any kind of order)

2. We have around 11% unknown types. Are they really unknown?

Doing a quick search, no they are not unknown and we could identify (at least the main ones), example: (1, 2, 3)

3. Why is orderbook_cache retained vs dropped?

I think that is only to not check order API twice between deployments for orders that are already on its final state. Would double check if we're documenting this properly.

4. TWAP nParts upper bound.

Nice catch. He mention that UI only accept TWAPs with 365 parts. On contracts side they are validated to be lower than uint32.max, what is a really giant number of rows to insert into the DB. In addition, this validation happens after the conditional order is emitted, on the query / execution path. This means that the nParts upper bound on the contract perspective is actually uint256.max. Looking at the code I don't find any kind of guard against it. This means that someone could use it of a DDoS attack.

WRT this PR I would only address points 1 and 3 here. The others are big enough to be executed alone.

[lgahdl]

Addressed points 1 and 3 in latest commit:

Point 1 — Flash loan docs: Updated docs/architecture.md to clarify that the five block handlers (OrderDiscoveryPoller, CandidateConfirmer, OrderStatusTracker, OwnerBackfill, CancellationWatcher) are generic — they apply to all ComposableCoW generators regardless of order type. Aave flash loan adapter detection is explicitly called out as event-driven via settlement.ts, not a block handler. Added this distinction to the overview paragraph, data-flow diagram label, and the block handler section header.

Point 3 — order_uid_cache docs: Added a cow_cache.order_uid_cache subsection to the schema section explaining why it's retained across Ponder redeployments (Ponder creates a new schema namespace on each ponder start; without the persistent cache, CandidateConfirmer and OrderStatusTracker would re-query the API for thousands of already-final orders on every restart) and what is/isn't cached (terminal statuses only; open orders are never cached).

Also updated all remaining C1–C5 / old handler name references in architecture.md to the new semantic names.

Points 2 (unknown types classification) and 4 (nParts DDoS guard) tracked as separate issues.

[yvesfracari]

are these all generic? Some of them seem to be really attached to composable cow. The only that is

[jeffersonBastos]

I think we can remove this

[jeffersonBastos]

all "PostgreSQL Memory Flags"

[jeffersonBastos]

Also here

[jeffersonBastos]

I think we can remove this section.

[jeffersonBastos]

We could track all internal references to remove, like this one to internal linear tasks.