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 moves retry ownership upstream while making Gateway return typed, actionable transaction outcomes and reject known-failing Solana transactions before broadcast.

• Unifies Ethereum and Solana polling under NOT_FOUND, FAILED, PENDING, and CONFIRMED status codes.
• Improves Solana program-error attribution and Orca position lookup semantics.
• Adds binCount forwarding, shared V3 bin calculations, and PancakeSwap pool balances.
• Replaces nonfunctional default Ethereum and BSC RPC endpoints.

Confidence Score: 5/5

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

No blocking failure remains.

Important Files Changed

Filename	Overview
src/chains/solana/solana.ts	Adds shared transaction status handling, failed-simulation rejection, and typed landed-transaction error processing.
src/chains/solana/routes/poll.ts	Distinguishes unknown signatures from pending transactions and parses transaction errors with program logs.
src/chains/ethereum/routes/poll.ts	Replaces heuristic statuses with the unified contract and correctly marks reverted receipts as failed.
src/chains/solana/solana-error-parser.ts	Attributes custom errors to the failing program and maps Orca error 6018 to slippage exceeded.
src/connectors/clmm-v3-utils.ts	Introduces SDK-neutral bigint calculations for V3 liquidity-bin distributions.
src/connectors/pancakeswap/clmm-routes/poolInfo.ts	Adds requested bin distributions and reports actual pool-token balances.
src/trading/clmm/pools.ts	Threads validated binCount requests through supported CLMM connectors while preserving Meteora behavior.
src/connectors/orca/orca.ts	Restricts null position results to definitive account absence and propagates transient lookup failures.
src/schemas/chain-schema.ts	Defines the common cross-chain transaction status contract.
src/schemas/clmm-schema.ts	Extends unified pool-info requests and responses with bounded bin-distribution support.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    U[Upstream retry owner] -->|one attempt| G[Gateway route]
    G --> S[Fetch and simulate]
    S -->|simulation error| E[Typed error without broadcast]
    S -->|simulation succeeds| B[Broadcast and confirm]
    B --> P[Unified poll contract]
    P --> C{TransactionStatusCode}
    C --> N[NOT_FOUND]
    C --> F[FAILED]
    C --> W[PENDING]
    C --> O[CONFIRMED]
    I[Unified CLMM pool-info] --> Q[binCount]
    Q --> V[Connector-specific pool reader]
    V --> D[Bin distribution and balances]

Loading

_{Reviews (12): Last reviewed commit: "refactor(clmm): drop the never-populated..." | Re-trigger Greptile}