feat(clmm): orphaned-position lifecycle, 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.

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, 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 on get_pool_info (1.5.8) hummingbot-api-client#25 — bin_count on get_pool_info (1.5.8)
• condor feat(clmm): surface orphaned LP positions to agents; 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 also gains 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.
• 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 a durable API-side lifecycle for LP executors that terminate with potentially stranded on-chain positions.

• Flags qualifying terminal executor states and persists their recovery metadata.
• Adds database-backed orphan listing and resolution endpoints.
• Makes repeated stop requests return terminal executor details from the database.
• Halts the mirrored LP rebalancer while its current process knows of an unresolved position.
• Routes CLMM pool information through Gateway with optional bin-count forwarding.

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 a newly terminated LP executor still reports an on-chain position and avoids accounting its pool balances as returned funds.
database/repositories/executor_repository.py	Adds an SQL-filtered query for recent executor records matching selected close types and an optional executor type.
models/executors.py	Extends stop responses with terminal-state metadata and defines orphan-listing response models.
routers/executors.py	Exposes endpoints for listing and resolving database-backed orphan candidates.
services/executor_service.py	Implements DB-aware stop behavior, orphan persistence and discovery, and explicit resolution of recovered positions.
routers/gateway_clmm.py	Replaces the direct Raydium pool lookup with the common Gateway path and forwards an optional bin count.
services/gateway_client.py	Adds optional bin-count forwarding to Gateway CLMM pool-information requests.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[LP executor running] --> B{Terminal outcome}
    B -->|Normal close| C[Persist terminal state]
    B -->|Involuntary hold or failed with position| D[Flag orphan in final state]
    B -->|Restart cleanup| E[Mark for on-chain reconciliation]
    D --> F[Orphan listing]
    E --> F
    F --> G[Operator reconciles position externally]
    G --> H[Resolve orphan in database]
    H --> I[Remove from orphan listing]
    D --> J[Process-local controller halt]
    J --> K[Explicit controller restart after recovery]

Loading

_{Reviews (3): Last reviewed commit: "refactor(clmm): route Raydium pool-info ..." | Re-trigger Greptile}