@gearbox-protocol/sdk 16.0.0-next.9 → 16.0.0

package/dist/types/sdk/prepare/types.d.ts

@@ -1,54 +1,82 @@
+import { Bps, Timestamp, TokenAmount } from "../../model/primitives.js";
+import { Curator } from "../../model/curators.js";
 import { PoolOpportunityKey, StrategyOpportunityKey } from "../../model/opportunities.js";
-import { StrategyPositionKey } from "../../model/positions.js";
-import { DataResponse } from "../../model/response.js";
+import { PositionCollateral, StrategyPosition, StrategyPositionKey } from "../../model/positions.js";
+import { SDKReturn } from "../../model/result.js";
+import { PositionClaimableWithdrawal } from "../../model/withdrawals.js";
 import "../../model/index.js";
-import { ClaimableWithdrawal } from "../../onchain/accounts/withdrawal-compressor/types.js";
 import { Asset } from "../../onchain/base/types.js";
 import { MultiCall } from "../../onchain/types/transactions.js";
 import { PoolSimulation } from "../../onchain/pools/types.js";
-import { OpenStrategyPreview } from "../../onchain/accounts/intents/open-strategy.js";
-import { PreviewErrorDetails, PreviewErrorReason, PreviewRefusal } from "../../onchain/accounts/intents/refusal.js";
-import { DelayedStart, OperationState, ResumableIntent, RouteRefusals } from "../../onchain/accounts/intents/types.js";
+import { BorrowLimitBinding, IntentPreviewError, PreviewErrorDetails, PreviewErrorReason, PreviewIssue, PreviewRefusal, raise, refuse } from "../../onchain/validation/refusal.js";
+import { LeverageBand } from "../../onchain/accounts/intents/leverage-band.js";
 import { AccountCalculatorOperation } from "../../onchain/accounts/intents/operations.js";
+import { ClaimRemainder, DelayedStart, OperationState, PathLossRate, ResumableIntent, RouteRefusals, WithdrawCeilings } from "../../onchain/accounts/intents/types.js";
+import { OpenStrategyState } from "../../onchain/accounts/intents/open-strategy.js";
 import "../../onchain/index.js";
+import { AccountFlowError, DebtOutOfRangeError, InsufficientPoolLiquidityError, LeverageOutOfRangeError, MultipleDelayedWithdrawalsError, NoDelayedRouteError, NoRecordedIntentError, NoStrategyTargetCollateralError, OpenFlowError, UnexpectedFailureError, UnsupportedCollateralTokenError, UnsupportedTokenPairError, WithRouteRefusals, WithdrawalInProgressError } from "./errors.js";
 import { Address } from "viem";
 //#region src/sdk/prepare/types.d.ts
 /**
- * What a pool deposit or withdrawal would yield.
+ * Where a pool operation leaves the wallet: the two sides of the trade as
+ * `sdk.pools` prices them, plus what a screen needs beside them and the raw
+ * simulation cannot know — whose market this is, and how large the position
+ * ends up.
+ **/
+interface LpState extends PoolSimulation {
+  /**
+   * Curator of the market the pool belongs to, in the same shape
+   * {@link PoolOpportunity} and {@link CreditOperationMarket} report it.
+   **/
+  curator: Curator;
+  /**
+   * The wallet's position in this pool once the operation has run, in the
+   * market's underlying.
+   *
+   * Denominated like {@link PoolPosition.netValue}, so a screen showing both
+   * reads one token: on an RWA market that is the unwrapped asset — USDC
+   * rather than the dcUSDC the pool actually holds.
+   *
+   * Does not account for withdrawal fee: this is what the remaining shares
+   * are worth, not what leaving with them would pay.
+   **/
+  netValue: TokenAmount;
+}
+/**
+ * What a pool deposit or withdrawal comes to.
  *
- * Shaped like {@link StrategySimulate} so both kinds of simulation are consumed
- * the same way, with the pool's own numbers as the preview: the ERC-4626
+ * Shaped like {@link StrategyResult} so both kinds of result are consumed the
+ * same way, with the pool's own numbers as the state: the ERC-4626
  * conversion applied to the amount, at the rate of the block the market was
  * loaded at.
  **/
