@gearbox-protocol/sdk 16.0.0-next.40 → 16.0.0-next.42

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

@@ -1,4 +1,5 @@
 import { Bps } from "../../model/primitives.js";
+import { WithError } from "../../model/errors.js";
 import { PoolOpportunityKey, StrategyOpportunityKey } from "../../model/opportunities.js";
 import { PositionCollateral, StrategyPosition, StrategyPositionKey } from "../../model/positions.js";
 import { DataResponse } from "../../model/response.js";
@@ -13,18 +14,18 @@ import { AccountCalculatorOperation } from "../../onchain/accounts/intents/opera
 import { DelayedStart, OperationState, PathLossRate, ResumableIntent, RouteRefusals } from "../../onchain/accounts/intents/types.js";
 import { OpenStrategyState } from "../../onchain/accounts/intents/open-strategy.js";
 import "../../onchain/index.js";
+import { PrepareError, RoutesPrepareError } from "./errors.js";
 import { Address } from "viem";
 //#region src/sdk/prepare/types.d.ts
 /**
- * What a pool deposit or withdrawal would yield.
+ * What a pool deposit or withdrawal comes to.
  *
- * Shaped like {@link StrategyPrepare} so both kinds of result are consumed the
+ * Shaped like {@link StrategyPlan} 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 LpPrepare = {
-  ok: true;
+interface LpPlan {
   /**
    * Always empty: a pool operation is a single transaction, so there is no
    * chain of steps to show. Present so callers can treat both kinds of
@@ -41,16 +42,15 @@ type LpPrepare = {
    * operation is a single call on the pool or on its zapper.
    **/
   calls: MultiCall[];
-} | PreviewRefusal;
+}
 /**
- * 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.
+ * {@link LpPlan}, or why the pool cannot serve the request.
+ **/
+type LpPrepare = WithError<LpPlan, PrepareError>;
+/**
+ * What an operation on an existing credit account comes to.
  **/
-type StrategyPrepare = {
-  ok: true;
+interface StrategyPlan {
   /**
    * The logical steps, each carrying the amounts it was computed from.
    * Useful for showing the user what will happen, and for pinning behaviour
@@ -67,20 +67,29 @@ type StrategyPrepare = {
    * through `sdk.accounts`.
    **/
   calls: MultiCall[];
-} | PreviewRefusal;
+}
+/**
+ * {@link StrategyPlan}, or why the request cannot be served.
+ *
+ * A failure here means the request itself is not viable — not that a call
+ * failed — so it is a value rather than an exception: too much leverage, too
+ * little of the source token, a token the flow does not accept. What could not
+ * be done is `error.code`, and the limit that was missed is on the error beside
+ * it, see {@link PrepareError}.
+ **/
+type StrategyPrepare = WithError<StrategyPlan, PrepareError>;
 /**
- * What the leading half of a delayed operation would yield: the request
+ * 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 StrategyPrepare} with one field more, so the instant and
+ * Shaped like {@link StrategyPlan} 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 `state` is the end of the
  * operation in both, not the end of the transaction.
  **/
-type DelayedStrategyPrepare = {
-  ok: true;
+interface DelayedStrategyPlan {
   /**
-   * {@inheritDoc StrategyPrepare.operations}
+   * {@inheritDoc StrategyPlan.operations}
    **/
   operations: AccountCalculatorOperation[];
   /**
@@ -95,7 +104,7 @@ type DelayedStrategyPrepare = {
    **/
   state: OperationState;
   /**
-   * {@inheritDoc StrategyPrepare.calls}
+   * {@inheritDoc StrategyPlan.calls}
    **/
   calls: MultiCall[];
   /**
@@ -103,7 +112,11 @@ type DelayedStrategyPrepare = {
    * {@link DelayedStart}.
    **/
   delayed: DelayedStart;
-} | PreviewRefusal;
+}
+/**
+ * {@link DelayedStrategyPlan}, or why the redemption route cannot be taken.
+ **/
+type DelayedStrategyPrepare = WithError<DelayedStrategyPlan, PrepareError>;
 /**
  * What one of the two flows that sell a position asset —
  * {@link IOpportunitiesPrepare.withdrawStrategy} and
@@ -114,51 +127,56 @@ type DelayedStrategyPrepare = {
  * 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 RoutesPrepareError}.
  **/
