SAYLOR The result you are building
Finished Result:
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.
Stop Before Proceeding:
Stop when pool or token identity, position ownership, withdrawal authority, token behavior, or executable exit is uncertain. Use read-only inspection and simulation before signing; never share wallet secrets.
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
Start with the row that most closely matches the evidence. The first test isolates a layer; it is not permission to
make every available change.
Evidence Likely layer First decisive check What the result means
TVL high, quote Active Request executable quotes at Liquidity is concentrated away from price or displayed TVL is not
impact high depth/range several sizes usable depth.
Withdraw simulation Position/accou Inspect first failing instruction Wrong position, range, token account, authority, compute, or
fails nt/program and position state program state blocks exit.
Fees shown but not Accounting/re Read position accrual and UI estimate, outdated data, or inactive reward differs from
claimable ward reward program accounts on-chain claim.
Pool price differs Price/arbitrage Compare executable bid/ask Pool is thin, stale, isolated, manipulated, or token transfer
from market /token and independent markets behavior differs.
Zap-out fails while Router/quote Simulate remove-liquidity Convenience route, slippage, account, or quote expiry fails after
direct removal works separately from swaps 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.
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.
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.
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.
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.
Procedure continued 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.
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.
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.
Decision rule SHIP / AUTOMATE GATE Proceed only when every required acceptance check is supported by direct evidence, rollback is available, and the remaining risk is explicitly owned. Unknown is not a pass.
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
Starting Problem:
A Meteora position shows $2,000 value, but zap-out repeatedly fails.
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.
Proof Of Completion:
Position liquidity decreases as expected, tokens arrive in verified accounts, and any later swap follows a fresh bounded quote without duplicate withdrawal.
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 Request executable quotes at several sizes price or displayed TVL is not usable depth.
Withdraw simulation fails Wrong position, range, token account, Inspect first failing instruction and position state authority, compute, or program state blocks exit.
Fees shown but not claimable UI estimate, outdated data, or inactive Read position accrual and reward program accounts reward differs from on-chain claim.
Pool price differs from market Pool is thin, stale, isolated, Compare executable bid/ask and independent markets manipulated, or token transfer behavior differs.
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.
Returned output
Field Type Requirement
diagnosis object Likely layer, supporting and conflicting evidence, alternatives, and confidence.
plan step[] Ordered bounded actions with owner, risk, expected proof, and stop condition.
verification check[] Observed pass/fail/unknown results, not inferred success from command exit alone.
handoff object Sanitized evidence record, recovery state, remaining risk, and next review trigger.
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
- https://solana.com/docs/programs
- https://docs.orca.so/
- https://docs.uniswap.org/concepts/protocol/concentrated-liquidity