-type LpSimulate = {
-  ok: true;
+interface LpResult {
   /**
    * Always empty: a pool operation is a single transaction, so there is no
-   * chain of steps to show. Present so callers can treat both simulations
-   * alike.
+   * chain of steps to show. Present so callers can treat both kinds of
+   * result alike.
    **/
   operations: [];
   /**
-   * What the wallet parts with and what it receives, plus the zapper the
-   * transaction goes through when one is involved.
+   * What the wallet parts with and what it receives, the zapper the
+   * transaction goes through when one is involved, and where the position ends
+   * up, see {@link LpState}.
    **/
-  preview: PoolSimulation;
+  state: LpState;
   /**
    * The transaction implementing the operation: exactly one, since a pool
    * operation is a single call on the pool or on its zapper.
    **/
   calls: MultiCall[];
-} | PreviewRefusal;
+  /** Block of the chain state this result was computed from. */
+  blockNumber: number;
+  /** Unix seconds of {@link blockNumber}. */
+  timestamp: Timestamp;
+}
 /**
- * What an operation on an existing credit account would yield.
- *
- * `ok: false` means the request itself is not viable — not that a call failed —
- * so the reason is a value rather than an exception: too much leverage, too
- * little of the source token, a token the flow does not accept.
+ * What an operation on an existing credit account comes to.
  **/
-type StrategySimulate = {
-  ok: true;
+interface StrategyResult {
   /**
    * The logical steps, each carrying the amounts it was computed from.
    * Useful for showing the user what will happen, and for pinning behaviour
@@ -59,26 +87,47 @@ type StrategySimulate = {
    * Projected account state once the operations execute: TVL, debt,
    * balances and quotas.
    **/
-  preview: OperationState;
+  state: OperationState;
   /**
    * Credit-facade multicall implementing the operations, ready to be sent
    * through `sdk.accounts`.
    **/
   calls: MultiCall[];
-} | PreviewRefusal;
+  /** Block of the chain state this result was computed from. */
+  blockNumber: number;
+  /** Unix seconds of {@link blockNumber}. */
+  timestamp: Timestamp;
+}
 /**
- * What the leading half of a delayed operation would yield: the request
+ * What the tail of a delayed operation comes to: {@link StrategyResult}, plus
+ * whether the claim it was built on settled the withdrawal whole.
+ **/
+interface FinalizeResult extends StrategyResult {
+  /**
+   * What the claim did not bring, when the venue paid out part of the matured
+   * withdrawal and left the rest of it queued — only a legacy Mellow multivault
+   * does. `undefined` everywhere else, which is the normal case: one request,
+   * one claim, one tail.
+   *
+   * When it is set, the result beside it serves only the share that arrived,
+   * and the operation is not over: pass `remainder.intent` back to
+   * {@link IOpportunitiesPrepare.finalize} with the next claim, see
+   * {@link ClaimRemainder}.
+   **/
+  remainder: ClaimRemainder | undefined;
+}
+/**
+ * What the leading half of a delayed operation comes to: the request
  * transaction, plus what it recorded for the tail and where that tail leads.
  *
- * Shaped like {@link StrategySimulate} with one field more, so the instant and
+ * Shaped like {@link StrategyResult} with one field more, so the instant and
  * the delayed route of the same request are compared side by side — and they
- * are meant to be compared on the same footing, so `preview` is the end of the
+ * are meant to be compared on the same footing, so `state` is the end of the
  * operation in both, not the end of the transaction.
  **/
