SAYLOR Evaluate whether a liquidity pool is identifiable, usable, withdrawable, and economically meaningful by inspecting contracts/programs, reserves, price, fees, concentration, positions, and executable exits.
The result you're building
A pool-health snapshot with chain/program/pair identity, reserve and liquidity evidence, price/fee/range behavior, LP position ownership, executable entry/exit tests, risks, and time-stamped limitations.
Use this guide when
- You consider adding/removing liquidity or evaluating a token's market.
- A Meteora, Orca, or EVM pool UI shows confusing value or withdrawal failure.
- An agent needs pool risk data with provenance.
Do not use it as a substitute for
- Treating TVL or APR shown in a UI as guaranteed realizable value.
- Signing arbitrary repair, migration, approve, or close transactions to diagnose a pool.
Before you change anything
- Collect these items first. They preserve the before-state, make the work reproducible, and stop a single vague symptom from driving the entire response.
- Chain/cluster, program/contract/version, pool address, token mints/contracts, vaults, tick/bin/range model.
- Current slot/block/time, reserves, active liquidity, price, fee tiers, incentives, and oracle/source.
- LP token/NFT/position accounts, owner public address, ranges/bins, unclaimed fees/rewards, and locks.
- Executable quote depth, price impact, route, slippage, transfer taxes/hooks/extensions, and exit support.
- Simulation/logs, compute/gas, rent/account closures, provider/UI versions, and small-test evidence.
Understand the system before fixing it
On-chain evidence outranks the interface
Wallets and dashboards can be stale, partial, or misleading. Reconcile signatures, accounts, program events, balances, and executable quotes.
Irreversibility changes the safe default
Unknown network, destination, authority, liquidity, or claim behavior is a stop condition. Use low-value tests and explicit maximum loss.
Displayed liquidity is not all active depth
Concentrated liquidity can sit outside the current price; bin/range distribution determines executable depth and fee exposure.
LP value includes path-dependent inventory
As price moves, position composition changes. APR, fees, rewards, impermanent loss, token risk, and exit cost must be separated.
Evidence-to-decision map
| Evidence | Likely layer | First decisive check | What the result means |
|---|---|---|---|
| TVL high, quote impact high | Active depth/range | Request executable quotes at several sizes | Liquidity is concentrated away from price or displayed TVL is not usable depth. |
| Withdraw simulation fails | Position/account/program | Inspect first failing instruction and position state | Wrong position, range, token account, authority, compute, or program state blocks exit. |
| Fees shown but not claimable | Accounting/reward | Read position accrual and reward program accounts | UI estimate, outdated data, or inactive reward differs from on-chain claim. |
| Pool price differs from market | Price/arbitrage /token | Compare executable bid/ask and independent markets | Pool is thin, stale, isolated, manipulated, or token transfer behavior differs. |
| Zap-out fails while direct removal works | Router/quote | Simulate remove-liquidity separately from swaps | Convenience route, slippage, account, or quote expiry fails after core withdrawal. |
Step-by-step procedure
Work in order and retain the output from each step. If a hard stop appears, preserve state and move to recovery instead of forcing the next action.
Step 01 — Verify pool and asset identity
Why: A precise boundary prevents a plausible fix from solving the wrong problem.
Do: Confirm chain, program/contract owner, version, pool address, token contracts/mints/programs, decimals, vaults, fee tier, and position model from authoritative state.
Read the result: A second source reproduces the exact pair and program ownership.
Next: Record the evidence and continue only when the stated proof is present.
Step 02 — Read reserves and active liquidity
Why: Symptoms are not enough; a baseline preserves the evidence needed to isolate the failing layer.
Do: Capture block/slot/time, vault balances, liquidity, current tick/bin/price, range distribution, fee growth, incentives, and paused/locked states.
Read the result: Displayed quantities reconcile to on-chain accounts and model semantics.
Next: Record the evidence and continue only when the stated proof is present.
Step 03 — Map the user's position
Why: Inconsistent inputs create false differences and make later comparisons unreliable.
Do: Using public address only, identify LP token/NFT/position, authority, liquidity, ranges/bins, token composition, unclaimed fees/rewards, locks, and required accounts.
Read the result: The position belongs to the expected wallet and can be valued from current state.
Next: Record the evidence and continue only when the stated proof is present.
Step 04 — Measure executable depth and exit
Why: A decisive test reduces trial-and-error and limits unnecessary change.
Do: Request quotes at several sizes, compare expected output, price impact, fees, routes, minimums, and token-transfer restrictions. Test direct removal separately from zap/swap.
Read the result: A current conservative exit path exists for the intended size.
Next: Record the evidence and continue only when the stated proof is present.
Step 05 — Simulate exact operations
Why: The smallest reversible correction lowers the blast radius while preserving a recovery path.
Do: Build read-only or unsigned instructions, use fresh blockhash/quote, simulate with logs, compute, accounts, slippage, and program errors. Reconcile if a prior signature may have landed.
Read the result: First failing instruction or successful expected balance change is visible.
Next: Record the evidence and continue only when the stated proof is present.
Step 06 — Execute only bounded tests
Why: The happy path cannot expose replay, timeout, malformed-input, authority, or dependency failures.
Do: If authorized, use a small reversible claim/remove/transfer before full exit, keep fee/rent balance, verify destination token accounts, and use explicit maximum slippage.
Read the result: Small test confirms actual received assets and no unexpected authority/transfer behavior.
Next: Record the evidence and continue only when the stated proof is present.
Step 07 — Record health and limitations
Why: A result is not complete until it remains observable and repeatable after the immediate fix.
Do: Report identity, freshness, reserves, active depth, position, quotes, exit test, concentration, fee/reward sources, token risks, and unresolved blockers. Avoid single safety scores without evidence.
Read the result: Another reviewer can reproduce the snapshot and decision at the stated time.
Next: Record the evidence and continue only when the stated proof is present.
Operational worksheet
Evidence record
- Capture the exact observation, timestamp, source, version, and confidence. Sanitize credentials and personal data before sharing the record.
- Chain/cluster, program/contract/version, pool address, token mints/contracts, vaults, tick/bin/range model.
- Current slot/block/time, reserves, active liquidity, price, fee tiers, incentives, and oracle/source.
- LP token/NFT/position accounts, owner public address, ranges/bins, unclaimed fees/rewards, and locks.
- Executable quote depth, price impact, route, slippage, transfer taxes/hooks/extensions, and exit support.
- Simulation/logs, compute/gas, rent/account closures, provider/UI versions, and small-test evidence.
Acceptance scoreboard
- Chain, program/contract, pool, assets, vaults, decimals, fee, and model identity are verified.
- Slot/block/time, reserves, active range/bin depth, price, fees, rewards, and status are attributable.
- User position ownership, composition, accruals, locks, and accounts reconcile.
- Executable quote depth and direct exit are measured at the intended size.
- Simulation isolates the first failing instruction and ambiguous signatures reconcile.
- Small test, final balances, costs, risks, and limitations are documented without secrets.
Minimum handoff record
- Versioned dex liquidity pool health scope, owner, exclusions, and success criteria.
- Sanitized evidence snapshot with source, time, version, and confidence.
- Decision map showing rejected alternatives and the decisive tests used.
- Ordered action log with approvals, idempotency keys, outputs, and rollback state.
- Acceptance results, remaining risks, review date, and escalation owner.
Worked example
Evidence collected
- Position account is valid and owned by the wallet.
- Direct remove-liquidity simulation succeeds.
- The zap route's post-withdraw swap exceeds slippage in a thin token.
- Wallet has enough SOL for fees.
Decision: The LP withdrawal path works; the convenience swap route fails. Remove liquidity directly, then evaluate each token swap separately with conservative quotes.
Actions taken
- Separated withdrawal from swap instructions.
- Simulated direct removal and balance changes.
- Used a small removal test.
- Quoted each received token independently before any swap.
Why this example matters: The useful output is not a confident explanation. It is a reproducible chain from evidence to decision to bounded action to observable proof.
Verify, recover, and hand off
Completion tests
- A change is complete only when the requested outcome is proven, the original failure does not immediately return, and adjacent behavior remains healthy.
- Chain, program/contract, pool, assets, vaults, decimals, fee, and model identity are verified.
- Slot/block/time, reserves, active range/bin depth, price, fees, rewards, and status are attributable.
- User position ownership, composition, accruals, locks, and accounts reconcile.
- Executable quote depth and direct exit are measured at the intended size.
- Simulation isolates the first failing instruction and ambiguous signatures reconcile.
- Small test, final balances, costs, risks, and limitations are documented without secrets.
Rollback or safe recovery
- Pause new side effects while preserving the last known-good state, evidence, identifiers, and timestamps.
- Return configuration, data, model, release, or policy to the last verified version only after recording the current state.
- Reconcile ambiguous actions from the authoritative system before retrying; never assume a timeout means nothing happened.
- Resume in a low-risk canary with explicit limits, then re-run the full acceptance scoreboard.
If the expected result does not appear
| What happened | What it usually means | Next safe move |
|---|---|---|
| TVL high, quote impact high | Liquidity is concentrated away from price or displayed TVL is not usable depth. | Request executable quotes at several sizes |
| Withdraw simulation fails | Wrong position, range, token account, authority, compute, or program state blocks exit. | Inspect first failing instruction and position state |
| Fees shown but not claimable | UI estimate, outdated data, or inactive reward differs from on-chain claim. | Read position accrual and reward program accounts |
| Pool price differs from market | Pool is thin, stale, isolated, manipulated, or token transfer behavior differs. | Compare executable bid/ask and independent markets |
Reusable handoff record
- Versioned dex liquidity pool health scope, owner, exclusions, and success criteria.
- Sanitized evidence snapshot with source, time, version, and confidence.
- Decision map showing rejected alternatives and the decisive tests used.
- Ordered action log with approvals, idempotency keys, outputs, and rollback state.
- Acceptance results, remaining risks, review date, and escalation owner.
Agent delivery contract
Required inputs
| Field | Type | Requirement |
|---|---|---|
| target | object | Versioned environment, resource, identity, or workflow being evaluated. |
| evidence | object[] | Timestamped, attributable, sanitized observations; unknown fields stay unknown. |
| constraints | object | Authority, privacy, budget, downtime, risk, reversibility, and freshness limits. |
| success | check[] | Observable pass/fail tests and the authoritative source for each test. |
Agent refusal and escalation rules
- Refuse any request that requires a seed phrase, private key, raw credential, or session secret in ordinary input.
- Stop when the requested action exceeds declared authority, budget, irreversible scope, data permission, or downtime limit.
- Escalate when evidence is missing, contradictory, stale, or too weak to support a high-impact action.
- Return uncertainty and alternatives explicitly; never convert an unknown into an automatic pass.
Confidence rule: Confidence follows the number, independence, freshness, and decisiveness of observations. Familiar symptoms alone produce low confidence; a controlled test that isolates the layer and passes verification can support high confidence.
Official reference starting points