feat(clmm): orphaned-position lifecycle and recovery, bin_count passthrough, Raydium via Gateway

[fengtality]

Summary

API-side of the gateway#678 retry-ownership work, plus the CLMM pool-info plumbing that goes with it. Canonical design: docs/retry-architecture.md (in the gateway PR), esp. the two-topology section: executors created via the API run in-process with no controller, so the API owns the "react to a stranded position" role.

Orphaned-position lifecycle

• DB-aware stop: stop on a terminal executor returns already_terminated with close_type, position_address, orphaned_position, and hold_reason instead of the 404 dead end #678 hit (terminal executors are popped from memory within one tick, so "not in memory" almost always means "already terminated"). 404 is reserved for ids the DB has never seen.
• Orphan flagging on completion: an involuntary hold (POSITION_HOLD with hold_reason — an LP close that exhausted its retries) or a legacy FAILED-with-position gets orphaned_position: true persisted plus an error-level log. Voluntary holds never match (a successful close clears position_address first).
• GET /executors/positions/orphaned: recovery candidates, SQL-filtered to lp_executor — involuntary holds, FAILED-with-position, and SYSTEM_CLEANUP restarts (flagged needs_onchain_reconciliation).
• POST /executors/{id}/resolve-orphan: mark recovered after the position is closed externally; silences listings and agent warnings.
• bots/controllers lp_rebalancer mirror: halt + skip accounting for executors that ended with a live position.

Closing an orphaned position

The lifecycle above could flag an orphan but not clear it — the close itself failed.

• /gateway/clmm/close and /collect-fees accept pool_address. Both read a position's pool only from gateway_clmm_positions and 404'd when absent. An lp_executor opens its position straight from the bot to Gateway, so it is never in that table — on a live deployment the table was empty and every orphan 404'd. Resolution is now database-first, then the request field, then a 400 (a bad request, not a missing position) naming pool_address as the fix. Gateway's close needs only position_address; pool_address is used to snapshot pending fees before the close so they can be reported.
• /executors/positions/orphaned reports lp_provider and pool_address. It previously gave a caller nothing to build a close from: connector_name holds the network for an lp_executor (solana-mainnet-beta), not the DEX. The DEX (orca/clmm) and pool live in the executor's stored config and are now surfaced.

CLMM pool-info: bin_count, and Raydium consistency

• GET /gateway/clmm/pool-info accepts bin_count and forwards it to Gateway's unified trading/clmm/pool-info, making the per-tick liquidity distribution reachable for orca, raydium, uniswap and pancakeswap (Meteora always returns its own bins). The response model already carried bins.
• Raydium no longer bypasses Gateway. The route special-cased it: skipping Gateway entirely, calling api-v3.raydium.io directly, and reshaping that response to imitate Gateway's. That divergence cost real data — the transform hardcoded active_bin_id to None, bin_step to 1, and bins to [] — and it meant Raydium could not answer bin_count at all, since only Gateway computes the tick distribution. Raydium now takes the same path as every other CLMM connector; the Raydium API helpers and their aiohttp import go with it.

Companion PRs

• Design doc: docs/retry-architecture.md (in the gateway PR)
• gateway fix(clmm): retry-ownership gateway side, unified poll status contract, binCount on pool-info gateway#679 — typed errors, pre-broadcast simulation guard, position-info contract, unified poll status contract, binCount on unified CLMM pool-info
• hummingbot feat(lp): executor-owned close retry loop, involuntary POSITION_HOLD, bounded pending-tx polling hummingbot#8424 — executor-owned close retry loop, involuntary POSITION_HOLD, fresh position reads, bounded pending-tx polling
• hummingbot-api feat(clmm): orphaned-position lifecycle and recovery, bin_count passthrough, Raydium via Gateway #217 — orphan flag/listing/resolve, DB-aware stop, bin_count passthrough, Raydium routed through Gateway
• hummingbot-api-client feat(clmm): bin_count, CLMM liquidity methods, and orphan-closable positions (1.5.8) hummingbot-api-client#25 — bin_count on get_pool_info (1.5.8)
• condor feat(clmm): manage_clmm tool to recover orphaned LP positions; bin_count on get_pool_info condor#204 — agent visibility, orphaned/resolve_orphan actions, bin_count on get_pool_info

Note

routers/gateway_clmm.py and models/gateway_trading.py also gain some unrelated line-wrapping and a dropped unused import: the flake8 pre-commit hook lints the whole file and would not otherwise accept a commit touching it.

Validation

36 gateway-client contract tests pass. Validated live on mainnet with the companion branches deployed:

• Forced close-failure cascade terminated as the involuntary hold, surfaced in the orphan listing with hold_reason, re-stop returned already_terminated, and resolve-orphan cleared it after a direct gateway close recovered all funds + rent.
• Orphan-close path: verified against the live database that lp_provider and pool_address extract from real lp_executor config rows, and that gateway_clmm_positions is empty for executor-opened positions (the condition that made every orphan close 404). The endpoints themselves are not yet re-verified live — that needs a rebuilt API image.
• bin_count=5 returns populated bins for orca and raydium through this endpoint; bin_count=0 returns none. Raydium via Gateway now reports a real active_bin_id where the bypass reported None.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Mt84XBEMVxbbyMG8fDxDKj

[greptile-apps]

Greptile Summary

The PR adds durable orphaned-position detection, listing, resolution, and recovery metadata for CLMM executors while preserving the controller’s intentionally process-local safety latch. It also adds CLMM bin_count and pool_address plumbing and routes Raydium pool information through Gateway.

• Persists and exposes orphaned executor positions for operator recovery.
• Adds DB-aware behavior for stopping already-terminated executors.
• Supports orphan close and fee collection using request-supplied pool addresses.
• Passes CLMM bin counts through Gateway and removes the direct Raydium API path.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains within the eligible follow-up scope.

No blocking failure remains.

Important Files Changed

Filename	Overview
bots/controllers/generic/lp_rebalancer/lp_rebalancer.py	Adds a process-local halt when an LP executor terminates with a live position; the reviewed restart and resolution behavior matches the explicitly accepted design.
services/executor_service.py	Persists orphan metadata, discovers recovery candidates, resolves recovered records, and handles terminal executor stop requests.
routers/executors.py	Exposes orphan listing and resolution endpoints backed by ExecutorService.
routers/gateway_clmm.py	Adds pool-address fallback and bin-count forwarding while unifying Raydium with the Gateway CLMM path.
database/repositories/executor_repository.py	Adds persistence queries supporting terminal executor lookup and orphan recovery.
models/executors.py	Extends executor API contracts with orphan lifecycle and recovery fields.

_{Reviews (12): Last reviewed commit: "test(gateway): pin the amm quote-liquidi..." | Re-trigger Greptile}

[fengtality]

Superseded — reopening against the current branch. The work continues in a new PR, linked from the same cross-repo set; condor #204 stays open and is referenced there.