-type DelayedStrategySimulate = {
-  ok: true;
+interface DelayedStrategyResult {
   /**
-   * {@inheritDoc StrategySimulate.operations}
+   * {@inheritDoc StrategyResult.operations}
    **/
   operations: AccountCalculatorOperation[];
   /**
@@ -91,9 +140,9 @@ type DelayedStrategySimulate = {
    * the request alone lands in — source spent, withdrawal position in its
    * place, debt untouched — is `delayed.afterRequest`.
    **/
-  preview: OperationState;
+  state: OperationState;
   /**
-   * {@inheritDoc StrategySimulate.calls}
+   * {@inheritDoc StrategyResult.calls}
    **/
   calls: MultiCall[];
   /**
@@ -101,62 +150,63 @@ type DelayedStrategySimulate = {
    * {@link DelayedStart}.
    **/
   delayed: DelayedStart;
-} | PreviewRefusal;
+  /** Block of the chain state this result was computed from. */
+  blockNumber: number;
+  /** Unix seconds of {@link blockNumber}. */
+  timestamp: Timestamp;
+}
 /**
  * What one of the two flows that sell a position asset —
- * {@link OpportunitiesPrepare.withdrawStrategy} and
- * {@link OpportunitiesPrepare.adjustLeverage} — would yield each way it can be
+ * {@link IOpportunitiesPrepare.withdrawStrategy} and
+ * {@link IOpportunitiesPrepare.adjustLeverage} — would yield each way it can be
  * served.
  *
  * Whether the account can sell that asset on the router, redeem it through its
  * issuer, or both, is not something the caller can know up front, so both routes
  * are quoted from one request. A route the account cannot take is `undefined`
  * with its refusal in `refused`, which is what lets a form offer exactly the
- * routes that exist; `ok: false` means neither does.
+ * routes that exist; a failure means neither does, and the error still carries
+ * `refused`, see {@link WithRouteRefusals}.
  **/
-type StrategyRoutesSimulate = {
-  ok: true;
+interface StrategyRoutesResult {
   /**
    * The router route: one transaction, settled on the spot. `undefined`
    * when the asset cannot be sold, see `refused.instant`.
    **/
-  instant: Extract<StrategySimulate, {
-    ok: true;
-  }> | undefined;
+  instant: StrategyResult | undefined;
   /**
    * The request half of the redemption route, which
-   * {@link OpportunitiesPrepare.finalize} completes once it matures.
+   * {@link IOpportunitiesPrepare.finalize} completes once it matures.
    * `undefined` when the route does not exist — no redemption venue for the
    * asset, or a request that settles at once anyway — see `refused.delayed`.
    **/
-  delayed: Extract<DelayedStrategySimulate, {
-    ok: true;
-  }> | undefined;
+  delayed: DelayedStrategyResult | undefined;
   /**
    * Why a missing route was refused, see {@link RouteRefusals}.
    **/
   refused: RouteRefusals;
-} |
-/**
- * The instant route's refusal, which is the one a caller can usually act on;
- * the delayed route's when the instant one did not even get that far.
- **/
-(PreviewRefusal & {
-  /**
-   * {@inheritDoc StrategyRoutesSimulate.refused}
-   **/
-  refused: RouteRefusals;
-});
+  /** Block of the chain state this result was computed from. */
+  blockNumber: number;
+  /** Unix seconds of {@link blockNumber}. */
+  timestamp: Timestamp;
+}
 /**
- * What opening a new leveraged position would yield.
+ * What opening a new leveraged position comes to.
  *
- * The only simulation that reports both an expected and a floor branch: opening
+ * The only result that reports both an expected and a floor branch: opening
  * takes both from a single pathfinder call, and `openCA` consumes both.
  **/
-type OpenStrategySimulate = {
-  ok: true;
-  preview: OpenStrategyPreview;
-} | PreviewRefusal;
+interface OpenStrategyResult {
+  /**
+   * Everything the opening arrives at: the projection, both branches of the
+   * post-open balances and quotas, and the router path `openCA` is handed.
+   **/
+  state: OpenStrategyState;
+  /** Block of the chain state this result was computed from. */
+  blockNumber: number;
+  /** Unix seconds of {@link blockNumber}. */
+  timestamp: Timestamp;
+}
 /**
  * Shared knobs. Both default to the SDK's own defaults when omitted.
  **/
@@ -165,17 +215,17 @@ interface PrepareOptions {
   slippage?: number;
   /**
    * Extra quota headroom in PERCENTAGE_FORMAT, to survive price drift between
-   * the simulation and execution.
+   * the preparation and execution.
    **/
   quotaReserve?: number;
 }
 /**
- * Position to simulate against. A `StrategyPosition` from
+ * Position to prepare against. A `StrategyPosition` from
  * `sdk.positions.list()` satisfies this, as does a bare key.
  **/
 type PositionInput = StrategyPositionKey;
 /**
- * Pool to simulate against. A `PoolOpportunity` from
+ * Pool to prepare against. A `PoolOpportunity` from
  * `sdk.opportunities.list()` satisfies this, as does a bare key.
  **/
 type PoolInput = PoolOpportunityKey;
