fix(clmm): retry-ownership gateway side, unified poll status contract, binCount on pool-info

[fengtality]

Summary

Gateway-side changes for the gateway#678 LP-close retry-ownership work, plus the CLMM pool-info and transaction-poll fixes found while validating it live. This PR carries the canonical cross-repo design doc: docs/retry-architecture.md — the reference for all four companion PRs.

Fixes #678 (gateway side; the retry itself lives in the Hummingbot PR below).

Typed errors and fail-fast (the #678 mechanism)

• Error parser: map Orca Whirlpool 6018 TokenMinSubceeded → SLIPPAGE_EXCEEDED, and attribute custom program errors to the program on the failed: custom program error log line instead of the first invoke line. Simulation-shaped errors open with a ComputeBudget prelude, so the DEX-specific error tables were never consulted — this is the actual mechanism behind Orca close-position should rebuild and retry after transient failures #678's MATH_OVERFLOW misreport.
• Pre-broadcast simulation guard: both send paths reject a transaction whose compute-estimation simulation returned an error — stale-state failures become a typed 400 before broadcast (zero fees) instead of an on-chain failure.
• Orca getPositionInfo contract (ported onto the feat(orca): migrate connector to current Whirlpools SDK #676 SDK migration): returns null only when fetchMaybePosition reports the account does not exist; transient errors propagate. Callers treat null as "position closed", so a swallowed RPC blip could abandon a live funded position while reporting success.
• Deliberately not included: an in-route close retry loop. Gateway stays a stateless transaction oracle (one request = one attempt, typed errors); retry ownership lives upstream. This is load-bearing: the migrated close route quotes at the config slippagePct (~1%), the exact condition under which Orca close-position should rebuild and retry after transient failures #678 was reachable (the legacy route used a 50% buffer).

One transaction-status contract for both chains

The two /poll routes spoke different dialects, and both had defects that made a poller unable to act on the answer:

• Solana returned txStatus 0 (pending) for a signature the cluster had never seen — indistinguishable from one awaiting confirmation, so a dropped transaction polled as pending forever. It now consults the signature-status cache and reports the new NOT_FOUND (-2), which is terminal once the transaction's blockhash expires.
• Ethereum reported reverted transactions as CONFIRMED — typeof receipt.status === 'number' ? 1 : -1, and a revert's status is 0, which is a number. It also emitted 2/3 gas-price heuristics no consumer understood, and blocked the request for three 1-second retries before reporting not-found as -1.
• Both now share TransactionStatusCode: NOT_FOUND (-2) / FAILED (-1) / PENDING (0) / CONFIRMED (1). Transient poll errors report PENDING — an unknown outcome is a reason to poll again, not to give up.
• Poll error attribution: /poll parsed only JSON.stringify(meta.err), which carries the error code but names no program, so every program-specific code fell through to UNKNOWN. It now parses the err together with meta.logMessages. Errors raised by programs with no registered table (e.g. a third-party router that CPIs into Whirlpool) correctly stay generic rather than being misattributed to the DEX they called.

CLMM pool-info: binCount

GET /trading/clmm/pool-info — the unified route hummingbot-api and condor read through — could never return bins: its querystring schema had no binCount and it called every connector as (fastify, network, poolAddress), dropping the parameter that orca/raydium/uniswap already supported.

• Unified route accepts binCount and forwards it; Meteora is called without it, as it always returns its own bins.
• PancakeSwap CLMM gains bin support (it had none). The V3 tick walk moves to a shared clmm-v3-utils helper — the two SDKs disagree on numeric type (@uniswap/v3-sdk is JSBI, @pancakeswap/v3-sdk is native bigint), so the helper works in bigint and each connector adapts its own SDK rather than importing the other's math.
• Fixes PancakeSwap pool-info token amounts, which were pool.liquidity (V3 virtual liquidity in sqrt-price space) scaled by each token's decimals — the same meaningless figure reported for both sides. Now ERC20 balanceOf on the pool contract, the fix Uniswap already carried.

Dead default RPCs

eth.llamarpc.com (mainnet) and binance.llamarpc.com (BSC) answer nothing — gateway logged "Unable to fetch block number" at startup and every read failed, which is why PancakeSwap pool-info reported "Pool not found" for pools that plainly exist. Defaults are now eth-mainnet.g.alchemy.com/public (chainId 0x1) and bsc-dataseed.bnbchain.org (chainId 0x38).

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 #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 hummingbot-api#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

Validation

tsc + eslint clean; 257 chain tests and 181 connector/trading tests pass, including new coverage for both poll routes (incl. a regression test pinning EVM reverts to FAILED), the binCount passthrough, and PancakeSwap pool-info.

Validated live on mainnet with the stack deployed from these branches:

• Poll contract: real confirmed / failed / dropped / malformed signatures on Solana, and real confirmed / reverted / unknown transactions on Ethereum, each returning the intended code.
• Forced close-failure cascade (fault-injected minimums): 11 attempts, one gateway request per attempt, every one rejected pre-broadcast at zero fee cost.
• binCount=61 returns 61 populated bins for orca, raydium, uniswap and pancakeswap (Meteora keeps its own 141), bins straddling the active price correctly; PancakeSwap token amounts match direct on-chain balanceOf.
• Funded open/close/swap cycles pass on the deployed image.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Mt84XBEMVxbbyMG8fDxDKj

[greptile-apps]

Greptile Summary

The PR standardizes transaction polling and typed Solana failures, rejects failed simulations before broadcast, extends unified CLMM pool information with configurable bins, and updates connector transaction interfaces.

• Introduces the shared NOT_FOUND / FAILED / PENDING / CONFIRMED transaction-status contract.
• Adds CLMM bin distribution support and corrects PancakeSwap pool token balances.
• Propagates transient Orca position-read failures rather than treating them as closed positions.
• Updates default Ethereum and BSC RPC endpoints and regenerates the OpenAPI specification.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains within the scope of the available prior review threads.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/chains/solana/solana.ts	Adds simulation failure guards and signature-status classification for Solana transaction polling.
src/chains/solana/solana-error-parser.ts	Attributes custom program errors to the failing program and expands typed Whirlpool error handling.
src/chains/ethereum/routes/poll.ts	Replaces chain-specific polling heuristics with the shared transaction-status contract and correctly distinguishes reverted receipts.
src/connectors/orca/orca.ts	Narrows absent-position handling so transient position-fetch failures propagate to callers.
src/trading/clmm/pools.ts	Accepts and forwards the optional CLMM bin count while preserving Meteora’s connector-specific behavior.
src/connectors/clmm-v3-utils.ts	Centralizes bigint-based V3 tick traversal and bin-distribution calculations for compatible connectors.
src/connectors/pancakeswap/clmm-routes/poolInfo.ts	Adds PancakeSwap bin calculation and reports actual pool token balances.
src/schemas/chain-schema.ts	Defines the common transaction-status codes consumed by both chain polling routes.
openapi.json	Regenerates the public API contract for the revised schemas and route parameters.
docs/retry-architecture.md	Documents cross-repository retry ownership, terminal semantics, polling behavior, and CLMM pool-information flow.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Client[Gateway client] --> Trading[Unified trading routes]
    Trading --> Connector[Chain or DEX connector]
    Connector --> Simulation[Build and simulate transaction]
    Simulation -->|simulation succeeds| Broadcast[Broadcast and confirm]
    Simulation -->|simulation fails| TypedError[Typed pre-broadcast error]
    Broadcast --> Poll[Unified transaction polling]
    Poll --> Status[NOT_FOUND / FAILED / PENDING / CONFIRMED]
    Trading --> PoolInfo[CLMM pool information]
    PoolInfo --> Bins[Optional bin distribution]

Loading

_{Reviews (20): Last reviewed commit: "test(jupiter): assert removed fields' ab..." | Re-trigger Greptile}

[greptile-apps]

Too many files changed for review (162 files, 100 file limit).

Bypass the limit by tagging @greptile-apps to review.

[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.