fix(solana): typed close errors + pre-broadcast simulation guard; Orca position-info contract (retry architecture)

[fengtality]

Summary

Gateway-side changes for the gateway#678 LP-close retry-ownership work. This PR also 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).

• 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. Regression-tested with a full simulation-shaped log.
• Pre-broadcast simulation guard: both send paths now 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: the in-route close retry loop from 040e99e. Gateway stays a stateless transaction oracle (one request = one attempt, typed errors); retry ownership lives upstream — see doc §6. Note this is now 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 (legacy route used a 50% buffer).

Companion PRs

• Design doc: docs/retry-architecture.md (in the gateway PR)
• gateway fix(solana): typed close errors + pre-broadcast simulation guard; Orca position-info contract (retry architecture) #679 — typed errors, pre-broadcast simulation guard, position-info contract (stateless; no retry loop)
• hummingbot feat(lp): retry-ownership for position close — bounded re-entry, involuntary POSITION_HOLD, fresh position reads hummingbot#8424 — connector retry opt-in, executor bounded re-entry + involuntary POSITION_HOLD, rebalancer halt
• hummingbot-api feat(executors): orphaned-position lifecycle for LP executors — flag, listing, DB-aware stop, resolve hummingbot-api#217 — orphan flag/listing/resolve, DB-aware stop (topology B: no controller)
• condor feat(executors): surface orphaned LP positions to agents — tick-prompt warnings, orphaned/resolve_orphan actions condor#204 — agent visibility, orphaned/resolve_orphan actions, recovery guidance

Validation

tsc + eslint clean; 74 targeted jest tests pass. Validated live on mainnet: a forced-failure cascade (fault-injected minimums) had all 33 doomed close attempts rejected pre-broadcast at zero fee cost, with 6018 correctly surfaced as SLIPPAGE_EXCEEDED; funded open/close cycles pass on the deployed image.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HahKfEY9rvKnZijrzUAFSq

[greptile-apps]

Greptile Summary

The PR standardizes transaction polling, adds typed Solana simulation and program-error handling, and tightens Orca’s position-existence contract.

• Introduces shared confirmed, pending, failed, and not-found transaction status codes across Ethereum and Solana.
• Rejects typed Solana simulation failures before broadcast and improves attribution of program-specific errors.
• Distinguishes definitively absent Orca positions from transient RPC and detail-fetch errors.
• Documents retry ownership and position-recovery responsibilities across the companion repositories.

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 status handling, pre-broadcast simulation-error guards, and typed handling for transactions that land with errors.
src/chains/solana/solana-error-parser.ts	Attributes custom errors to the program identified by the failure log and maps Orca error 6018 to slippage exceeded.
src/chains/solana/routes/poll.ts	Distinguishes signatures observed by the cluster from unknown signatures and includes program logs when parsing landed failures.
src/chains/ethereum/routes/poll.ts	Adopts the shared polling contract and correctly classifies reverted receipts as failed.
src/connectors/orca/orca.ts	Returns null only when the position account is definitively absent and propagates other position-fetch failures.
src/schemas/chain-schema.ts	Defines the shared cross-chain transaction status code contract.
docs/retry-architecture.md	Documents stateless Gateway attempts, upstream retry ownership, terminal position semantics, and orphan recovery.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Gateway
    participant RPC
    participant Program
    Client->>Gateway: Submit one transaction attempt
    Gateway->>RPC: Simulate transaction
    alt Simulation returns program error
        RPC-->>Gateway: Error and program logs
        Gateway->>Gateway: Parse failing program and typed error
        Gateway-->>Client: Typed error before broadcast
    else Simulation succeeds
        RPC-->>Gateway: Compute usage
        Gateway->>Program: Sign and broadcast
        Program-->>Gateway: Confirmation result
        Gateway-->>Client: Confirmed result or typed failure
    end

Loading

_{Reviews (6): Last reviewed commit: "fix(poll): attribute failed-transaction ..." | Re-trigger Greptile}