@@ -208,7 +258,7 @@ interface WithdrawStrategyParams extends PrepareOptions {
   /**
    * Amount the wallet receives, denominated in `tokenOut`. `MAX_UINT256`, or
    * anything at or above the account's net value, turns the flow into an exit,
-   * see {@link OpportunitiesPrepare.withdrawStrategy}.
+   * see {@link IOpportunitiesPrepare.withdrawStrategy}.
    **/
   amount: bigint;
   /** Wallet receiving the payout. */
@@ -235,7 +285,7 @@ interface RepayStrategyParams extends PrepareOptions {
    * Amount taken from the wallet. Anything above the outstanding debt settles
    * it in full and stays on the account as collateral, so a caller clearing the
    * account can add a buffer for the interest that accrues before the
-   * transaction lands, see {@link OpportunitiesPrepare.maxRepay}.
+   * transaction lands, see {@link IOpportunitiesPrepare.maxRepay}.
    * `MAX_UINT256` settles the debt and sizes that buffer itself.
    **/
   amount: bigint;
@@ -301,13 +351,13 @@ interface LpParams {
   tokenIn?: Address;
   /**
    * Token the user receives. Defaults to the only route available for `tokenIn`;
-   * required when the pool offers several, otherwise the simulation reports
-   * `unsupportedTokenPair`.
+   * required when the pool offers several, otherwise the preparation is refused
+   * with `unsupportedTokenPair`.
    **/
   tokenOut?: Address;
 }
 /**
- * Same shape as {@link LpParams}, but {@link OpportunitiesPrepare.redeem}
+ * Same shape as {@link LpParams}, but {@link IOpportunitiesPrepare.redeem}
  * treats `amount` as the pool shares to burn rather than the underlying to
  * receive.
  **/
@@ -324,34 +374,51 @@ interface LpRedeemParams {
 interface FinalizeParams extends PrepareOptions {
   /**
    * The matured withdrawal to claim, from
-   * `sdk.onchain.chain(chainId).withdrawalCompressor.getCurrentWithdrawals()`.
+   * `sdk.positions.getCurrentWithdrawals()`.
    **/
-  claimable: ClaimableWithdrawal;
+  claimable: PositionClaimableWithdrawal;
   /**
    * The operation to resume. Defaults to the one the request recorded in the
-   * withdrawal's `extraData`, which is what {@link ClaimableWithdrawal.intent}
-   * decodes; pass it explicitly when the compressor is too old to report it.
+   * withdrawal's `extraData`, which is what
+   * {@link PositionClaimableWithdrawal.intent} decodes; pass it explicitly
+   * when the compressor is too old to report it — as a Mellow one is, since a
+   * Mellow request cannot carry an intent at all — or when a previous claim
+   * served only part of the operation and left one in
+   * {@link FinalizeResult.remainder}.
    **/
   intent?: ResumableIntent;
 }
 /**
- * Simulations of everything a wallet can do to a pool or a credit account.
+ * Everything a wallet can do to a pool or a credit account, prepared.
  *
  * On-chain only: every method reads live state and, for strategies, asks the
  * pathfinder for real swap paths. Nothing is executed and nothing is signed —
  * the result is the numbers plus the calldata that would produce them.
  *
- * Not to be confused with `src/preview/simulate`, which goes the other way: it
- * takes calldata that already exists and reports what it would do.
+ * Not to be confused with `src/preview`, which goes the other way: it takes
+ * calldata that already exists and reports what it would do.
+ *
+ * Every refusable method answers `SDKReturn` and names, in its own signature,
+ * exactly the errors its flow can refuse with — the union is the list of
+ * everything a caller has to handle, checked by the compiler. None of them
+ * throws: a chain that cannot be reached or a crash on the way arrives as
+ * `unexpectedFailure` with the cause attached.
+ *
+ * The bare readers stay outside the envelope: the `max*` ceilings answer their
+ * number and throw on an account or chain the SDK does not hold, and the two
+ * synchronous readers ({@link leverageBand}, {@link withdrawableCollaterals})
+ * weigh state already loaded and say "nothing available" with `undefined` or
+ * an empty list.
  **/
-interface OpportunitiesPrepare {
+interface IOpportunitiesPrepare {
   /**
    * Depositing into a pool: underlying in, shares out.
    *
-   * Synchronous, unlike every strategy simulation below: the answer is the
-   * pool's share rate applied to the amount, and that rate is already loaded.
+   * The trade itself is the pool's share rate applied to the amount, which is
+   * loaded already; the wait is for the one thing that is not, the shares the
+   * wallet holds, without which {@link LpState.netValue} cannot be said.
    **/
-  deposit(pool: PoolInput, params: LpParams): LpSimulate;
+  deposit(pool: PoolInput, params: LpParams): Promise<SDKReturn<LpResult, UnsupportedTokenPairError | UnexpectedFailureError>>;
   /**
    * Taking underlying out of a pool: `amount` is the `tokenOut` the wallet
    * wants back, and the pool burns whatever shares that costs.
@@ -359,26 +426,26 @@ interface OpportunitiesPrepare {
    * The LP counterpart of {@link withdrawStrategy} / {@link withdrawCollateral},
    * which act on credit accounts.
    **/
-  withdraw(pool: PoolInput, params: LpParams): LpSimulate;
+  withdraw(pool: PoolInput, params: LpParams): Promise<SDKReturn<LpResult, UnsupportedTokenPairError | UnexpectedFailureError>>;
   /**
    * Redeeming pool shares: `amount` is the `tokenIn` the wallet parts with,
-   * and the preview is the underlying it converts to.
+   * and the reported state is the underlying it converts to.
    **/
-  redeem(pool: PoolInput, params: LpRedeemParams): LpSimulate;
+  redeem(pool: PoolInput, params: LpRedeemParams): Promise<SDKReturn<LpResult, UnsupportedTokenPairError | UnexpectedFailureError>>;
   /**
    * Opening a leveraged position from wallet collateral.
    *
    * The one flow with no account yet, so the result carries no operation list —
    * it feeds `sdk.accounts.openCA` instead.
    **/
-  openNewStrategy(strategy: StrategyInput, params: OpenStrategyParams): Promise<DataResponse<OpenStrategySimulate>>;
+  openNewStrategy(strategy: StrategyInput, params: OpenStrategyParams): Promise<SDKReturn<OpenStrategyResult, OpenFlowError | DebtOutOfRangeError | LeverageOutOfRangeError | UnsupportedTokenPairError | InsufficientPoolLiquidityError | NoStrategyTargetCollateralError>>;
   /**
    * Growing a position: collateral in, debt drawn on top, both converted into
    * the position token.
    *
    * Leverage stays put unless `targetLeverage` asks for more.
    **/
-  depositStrategy(position: PositionInput, params: DepositStrategyParams): Promise<DataResponse<StrategySimulate>>;
+  depositStrategy(position: PositionInput, params: DepositStrategyParams): Promise<SDKReturn<StrategyResult, AccountFlowError | DebtOutOfRangeError | LeverageOutOfRangeError | UnsupportedCollateralTokenError | UnsupportedTokenPairError | InsufficientPoolLiquidityError>>;
   /**
    * Shrinking a position: part of its net value goes to the wallet and debt is
    * repaid in the same proportion, so leverage is unchanged.
@@ -386,7 +453,7 @@ interface OpportunitiesPrepare {
    * Answers with both routes the withdrawal can take — sold through the router
    * now, or redeemed through the source's issuer and finished days later — since
    * the source token decides which of them exist, see
-   * {@link StrategyRoutesSimulate}.
+   * {@link StrategyRoutesResult}.
    *
    * `MAX_UINT256` — or any amount at or above the account's net value — is an
    * exit instead: the quotas are dropped, the position is sold whole in one
@@ -404,18 +471,28 @@ interface OpportunitiesPrepare {
    * @see withdrawCollateral to move an asset out without touching debt, which
    * raises leverage instead.
    **/
-  withdrawStrategy(position: PositionInput, params: WithdrawStrategyParams): Promise<DataResponse<StrategyRoutesSimulate>>;
+  withdrawStrategy(position: PositionInput, params: WithdrawStrategyParams): Promise<SDKReturn<StrategyRoutesResult, (AccountFlowError | DebtOutOfRangeError | UnsupportedTokenPairError | NoDelayedRouteError | MultipleDelayedWithdrawalsError | WithdrawalInProgressError) & WithRouteRefusals>>;
   /**
-   * Largest partial withdrawal {@link withdrawStrategy} accepts, in underlying
-   * units: the amount whose proportional repayment leaves the debt at the
-   * credit manager's `minDebt`. Between this and the account's net value the
-   * flow refuses — the leftover loan would sit below `minDebt` — and at the net
-   * value it turns into an exit.
+   * How much {@link withdrawStrategy} can take out, both ends of it, in
+   * underlying units: `partial` is the largest withdrawal that keeps leverage
+   * and leaves the debt at the credit manager's `minDebt`, `exit` is the net
+   * value leaving entirely hands over.
+   *
+   * Two numbers rather than one because the range has a hole in it: between
+   * them the flow refuses with `debtOutOfRange`, since the leftover loan would
+   * sit below the floor. A form driving a slider off `partial` and a Max
+   * button off `exit` describes what the account can actually do; a form using
+   * either alone will misstate one of them — see {@link WithdrawCeilings},
+   * which spells out how far apart they can be.
+   *
+   * Taking everything out needs neither figure: send `MAX_UINT256` to
+   * {@link withdrawStrategy} and the exit is what runs, named rather than
+   * priced.
    *
-   * Taking everything out needs none of this arithmetic: send `MAX_UINT256` to
-   * {@link withdrawStrategy} and the exit is what runs.
+   * A bare read: it answers its numbers, and throws on an account or a chain
+   * the SDK does not hold.
    **/
-  maxWithdraw(position: PositionInput): Promise<DataResponse<bigint>>;
+  maxWithdraw(position: PositionInput): Promise<WithdrawCeilings>;
   /**
    * Paying debt down with funds from the wallet: collateral stays where it is,
    * so net value grows by what was repaid, leverage falls and the health factor
@@ -427,18 +504,21 @@ interface OpportunitiesPrepare {
    * A repayment that covers the whole debt clears the account's quotas with it,
    * which the facade requires of a loan going to zero, and asks for the full
    * outstanding amount, so nothing is left owing because interest moved between
-   * this simulation and the transaction. `MAX_UINT256` is how to ask for that
+   * this preparation and the transaction. `MAX_UINT256` is how to ask for that
    * settlement without naming a figure: the wallet is charged the debt plus a
    * 10bps margin for the interest still to come, and whatever the facade does
    * not take stays on the account.
    **/
-  repayStrategy(position: PositionInput, params: RepayStrategyParams): Promise<DataResponse<StrategySimulate>>;
+  repayStrategy(position: PositionInput, params: RepayStrategyParams): Promise<SDKReturn<StrategyResult, AccountFlowError | DebtOutOfRangeError | UnsupportedCollateralTokenError>>;
   /**
    * Debt {@link repayStrategy} would have to cover to clear the account, in
    * underlying units: principal, interest and fees as of this read. Interest
    * keeps accruing, so a wallet meaning to settle sends this with a buffer.
+   *
+   * A bare read: it answers its number, and throws on an account or a chain
+   * the SDK does not hold.
    **/
-  maxRepay(position: PositionInput): Promise<DataResponse<bigint>>;
+  maxRepay(position: PositionInput): Promise<bigint>;
   /**
    * Retargeting leverage at fixed collateral: debt moves, own funds do not.
    *
@@ -447,12 +527,12 @@ interface OpportunitiesPrepare {
    * buys instead, so there the delayed route is always absent with
    * `refused.delayed: "noDelayedRoute"`.
    **/
-  adjustLeverage(position: PositionInput, params: AdjustLeverageParams): Promise<DataResponse<StrategyRoutesSimulate>>;
+  adjustLeverage(position: PositionInput, params: AdjustLeverageParams): Promise<SDKReturn<StrategyRoutesResult, (AccountFlowError | DebtOutOfRangeError | UnsupportedTokenPairError | NoDelayedRouteError | MultipleDelayedWithdrawalsError | WithdrawalInProgressError | InsufficientPoolLiquidityError | LeverageOutOfRangeError) & WithRouteRefusals>>;
   /**
    * Putting the position token onto the account at fixed debt, which lowers
    * leverage and raises the health factor.
    **/
-  addCollateral(position: PositionInput, params: AddCollateralParams): Promise<DataResponse<StrategySimulate>>;
+  addCollateral(position: PositionInput, params: AddCollateralParams): Promise<SDKReturn<StrategyResult, AccountFlowError>>;
   /**
    * Moving one asset that already sits on the account out to the wallet, at
    * fixed debt — so TVL falls and leverage rises.
@@ -460,7 +540,46 @@ interface OpportunitiesPrepare {
    * @see withdrawStrategy for the deleveraging withdrawal, which repays debt in
    * proportion and leaves leverage unchanged.
    **/
-  withdrawCollateral(position: PositionInput, params: WithdrawCollateralParams): Promise<DataResponse<StrategySimulate>>;
+  withdrawCollateral(position: PositionInput, params: WithdrawCollateralParams): Promise<SDKReturn<StrategyResult, AccountFlowError>>;
+  /**
+   * The leverages a deposit of a given size can reach in this market: the
+   * range a leverage slider should mark as available.
+   *
+   * `maxLeverage` on the opportunity is the ceiling the liquidation threshold
+   * allows, and it is the same number whatever the deposit. What a given
+   * deposit reaches is decided by the debt it implies —
+   * `debt = netValue x (leverage - 1)` — and by the band the market puts that
+   * debt in.
+   *
+   * Synchronous, unlike the ceilings above it: those read the account from the
+   * chain, this one only needs loaded market state, so a form can ask on every
+   * keystroke. Hand over the collateral as it stands and the SDK values it —
+   * opening takes the tokens being deposited, adjusting the position's own net
+   * value in the underlying.
+   *
+   * Nothing at all when the market has no band to offer: a deposit too small
+   * to carry `minDebt` at any leverage the threshold allows, or a manager with
+   * no borrowing room left. Not the same answer as "every leverage works", and
+   * a caller must not mark a range for it.
+   **/
+  leverageBand(strategy: StrategyInput, collateral: readonly Asset[], targetHF?: Bps): LeverageBand | undefined;
+  /**
+   * The collaterals an account can actually take out, most valuable first —
+   * what a withdraw-collateral picker offers.
+   *
+   * `StrategyPosition.collaterals` is everything the account holds, in the
+   * order the manager keeps its tokens. Phantoms are in there: the position
+   * reports one as itself and puts the asset it redeems into under
+   * `withdrawals`, and {@link withdrawCollateral} cannot move a balance that
+   * is not transferable. Balances below dust are already gone — the position
+   * drops them as it is built.
+   *
+   * Synchronous, like {@link leverageBand}: it reads loaded token metadata and
+   * the position it was handed, so a form can ask on every render. Nothing is
+   * quoted here — which of these the router can sell is a different question,
+   * and the answer to it is a prepared operation.
+   **/
+  withdrawableCollaterals(position: StrategyPosition): PositionCollateral[];
   /**
    * Largest amount of one collateral {@link withdrawCollateral} can move out
    * while the account stays safely collateralised, in the token's units: the
@@ -468,8 +587,14 @@ interface OpportunitiesPrepare {
    * capped by their quotas) and the target keeps covering what the debt still
    * requires. Zero debt frees the whole balance — the ceiling a
    * withdraw-collateral form should offer.
+   *
+   * `targetHF` names the health factor to leave the account at, in basis
+   * points; omitted, the SDK holds it to the bar a form would.
+   *
+   * A bare read: it answers its number, and throws on an account or a chain
+   * the SDK does not hold.
    **/
-  maxWithdrawCollateral(position: PositionInput, token: Address): Promise<DataResponse<bigint>>;
+  maxWithdrawCollateral(position: PositionInput, token: Address, targetHF?: bigint): Promise<bigint>;
   /**
    * The tail of a delayed route: claim the matured withdrawal, then whatever the
    * operation that requested it still owes — repaying debt and paying the wallet
@@ -486,8 +611,13 @@ interface OpportunitiesPrepare {
    *
    * Answers like the instant flows, so both halves are consumed the same way.
    * Reports `noRecordedIntent` when the claim names no operation to resume.
+   *
+   * A claim can settle only part of what was queued — a legacy Mellow
+   * multivault pays out what it holds liquid and re-queues the rest — and then
+   * the result serves that share and `remainder` says what is left, see
+   * {@link FinalizeResult.remainder}.
    **/
-  finalize(position: PositionInput, params: FinalizeParams): Promise<DataResponse<StrategySimulate>>;
+  finalize(position: PositionInput, params: FinalizeParams): Promise<SDKReturn<FinalizeResult, AccountFlowError | NoRecordedIntentError | NoDelayedRouteError | WithdrawalInProgressError | UnsupportedTokenPairError>>;
 }
 //#endregion
-export { AddCollateralParams, AdjustLeverageParams, DelayedStrategySimulate, DepositStrategyParams, FinalizeParams, LpParams, LpRedeemParams, LpSimulate, OpenStrategyParams, OpenStrategySimulate, type OperationState, OpportunitiesPrepare, PoolInput, PositionInput, PrepareOptions, type PreviewErrorDetails, type PreviewErrorReason, type PreviewRefusal, RepayStrategyParams, StrategyInput, StrategyRoutesSimulate, StrategySimulate, WithdrawCollateralParams, WithdrawStrategyParams };
+export { AddCollateralParams, AdjustLeverageParams, BorrowLimitBinding, DelayedStrategyResult, DepositStrategyParams, FinalizeParams, FinalizeResult, IOpportunitiesPrepare, IntentPreviewError, type LeverageBand, LpParams, LpRedeemParams, LpResult, LpState, OpenStrategyParams, OpenStrategyResult, type OperationState, type PathLossRate, PoolInput, PositionInput, PrepareOptions, PreviewErrorDetails, PreviewErrorReason, PreviewIssue, PreviewRefusal, RepayStrategyParams, StrategyInput, StrategyResult, StrategyRoutesResult, type WithdrawCeilings, WithdrawCollateralParams, WithdrawStrategyParams, raise, refuse };

package/dist/types/sdk/prepare/withdrawable-collaterals.d.ts

@@ -0,0 +1,11 @@
+import { PositionCollateral, StrategyPosition } from "../../model/positions.js";
+import "../../model/index.js";
+import { OnchainSDK } from "../../onchain/OnchainSDK.js";
+import "../../onchain/index.js";
+//#region src/sdk/prepare/withdrawable-collaterals.d.ts
+/**
+ * {@inheritDoc IOpportunitiesPrepare.withdrawableCollaterals}
+ **/
+declare function withdrawableCollaterals(sdk: OnchainSDK, position: StrategyPosition): PositionCollateral[];
+//#endregion
+export { withdrawableCollaterals };

package/dist/types/sdk/preview/PreviewNamespace.d.ts

@@ -1,20 +1,23 @@
 import { OperationPreview, PreviewOperationInput, PreviewOperationOptions } from "../../model/previews.js";
+import { SDKReturn } from "../../model/result.js";
 import "../../model/index.js";
 import { MultichainSDK } from "../../onchain/MultichainSDK.js";
 import "../../onchain/index.js";
+import { PreviewOperationError } from "../../preview/preview/previewOperation.js";
+import "../../preview/index.js";
+import { IPreview } from "./types.js";
 import { NamespaceOptions } from "../types.js";
-import { Preview } from "./types.js";
 //#region src/sdk/preview/PreviewNamespace.d.ts
 /**
- * {@inheritDoc Preview}
+ * {@inheritDoc IPreview}
  **/
-declare class PreviewNamespace implements Preview {
+declare class PreviewNamespace implements IPreview {
   #private;
   constructor(onchain: MultichainSDK, options: NamespaceOptions);
   /**
-   * {@inheritDoc Preview.previewOperation}
+   * {@inheritDoc IPreview.previewOperation}
    **/
-  previewOperation(input: PreviewOperationInput, options?: PreviewOperationOptions): Promise<OperationPreview>;
+  previewOperation(input: PreviewOperationInput, options?: PreviewOperationOptions): Promise<SDKReturn<OperationPreview, PreviewOperationError>>;
 }
 //#endregion
 export { PreviewNamespace };

package/dist/types/sdk/preview/index.d.ts

@@ -1,3 +1,3 @@
-import { Preview, PreviewByMode } from "./types.js";
+import { IPreview, IPreviewByMode } from "./types.js";
 import { PreviewNamespace } from "./PreviewNamespace.js";
-export { Preview, PreviewByMode, PreviewNamespace };
+export { IPreview, IPreviewByMode, PreviewNamespace };