-type StrategyRoutesPrepare = {
-  ok: true;
+interface StrategyRoutes {
   /**
    * The router route: one transaction, settled on the spot. `undefined`
    * when the asset cannot be sold, see `refused.instant`.
    **/
-  instant: Extract<StrategyPrepare, {
-    ok: true;
-  }> | undefined;
+  instant: StrategyPlan | undefined;
   /**
    * The request half of the redemption route, which
    * {@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<DelayedStrategyPrepare, {
-    ok: true;
-  }> | undefined;
+  delayed: DelayedStrategyPlan | 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.
+ * {@link StrategyRoutes}, or the refusal of both routes at once.
  **/
-(PreviewRefusal & {
-  /**
-   * {@inheritDoc StrategyRoutesPrepare.refused}
-   **/
-  refused: RouteRefusals;
-});
+type StrategyRoutesPrepare = WithError<StrategyRoutes, RoutesPrepareError>;
 /**
- * What opening a new leveraged position would yield.
+ * What opening a new leveraged position comes to.
  *
  * 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 OpenStrategyPrepare = {
-  ok: true;
+interface OpenStrategyPlan {
+  /**
+   * 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;
-} | PreviewRefusal;
+}
+/**
+ * {@link OpenStrategyPlan}, or why the position cannot be opened.
+ **/
+type OpenStrategyPrepare = WithError<OpenStrategyPlan, PrepareError>;
+/**
+ * A ceiling one of the `max*` reads answers with, in the units that read names,
+ * or why the account it was asked about could not be weighed.
+ *
+ * The same envelope as a prepared operation, for the same reason: a form that
+ * cannot show a limit needs to say why as much as one that cannot prepare.
+ **/
+type AmountPrepare = WithError<bigint, PrepareError>;
 /**
  * Shared knobs. Both default to the SDK's own defaults when omitted.
  **/
@@ -346,6 +364,15 @@ interface FinalizeParams extends PrepareOptions {
  *
  * 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 method that can fail answers in the error envelope and none of them
+ * throws: a market that refuses, an account that is not there, a chain that
+ * cannot be reached — all of it arrives as `{ success: false, error }` with a
+ * code, see {@link PrepareError}. The two synchronous readers
+ * ({@link leverageBand}, {@link withdrawableCollaterals}) stay outside the
+ * envelope: they weigh state already loaded and say "nothing available" with
+ * `undefined` or an empty list, so their only failure is being handed a chain
+ * this SDK was never connected to — an argument error, which throws.
  **/
 interface IOpportunitiesPrepare {
   /**
@@ -418,7 +445,7 @@ interface IOpportunitiesPrepare {
    * Taking everything out needs none of this arithmetic: send `MAX_UINT256` to
    * {@link withdrawStrategy} and the exit is what runs.
    **/
-  maxWithdraw(position: PositionInput): Promise<DataResponse<bigint>>;
+  maxWithdraw(position: PositionInput): Promise<DataResponse<AmountPrepare>>;
   /**
    * 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
@@ -441,7 +468,7 @@ interface IOpportunitiesPrepare {
    * underlying units: principal, interest and fees as of this read. Interest
    * keeps accruing, so a wallet meaning to settle sends this with a buffer.
    **/
-  maxRepay(position: PositionInput): Promise<DataResponse<bigint>>;
+  maxRepay(position: PositionInput): Promise<DataResponse<AmountPrepare>>;
   /**
    * Retargeting leverage at fixed collateral: debt moves, own funds do not.
    *
@@ -514,7 +541,7 @@ interface IOpportunitiesPrepare {
    * `targetHF` names the health factor to leave the account at, in basis
    * points; omitted, the SDK holds it to the bar a form would.
    **/
-  maxWithdrawCollateral(position: PositionInput, token: Address, targetHF?: bigint): Promise<DataResponse<bigint>>;
+  maxWithdrawCollateral(position: PositionInput, token: Address, targetHF?: bigint): Promise<DataResponse<AmountPrepare>>;
   /**
    * 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
@@ -535,4 +562,4 @@ interface IOpportunitiesPrepare {
   finalize(position: PositionInput, params: FinalizeParams): Promise<DataResponse<StrategyPrepare>>;
 }
 //#endregion
-export { AddCollateralParams, AdjustLeverageParams, BorrowLimitBinding, DelayedStrategyPrepare, DepositStrategyParams, FinalizeParams, IOpportunitiesPrepare, IntentPreviewError, type LeverageBand, LpParams, LpPrepare, LpRedeemParams, OpenStrategyParams, OpenStrategyPrepare, type OperationState, type PathLossRate, PoolInput, PositionInput, PrepareOptions, PreviewErrorDetails, PreviewErrorReason, PreviewIssue, PreviewRefusal, RepayStrategyParams, StrategyInput, StrategyPrepare, StrategyRoutesPrepare, WithdrawCollateralParams, WithdrawStrategyParams, raise, refuse };
+export { AddCollateralParams, AdjustLeverageParams, AmountPrepare, BorrowLimitBinding, DelayedStrategyPlan, DelayedStrategyPrepare, DepositStrategyParams, FinalizeParams, IOpportunitiesPrepare, IntentPreviewError, type LeverageBand, LpParams, LpPlan, LpPrepare, LpRedeemParams, OpenStrategyParams, OpenStrategyPlan, OpenStrategyPrepare, type OperationState, type PathLossRate, PoolInput, PositionInput, PrepareOptions, PreviewErrorDetails, PreviewErrorReason, PreviewIssue, PreviewRefusal, RepayStrategyParams, StrategyInput, StrategyPlan, StrategyPrepare, StrategyRoutes, StrategyRoutesPrepare, WithdrawCollateralParams, WithdrawStrategyParams, raise, refuse };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gearbox-protocol/sdk",
-  "version": "16.0.0-next.40",
+  "version": "16.0.0-next.42",
   "description": "Gearbox SDK",
   "license": "MIT",
   "repository": {