@gearbox-protocol/sdk 16.0.0-next.41 → 16.0.0-next.43

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

@@ -1,7 +1,7 @@
-import { Bps } from "../../model/primitives.js";
+import { Bps, Timestamp } from "../../model/primitives.js";
 import { PoolOpportunityKey, StrategyOpportunityKey } from "../../model/opportunities.js";
 import { PositionCollateral, StrategyPosition, StrategyPositionKey } from "../../model/positions.js";
-import { DataResponse } from "../../model/response.js";
+import { SDKReturn } from "../../model/result.js";
 import { PositionClaimableWithdrawal } from "../../model/withdrawals.js";
 import "../../model/index.js";
 import { Asset } from "../../onchain/base/types.js";
@@ -13,18 +13,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 { AccountFlowError, DebtOutOfRangeError, InsufficientPoolLiquidityError, LeverageOutOfRangeError, MultipleDelayedWithdrawalsError, NoDelayedRouteError, NoRecordedIntentError, NoStrategyTargetCollateralError, OpenFlowError, 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.
+ * What a pool deposit or withdrawal comes to.
  *
- * Shaped like {@link StrategyPrepare} so both kinds of result are consumed the
+ * 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 LpPrepare = {
-  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 kinds of
@@ -41,16 +41,15 @@ type LpPrepare = {
    * 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 StrategyPrepare = {
-  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
@@ -67,20 +66,23 @@ type StrategyPrepare = {
    * 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 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 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 `state` is the end of the
  * operation in both, not the end of the transaction.
  **/
-type DelayedStrategyPrepare = {
-  ok: true;
+interface DelayedStrategyResult {
   /**
-   * {@inheritDoc StrategyPrepare.operations}
+   * {@inheritDoc StrategyResult.operations}
    **/
   operations: AccountCalculatorOperation[];
   /**
@@ -95,7 +97,7 @@ type DelayedStrategyPrepare = {
    **/
   state: OperationState;
   /**
-   * {@inheritDoc StrategyPrepare.calls}
+   * {@inheritDoc StrategyResult.calls}
    **/
   calls: MultiCall[];
   /**
@@ -103,7 +105,11 @@ type DelayedStrategyPrepare = {
    * {@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 IOpportunitiesPrepare.withdrawStrategy} and
@@ -114,51 +120,48 @@ 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 WithRouteRefusals}.
  **/
-type StrategyRoutesPrepare = {
-  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<StrategyPrepare, {
-    ok: true;
-  }> | undefined;
+  instant: StrategyResult | 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: 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 StrategyRoutesPrepare.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 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 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;
-} | PreviewRefusal;
+  /** 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.
  **/
@@ -346,6 +349,20 @@ 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 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. An async flow
+ * never throws: a chain that cannot be reached or a crash on the way arrives
+ * as `unexpectedFailure` with the cause attached. The synchronous LP flows
+ * only do arithmetic on loaded state, so their one refusal is the unroutable
+ * pair — anything else there is a bug or a lifecycle error, and it throws.
+ *
+ * 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 IOpportunitiesPrepare {
   /**
@@ -354,7 +371,7 @@ interface IOpportunitiesPrepare {
    * Synchronous, unlike every strategy method below: the answer is the pool's
    * share rate applied to the amount, and that rate is already loaded.
    **/
-  deposit(pool: PoolInput, params: LpParams): LpPrepare;
+  deposit(pool: PoolInput, params: LpParams): SDKReturn<LpResult, UnsupportedTokenPairError>;
   /**
    * Taking underlying out of a pool: `amount` is the `tokenOut` the wallet
    * wants back, and the pool burns whatever shares that costs.
@@ -362,26 +379,26 @@ interface IOpportunitiesPrepare {
    * The LP counterpart of {@link withdrawStrategy} / {@link withdrawCollateral},
    * which act on credit accounts.
    **/
-  withdraw(pool: PoolInput, params: LpParams): LpPrepare;
+  withdraw(pool: PoolInput, params: LpParams): SDKReturn<LpResult, UnsupportedTokenPairError>;
   /**
    * Redeeming pool shares: `amount` is the `tokenIn` the wallet parts with,
    * and the reported state is the underlying it converts to.
    **/
-  redeem(pool: PoolInput, params: LpRedeemParams): LpPrepare;
+  redeem(pool: PoolInput, params: LpRedeemParams): SDKReturn<LpResult, UnsupportedTokenPairError>;
   /**
    * 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<OpenStrategyPrepare>>;
+  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<StrategyPrepare>>;
+  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.
@@ -389,7 +406,7 @@ interface IOpportunitiesPrepare {
    * 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 StrategyRoutesPrepare}.
+   * {@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
@@ -407,7 +424,7 @@ interface IOpportunitiesPrepare {
    * @see withdrawCollateral to move an asset out without touching debt, which
    * raises leverage instead.
    **/
-  withdrawStrategy(position: PositionInput, params: WithdrawStrategyParams): Promise<DataResponse<StrategyRoutesPrepare>>;
+  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
@@ -417,8 +434,11 @@ interface IOpportunitiesPrepare {
    *
    * 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 number, and throws on an account or a chain
+   * the SDK does not hold.
    **/
-  maxWithdraw(position: PositionInput): Promise<DataResponse<bigint>>;
+  maxWithdraw(position: PositionInput): Promise<bigint>;
   /**
    * 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
@@ -435,13 +455,16 @@ interface IOpportunitiesPrepare {
    * 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<StrategyPrepare>>;
+  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.
    *
@@ -450,12 +473,12 @@ interface IOpportunitiesPrepare {
    * buys instead, so there the delayed route is always absent with
    * `refused.delayed: "noDelayedRoute"`.
    **/
-  adjustLeverage(position: PositionInput, params: AdjustLeverageParams): Promise<DataResponse<StrategyRoutesPrepare>>;
+  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<StrategyPrepare>>;
+  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.
@@ -463,7 +486,7 @@ interface IOpportunitiesPrepare {
    * @see withdrawStrategy for the deleveraging withdrawal, which repays debt in
    * proportion and leaves leverage unchanged.
    **/
-  withdrawCollateral(position: PositionInput, params: WithdrawCollateralParams): Promise<DataResponse<StrategyPrepare>>;
+  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.
@@ -513,8 +536,11 @@ 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.
+   *
+   * 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, targetHF?: bigint): 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
@@ -532,7 +558,7 @@ interface IOpportunitiesPrepare {
    * Answers like the instant flows, so both halves are consumed the same way.
    * Reports `noRecordedIntent` when the claim names no operation to resume.
    **/
-  finalize(position: PositionInput, params: FinalizeParams): Promise<DataResponse<StrategyPrepare>>;
+  finalize(position: PositionInput, params: FinalizeParams): Promise<SDKReturn<StrategyResult, AccountFlowError | NoRecordedIntentError | NoDelayedRouteError | WithdrawalInProgressError | UnsupportedTokenPairError>>;
 }
 //#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, BorrowLimitBinding, DelayedStrategyResult, DepositStrategyParams, FinalizeParams, IOpportunitiesPrepare, IntentPreviewError, type LeverageBand, LpParams, LpRedeemParams, LpResult, OpenStrategyParams, OpenStrategyResult, type OperationState, type PathLossRate, PoolInput, PositionInput, PrepareOptions, PreviewErrorDetails, PreviewErrorReason, PreviewIssue, PreviewRefusal, RepayStrategyParams, StrategyInput, StrategyResult, StrategyRoutesResult, WithdrawCollateralParams, WithdrawStrategyParams, raise, refuse };

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

@@ -1,7 +1,10 @@
 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 { PreviewVerdictError } from "../../preview/preview/previewOperation.js";
+import "../../preview/index.js";
 import { IPreview } from "./types.js";
 import { NamespaceOptions } from "../types.js";
 //#region src/sdk/preview/PreviewNamespace.d.ts
@@ -14,7 +17,7 @@ declare class PreviewNamespace implements IPreview {
   /**
    * {@inheritDoc IPreview.previewOperation}
    **/
-  previewOperation(input: PreviewOperationInput, options?: PreviewOperationOptions): Promise<OperationPreview>;
+  previewOperation(input: PreviewOperationInput, options?: PreviewOperationOptions): Promise<SDKReturn<OperationPreview, PreviewVerdictError>>;
 }
 //#endregion
 export { PreviewNamespace };

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

@@ -1,5 +1,8 @@
 import { OperationPreview, PreviewOperationInput, PreviewOperationOptions } from "../../model/previews.js";
+import { SDKReturn } from "../../model/result.js";
 import "../../model/index.js";
+import { PreviewVerdictError } from "../../preview/preview/previewOperation.js";
+import "../../preview/index.js";
 //#region src/sdk/preview/types.d.ts
 /**
  * On-chain preview of a raw operation calldata.
@@ -7,10 +10,11 @@ import "../../model/index.js";
 interface IPreview {
   /**
    * Decodes a raw operation and assembles an operation-specific,
-   * human-displayable preview. Throws when the operation is unsupported or
-   * the targeted credit account cannot be resolved.
+   * human-displayable preview. A verdict on the calldata — an unsupported
+   * target, function or operation, a foreign delayed intent, a failed
+   * simulation — is the `ok: false` half; genuine failures still throw.
    **/
-  previewOperation(input: PreviewOperationInput, options?: PreviewOperationOptions): Promise<OperationPreview>;
+  previewOperation(input: PreviewOperationInput, options?: PreviewOperationOptions): Promise<SDKReturn<OperationPreview, PreviewVerdictError>>;
 }
 /**
  * `sdk.preview` per mode: an on-chain read, absent when the SDK reads no chain.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gearbox-protocol/sdk",
-  "version": "16.0.0-next.41",
+  "version": "16.0.0-next.43",
   "description": "Gearbox SDK",
   "license": "MIT",
   "repository": {
@@ -90,7 +90,15 @@
     "prepare": "husky",
     "check": "biome check --write",
     "check:ci": "biome check --diagnostic-level=error",
-    "typecheck:ci": "tsc --noEmit"
+    "typecheck:ci": "tsc --noEmit",
+    "agent:test:backend": "vitest run --project unit",
+    "agent:install": "pnpm install --frozen-lockfile",
+    "agent:test:frontend": "echo 'N/A: sdk is a library, no frontend lane'",
+    "agent:test:e2e": "vitest run --project e2e",
+    "agent:typecheck": "tsc --noEmit",
+    "agent:verify:commit": "pnpm check:ci",
+    "agent:verify:pr": "pnpm check:ci && pnpm typecheck:ci && pnpm test:unit && pnpm build",
+    "agent:verify:docs": "echo 'N/A: docs verified via planctl verify'"
   },
   "dependencies": {
     "@redstone-finance/evm-connector": "^0.9.0",
@@ -115,6 +123,7 @@
     "tsdown": "^0.22.14",
     "tsx": "^4.23.2",
     "typescript": "^7.0.2",
+    "unrun": "^0.3.1",
     "viem-deal": "^2.0.4",
     "vite": "^8.2.2",
     "vitest": "^4.1.11",