@gearbox-protocol/sdk 15.1.0-next.2 → 15.1.0-next.21

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

@@ -1,6 +1,6 @@
-import { Asset, PermitResult } from "../base/types.js";
 import { PoolPosition } from "../../model/positions.js";
 import "../../model/index.js";
+import { Asset, PermitResult } from "../base/types.js";
 import { IZapperContract } from "../market/zapper/types.js";
 import "../market/index.js";
 import { MultiCall, RawTx } from "../types/transactions.js";
@@ -35,8 +35,8 @@ interface AddLiquidityProps {
 /**
  * Parameters for withdrawing liquidity from a Gearbox lending pool.
  *
- * Withdrawals are routed through a zapper that redeems pool shares
- * (diesel tokens) for the underlying asset.
+ * A direct withdrawal goes to the pool itself; anything else is routed through
+ * a zapper that redeems the share-like token it minted.
  **/
 interface RemoveLiquidityProps {
   /**
@@ -44,12 +44,21 @@ interface RemoveLiquidityProps {
    **/
   pool: Address;
   /**
-   * Amount of pool shares (diesel tokens) to redeem.
+   * Amount of underlying the wallet wants back, matching
+   * {@link PoolSimulation.tokenOut} when {@link RemoveLiquidityProps.mode} is
+   * `"withdraw"`. Amount of pool shares to burn when `mode` is `"redeem"`.
    **/
   amount: bigint;
   wallet: Address;
   permit: PermitResult | undefined;
   meta: WithdrawalMetadata;
+  /**
+   * `withdraw` calls the pool's ERC-4626 `withdraw(assets, …)`; `redeem` calls
+   * `redeem(shares, …)` or the zapper's redeem with shares directly.
+   *
+   * @default "withdraw"
+   **/
+  mode?: "withdraw" | "redeem";
 }
 type MarketType = "rwa-on-demand" | "rwa-default" | "classic";
 interface DepositMetadata {
@@ -92,6 +101,59 @@ interface WithdrawalMetadata {
    */
   type?: MarketType;
 }
+/**
+ * Props shared by {@link IPoolsService.simulateDeposit},
+ * {@link IPoolsService.simulateWithdraw}, and
+ * {@link IPoolsService.simulateRedeem}.
+ **/
+interface SimulatePoolOperationProps {
+  /**
+   * Address of the Gearbox lending pool.
+   **/
+  pool: Address;
+  /**
+   * Operation amount. Means `tokenIn` on deposit and redeem, `tokenOut` on
+   * withdraw — see each method's docs.
+   **/
+  amount: bigint;
+  /**
+   * Token the user parts with. Defaults to the pool underlying for deposits and
+   * to the pool shares (diesel token) for withdrawals.
+   **/
+  tokenIn?: Address;
+  /**
+   * Token the user receives. Defaults to the only route available for `tokenIn`;
+   * required when several routes exist.
+   **/
+  tokenOut?: Address;
+}
+/**
+ * Both sides of a simulated pool operation, converted at the pool's current
+ * share rate.
+ **/
+interface PoolSimulation {
+  /**
+   * Token and amount leaving the wallet — exactly what was asked for.
+   **/
+  tokenIn: Asset;
+  /**
+   * Token and amount arriving in the wallet at the rate the pool state implies.
+   **/
+  tokenOut: Asset;
+  /**
+   * Zapper the operation would be routed through; unset for direct pool
+   * operations.
+   **/
+  zapper?: Address;
+  /**
+   * Withdrawals only: underlying the pool can actually pay out right now,
+   * shaved by a hair so a withdrawal sized against it does not fail on rounding.
+   *
+   * The conversion is a rate, not a promise that the pool is liquid enough, so
+   * compare `tokenOut.balance` against this to see if the withdrawal fits.
+   **/
+  availableLiquidity?: bigint;
+}
 /**
  * Props for {@link IPoolsService.listPositions}.
  **/
@@ -158,6 +220,49 @@ interface IPoolsService {
    * @param tokenOut
    */
   getWithdrawalMetadata(pool: Address, tokenIn: Address, tokenOut?: Address): WithdrawalMetadata;
+  /**
+   * Simulates a deposit and reports what the wallet would receive.
+   *
+   * The ERC-4626 conversion of the pool, computed from the state the SDK already
+   * holds rather than read back from the chain, so the answer is synchronous and
+   * as fresh as the loaded market. Nothing is executed, so balances and
+   * allowances are irrelevant.
+   *
+   * A zapper leg converts one-for-one — every zapper wraps rather than trades —
+   * so a routed deposit reports the same amount as a direct one.
+   *
+   * @param props - {@link SimulatePoolOperationProps}
+   * @returns {@link PoolSimulation}
+   * @throws If the token pair has no route, or if `tokenOut` is omitted while
+   * several routes exist (RWA on-demand markets have no rate at all).
+   **/
+  simulateDeposit(props: SimulatePoolOperationProps): PoolSimulation;
+  /**
+   * Simulates a withdrawal and reports what the wallet would receive.
+   *
+   * The mirror of {@link simulateDeposit}: `amount` is the underlying the
+   * wallet wants back, and the result is the shares it costs at the pool's
+   * current rate.
+   *
+   * @param props - {@link SimulatePoolOperationProps}
+   * @returns {@link PoolSimulation}
+   * @throws If the token pair has no route, or if `tokenOut` is omitted while
+   * several routes exist.
+   **/
+  simulateWithdraw(props: SimulatePoolOperationProps): PoolSimulation;
+  /**
+   * Simulates a redemption and reports what the wallet would receive.
+   *
+   * The ERC-4626 `previewRedeem` mirror: `amount` is the shares to burn, and
+   * the result is the underlying they convert to, less the pool's withdrawal
+   * fee.
+   *
+   * @param props - {@link SimulatePoolOperationProps}
+   * @returns {@link PoolSimulation}
+   * @throws If the token pair has no route, or if `tokenOut` is omitted while
+   * several routes exist.
+   **/
+  simulateRedeem(props: SimulatePoolOperationProps): PoolSimulation;
   /**
    * Returns contract call parameters for adding liquidity to a pool
    * Or undefined if no deposit action is required (e.g. for RWA underlying on demand)
@@ -174,4 +279,4 @@ interface IPoolsService {
   removeLiquidity(props: RemoveLiquidityProps): PoolServiceCallResult;
 }
 //#endregion
-export { AddLiquidityProps, DepositMetadata, IPoolsService, ListPoolPositionsProps, MarketType, PoolServiceCall, PoolServiceCallResult, RemoveLiquidityProps, WithdrawalMetadata };
+export { AddLiquidityProps, DepositMetadata, IPoolsService, ListPoolPositionsProps, MarketType, PoolServiceCall, PoolServiceCallResult, PoolSimulation, RemoveLiquidityProps, SimulatePoolOperationProps, WithdrawalMetadata };

package/dist/types/sdk/positions/MultichainPositionsService.d.ts

@@ -1,8 +1,8 @@
-import { PluginsMap } from "../plugins/types.js";
-import "../plugins/index.js";
 import { Position } from "../../model/positions.js";
 import { DataResponse } from "../../model/response.js";
 import "../../model/index.js";
+import { PluginsMap } from "../plugins/types.js";
+import "../plugins/index.js";
 import { ListPositionsProps } from "./types.js";
 import { MultichainConstruct } from "../base/MultichainConstruct.js";
 import "../base/index.js";

package/dist/types/sdk/positions/PositionsService.d.ts

@@ -1,6 +1,7 @@
-import { Position } from "../../model/positions.js";
+import { Bps } from "../../model/primitives.js";
+import { BorrowRateBreakdown, Position, StrategyPosition } from "../../model/positions.js";
 import "../../model/index.js";
-import { ListPositionsProps } from "./types.js";
+import { AccountSnapshot, ListPositionsProps, ListStrategyPositionsProps } from "./types.js";
 import { SDKConstruct } from "../base/SDKConstruct.js";
 import "../base/index.js";
 //#region src/sdk/positions/PositionsService.d.ts
@@ -10,6 +11,7 @@ import "../base/index.js";
  * took over by liquidating.
  **/
 declare class PositionsService extends SDKConstruct {
+  #private;
   /**
    * Every position of a wallet on this chain, optionally narrowed by
    * {@link PositionFilter} (see {@link matchesPositionFilter} for what each
@@ -17,6 +19,35 @@ declare class PositionsService extends SDKConstruct {
    * the call rather than the SDK's loaded snapshot.
    **/
   list(props: ListPositionsProps): Promise<Position[]>;
+  /**
+   * Describes all credit accounts of a wallet as strategy positions.
+   *
+   * @param props - {@link ListStrategyPositionsProps}
+   **/
+  listStrategyPositions(props: ListStrategyPositionsProps): Promise<StrategyPosition[]>;
+  /**
+   * Health factor of an account state, in basis points (`10000` = 1.0).
+   **/
+  healthFactor(snapshot: AccountSnapshot, options?: {
+    safePrices?: boolean;
+  }): Bps;
+  /**
+   * Cost of an account state's debt, broken down into the pool's base rate
+   * and per-token quota rates.
+   **/
+  borrowRate(snapshot: AccountSnapshot): BorrowRateBreakdown;
+  /**
+   * Estimated milliseconds until the account's health factor decays to
+   * `10000` under its current borrow rate, or `null` when the debt carries
+   * no rate (or the account is already liquidatable).
+   **/
+  timeToLiquidation(snapshot: AccountSnapshot): bigint | null;
+  /**
+   * Price of the single non-underlying collateral at which the account
+   * becomes liquidatable, or `null` when the account holds zero or several
+   * non-underlying assets.
+   **/
+  liquidationPrice(snapshot: AccountSnapshot): bigint | null;
 }
 //#endregion
 export { PositionsService };

package/dist/types/sdk/positions/calcBorrowRate.d.ts

@@ -0,0 +1,44 @@
+import { Bps, Token } from "../../model/primitives.js";
+import { BorrowRateBreakdown } from "../../model/positions.js";
+import "../../model/index.js";
+import { AccountSnapshot } from "./types.js";
+import { Address } from "viem";
+//#region src/sdk/positions/calcBorrowRate.d.ts
+/**
+ * Inputs of {@link calcBorrowRate}.
+ **/
+interface CalcBorrowRateProps {
+  snapshot: AccountSnapshot;
+  /**
+   * Pool base interest rate in ray.
+   **/
+  baseInterestRate: bigint;
+  /**
+   * Credit manager interest fee in basis points.
+   **/
+  feeInterest: number;
+  /**
+   * Active quota rates in basis points. Missing keys are treated as inactive
+   * (zero contribution), but a per-token entry is still reported.
+   **/
+  quotaRates: Record<Address, Bps>;
+  /**
+   * Resolves full token metadata for a quota token address.
+   **/
+  resolveToken: (address: Address) => Token;
+}
+/**
+ * Cost of an account state's debt, broken down into the pool's base rate and
+ * per-token quota rates.
+ *
+ * The base rate is the market's current borrow APY (the pool's base rate plus
+ * the credit manager's interest fee) — the same value `borrowApy` reports on
+ * a position; it is not recomputed for the projected pool liquidity. Quota
+ * contributions are `quotaBalance * quotaRate` with the interest fee on top,
+ * normalized against the total value (`total`, `quotas`) and against the
+ * debt (`totalOnDebt`, the rate the debt itself grows at). Formulas are in
+ * parity with the frontend's `BorrowRateUtils`.
+ **/
+declare function calcBorrowRate(props: CalcBorrowRateProps): BorrowRateBreakdown;
+//#endregion
+export { CalcBorrowRateProps, calcBorrowRate };

package/dist/types/sdk/positions/calcHealthFactor.d.ts

@@ -0,0 +1,55 @@
+import { Bps } from "../../model/primitives.js";
+import "../../model/index.js";
+import { AccountSnapshot } from "./types.js";
+import { Address } from "viem";
+//#region src/sdk/positions/calcHealthFactor.d.ts
+/**
+ * Inputs of {@link calcHealthFactor}.
+ **/
+interface CalcHealthFactorProps {
+  snapshot: AccountSnapshot;
+  /**
+   * Market underlying. Debt and quota balances are valued in this token.
+   **/
+  underlying: Address;
+  /**
+   * Token decimals. Missing keys default to 18.
+   **/
+  decimals: Record<Address, number>;
+  /**
+   * Oracle main-feed prices in 8-decimal (`PRICE_DECIMALS`) fixed point. A
+   * missing key is an unpriceable token and contributes nothing.
+   **/
+  prices: Record<Address, bigint>;
+  /**
+   * Oracle reserve-feed prices, when available. Used with {@link safePrices}
+   * to value collateral at the lower of the two feeds.
+   **/
+  reservePrices?: Record<Address, bigint>;
+  /**
+   * Value collateral at safe prices — the lower of each token's main and
+   * reserve feeds. Debt and quota balances always use the main feed.
+   **/
+  safePrices?: boolean;
+  /**
+   * Liquidation thresholds in basis points. Missing keys are treated as 0.
+   **/
+  liquidationThresholds: Record<Address, Bps>;
+  /**
+   * Whether each token's quota is currently active. Missing keys are inactive.
+   **/
+  activeQuotas: Record<Address, boolean>;
+}
+/**
+ * Health factor of an account state, in basis points (`10000` = 1.0).
+ *
+ * Collateral is valued under liquidation thresholds, with quoted tokens
+ * capped by their quota, and compared against the debt's value. An account
+ * with no debt reports `65535` (`MAX_UINT16`), the contract's own sentinel
+ * scaled down. Formulas are in parity with the legacy `calcHealthFactor`.
+ * Tokens with no price in {@link CalcHealthFactorProps.prices} contribute
+ * nothing.
+ **/
+declare function calcHealthFactor(props: CalcHealthFactorProps): Bps;
+//#endregion
+export { CalcHealthFactorProps, calcHealthFactor };

package/dist/types/sdk/positions/calcLiquidationPrice.d.ts

@@ -0,0 +1,12 @@
+import { CalcLiquidationPriceProps } from "./calcLiquidationPriceForTarget.js";
+//#region src/sdk/positions/calcLiquidationPrice.d.ts
+/**
+ * Liquidation price of an account state's target collateral, in the oracle's
+ * 8-decimal (`PRICE_DECIMALS`) fixed point.
+ *
+ * As the frontend does, a liquidation price only exists when the account
+ * holds exactly one non-dust non-underlying asset; otherwise `null`.
+ **/
+declare function calcLiquidationPrice(props: CalcLiquidationPriceProps): bigint | null;
+//#endregion
+export { calcLiquidationPrice };

package/dist/types/sdk/positions/calcLiquidationPriceForTarget.d.ts

@@ -0,0 +1,43 @@
+import { Bps } from "../../model/primitives.js";
+import "../../model/index.js";
+import { AccountSnapshot } from "./types.js";
+import { Address } from "viem";
+//#region src/sdk/positions/calcLiquidationPriceForTarget.d.ts
+/**
+ * Shared market-side inputs of a liquidation-price calculation.
+ **/
+interface CalcLiquidationPriceProps {
+  snapshot: AccountSnapshot;
+  /**
+   * Market underlying. Its balance under its LT is subtracted from the debt.
+   **/
+  underlying: Address;
+  /**
+   * Token decimals. Missing keys default to 18.
+   **/
+  decimals: Record<Address, number>;
+  /**
+   * Liquidation thresholds in basis points. Missing keys are treated as 0.
+   **/
+  liquidationThresholds: Record<Address, Bps>;
+}
+/**
+ * Inputs of {@link calcLiquidationPriceForTarget}.
+ **/
+interface CalcLiquidationPriceForTargetProps extends CalcLiquidationPriceProps {
+  /**
+   * Collateral token whose liquidation price to compute.
+   **/
+  targetToken: Address;
+}
+/**
+ * Liquidation price of an explicitly named collateral token, in
+ * `PRICE_DECIMALS` fixed point; `0n` when the account holds none of it or the
+ * token has no liquidation threshold. Formula is in parity with the legacy
+ * `liquidationPrice`: the effective debt (debt less the underlying balance's
+ * contribution under its threshold) over the threshold-weighted target
+ * balance.
+ **/
+declare function calcLiquidationPriceForTarget(props: CalcLiquidationPriceForTargetProps): bigint;
+//#endregion
+export { CalcLiquidationPriceForTargetProps, CalcLiquidationPriceProps, calcLiquidationPriceForTarget };

package/dist/types/sdk/positions/calcTimeToLiquidationMs.d.ts

@@ -0,0 +1,16 @@
+import { Bps } from "../../model/primitives.js";
+import "../../model/index.js";
+//#region src/sdk/positions/calcTimeToLiquidationMs.d.ts
+/**
+ * Estimated milliseconds until `healthFactorBps` decays to `10000` (1.0)
+ * while the debt grows at `totalBorrowRateOnDebt`, in the same `Bps` scale
+ * (`10000` = 100%) as {@link BorrowRateBreakdown.totalOnDebt} reports it —
+ * not the legacy `PERCENTAGE_FACTOR_1KK` (`1_000_000` = 100%) scale the
+ * pre-rewrite frontend fed into its own `getTimeToLiquidation`.
+ *
+ * `null` when the account is already at or under the liquidation threshold,
+ * or when the debt carries no borrow rate at all.
+ **/
+declare function calcTimeToLiquidationMs(healthFactorBps: Bps, totalBorrowRateOnDebt: bigint): bigint | null;
+//#endregion
+export { calcTimeToLiquidationMs };

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

@@ -1,4 +1,9 @@
-import { ListPositionsProps, ListPositionsPropsBase } from "./types.js";
+import { AccountSnapshot, ListPositionsProps, ListPositionsPropsBase, ListStrategyPositionsProps, accountSnapshotFromCreditAccountData } from "./types.js";
+import { CalcBorrowRateProps, calcBorrowRate } from "./calcBorrowRate.js";
+import { CalcHealthFactorProps, calcHealthFactor } from "./calcHealthFactor.js";
+import { CalcLiquidationPriceForTargetProps, CalcLiquidationPriceProps, calcLiquidationPriceForTarget } from "./calcLiquidationPriceForTarget.js";
+import { calcLiquidationPrice } from "./calcLiquidationPrice.js";
+import { calcTimeToLiquidationMs } from "./calcTimeToLiquidationMs.js";
 import { MultichainPositionsService } from "./MultichainPositionsService.js";
 import { PositionsService } from "./PositionsService.js";
-export { ListPositionsProps, ListPositionsPropsBase, MultichainPositionsService, PositionsService };
+export { AccountSnapshot, CalcBorrowRateProps, CalcHealthFactorProps, CalcLiquidationPriceForTargetProps, CalcLiquidationPriceProps, ListPositionsProps, ListPositionsPropsBase, ListStrategyPositionsProps, MultichainPositionsService, PositionsService, accountSnapshotFromCreditAccountData, calcBorrowRate, calcHealthFactor, calcLiquidationPrice, calcLiquidationPriceForTarget, calcTimeToLiquidationMs };

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

@@ -1,7 +1,9 @@
-import { WithBlock } from "../types/multichain.js";
 import { PositionFilter } from "../../model/positions.js";
 import "../../model/index.js";
+import { WithBlock } from "../types/multichain.js";
+import { Asset, CreditAccountData } from "../base/types.js";
 import "../types/index.js";
+import "../base/index.js";
 import { Address } from "viem";
 //#region src/sdk/positions/types.d.ts
 /**
@@ -30,5 +32,58 @@ interface ListPositionsPropsBase {
  * {@link MultichainPositionsService.list}.
  **/
 type ListPositionsProps<Multichain extends boolean = false> = ListPositionsPropsBase & WithBlock<Multichain>;
+/**
+ * Props for {@link PositionsService.listStrategyPositions}.
+ **/
+interface ListStrategyPositionsProps {
+  /**
+   * Wallet whose credit accounts to describe. RWA accounts are resolved from
+   * the investor EOA, see {@link ICreditAccountsService.getBorrowerCreditAccounts}.
+   **/
+  owner: Address;
+  /**
+   * Whether to include accounts that carry no debt.
+   **/
+  includeZeroDebt: boolean;
+  /**
+   * Block to read at. Defaults to the latest block.
+   **/
+  blockNumber?: bigint;
+}
+/**
+ * The one input every position-metric function takes: a credit account's
+ * state — its credit manager, token balances, quota holdings, total debt and
+ * total value in the market's underlying — actual or projected.
+ *
+ * Everything else (decimals, prices, liquidation thresholds, quota rates,
+ * the pool's base rate) is supplied at the calculation site.
+ **/
+interface AccountSnapshot {
+  /**
+   * Credit manager the account is (or will be) opened in.
+   **/
+  creditManager: Address;
+  /**
+   * Token balances of the account.
+   **/
+  assets: Asset[];
+  /**
+   * Quota holdings of the account: quota balances are denominated in the
+   * market's underlying.
+   **/
+  quotas: Asset[];
+  /**
+   * Debt principal plus accrued interest and fees, in underlying.
+   **/
+  totalDebt: bigint;
+  /**
+   * Total account value in underlying.
+   **/
+  totalValue: bigint;
+}
+/**
+ * Builds an {@link AccountSnapshot} from on-chain credit account data
+ **/
+declare function accountSnapshotFromCreditAccountData(ca: CreditAccountData): AccountSnapshot;
 //#endregion
-export { ListPositionsProps, ListPositionsPropsBase };
+export { AccountSnapshot, ListPositionsProps, ListPositionsPropsBase, ListStrategyPositionsProps, accountSnapshotFromCreditAccountData };

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

@@ -1,12 +1,12 @@
 import { NetworkType } from "../chain/chains.js";
 import { WithdrawalsState } from "../accounts/withdrawal-compressor/types.js";
 import { MarketData } from "../base/types.js";
-import { PluginStatesMap, PluginsMap } from "../plugins/types.js";
-import "../plugins/index.js";
 import { RWAState } from "../market/rwa/types.js";
 import "../market/rwa/index.js";
 import { ZapperData } from "../market/types.js";
 import "../market/index.js";
+import { PluginStatesMap, PluginsMap } from "../plugins/types.js";
+import "../plugins/index.js";
 import { TokensMetaState } from "../base/TokensMeta.js";
 import { AddressProviderState } from "../core/types.js";
 import "../core/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gearbox-protocol/sdk",
-  "version": "15.1.0-next.2",
+  "version": "15.1.0-next.21",
   "description": "Gearbox SDK",
   "license": "MIT",
   "repository": {
@@ -147,5 +147,6 @@
       "biome check --no-errors-on-unmatched --write"
     ]
   },
+  "foundryVersion": "1.7.1",
   "packageManager": "pnpm@11.7.0"
 }

package/dist/cjs/model/history.js

@@ -1,53 +0,0 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-//#region src/model/history.ts
-/**
-* Every {@link PoolHistoryMetric}, for callers that enumerate them.
-**/
-const POOL_HISTORY_METRICS = [
-	"depositApy",
-	"borrowApy",
-	"dieselRate",
-	"supplied",
-	"borrowed",
-	"availableLiquidity"
-];
-/**
-* Every {@link StrategyHistoryMetric}, for callers that enumerate them.
-**/
-const STRATEGY_HISTORY_METRICS = [
-	"netApy",
-	"borrowApy",
-	"collateralApy",
-	"tvl",
-	"collateralPrice",
-	"collateralUsdPrice",
-	"underlyingUsdPrice"
-];
-/**
-* Every {@link PoolPositionHistoryMetric}, for callers that enumerate them.
-**/
-const POOL_POSITION_HISTORY_METRICS = [
-	"depositApy",
-	"borrowApy",
-	"dieselRate",
-	"supplied",
-	"borrowed",
-	"availableLiquidity"
-];
-/**
-* Every {@link StrategyPositionHistoryMetric}, for callers that enumerate them.
-**/
-const STRATEGY_POSITION_HISTORY_METRICS = [
-	"netApy",
-	"borrowApy",
-	"collateralApy",
-	"tvl",
-	"collateralPrice",
-	"collateralUsdPrice",
-	"underlyingUsdPrice"
-];
-//#endregion
-exports.POOL_HISTORY_METRICS = POOL_HISTORY_METRICS;
-exports.POOL_POSITION_HISTORY_METRICS = POOL_POSITION_HISTORY_METRICS;
-exports.STRATEGY_HISTORY_METRICS = STRATEGY_HISTORY_METRICS;
-exports.STRATEGY_POSITION_HISTORY_METRICS = STRATEGY_POSITION_HISTORY_METRICS;