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

package/dist/types/model/previews.d.ts

@@ -0,0 +1,470 @@
+import { Bps, ChainId, Leverage, TokenAmount } from "./primitives.js";
+import { DelayedIntent } from "./delayed-intents.js";
+import { BorrowRateBreakdown } from "./positions.js";
+import { Address, Hex } from "viem";
+//#region src/model/previews.d.ts
+/**
+ * ERC4626 pool operation kind, as surfaced on a {@link PoolOperationPreview}.
+ **/
+type PoolOperationType = "Deposit" | "Mint" | "Withdraw" | "Redeem";
+/**
+ * Raw-calldata operation to preview: the chain and the transaction fields.
+ * The on-chain SDK is resolved from {@link chainId} by the caller.
+ **/
+interface PreviewOperationInput {
+  /**
+   * Chain the transaction is sent on.
+   **/
+  chainId: ChainId;
+  /**
+   * Contract address that was called.
+   **/
+  to: Address;
+  /**
+   * Raw calldata of the operation.
+   **/
+  calldata: Hex;
+  /**
+   * Transaction sender.
+   **/
+  sender: Address;
+  /**
+   * Transaction `msg.value`, required for native-token zapper deposits.
+   **/
+  value?: bigint;
+}
+/**
+ * Options for previewing a raw operation.
+ **/
+interface PreviewOperationOptions {
+  /**
+   * Block to read/simulate at; defaults to latest. Only set for testnet
+   * forks.
+   **/
+  blockNumber?: bigint;
+}
+/**
+ * Broken `storeExpectedBalances`/`compareBalances` bracket structure:
+ * `storeExpectedBalances` without a matching `compareBalances`, nested
+ * brackets, or `compareBalances` without a preceding `storeExpectedBalances`.
+ * We expect transactions that were generated by our frontend using router/withdrawal compressor
+ **/
+declare const ERROR_MALFORMED_BRACKET = 1001;
+/**
+ * Adapter call outside a `storeExpectedBalances`/`compareBalances` bracket
+ * We expect transactions that were generated by our frontend using router/withdrawal compressor,
+ **/
+declare const ERROR_ADAPTER_CALL_OUTSIDE_BRACKET = 1002;
+/**
+ * Bracketed call whose target is not an adapter (or adapter that is not known to the SDK)
+ **/
+declare const ERROR_NON_ADAPTER_CALL_IN_BRACKET = 1003;
+/**
+ * Bracketed adapter call cannot be replayed (undecodable/unsupported calldata)
+ **/
+declare const ERROR_UNPREVIEWABLE_ADAPTER_CALL = 1004;
+/**
+ * Out-of-bracket RWA wrap/unwrap calldata cannot be decoded
+ **/
+declare const ERROR_UNPREVIEWABLE_RWA_WRAP_UNWRAP = 1005;
+/**
+ * `msg.value` does not fit into the declared WETH collateral
+ * Transactions can have arbitrary value, but the ones that we create
+ * using our frontend should have a value that fits into the declared WETH collateral.
+ **/
+declare const ERROR_INVALID_TRANSACTION_VALUE = 1006;
+/** A token in the preview could not be priced by the oracle */
+declare const ERROR_UNPRICEABLE_TOKEN = 2001;
+/**
+ * Non-throwing preview failure. When set on a preview, all fields are still
+ * computed best-effort, but some of them may be unreliable.
+ */
+interface OperationPreviewError {
+  /**
+   * Numeric http-style error code, see the `ERROR_*` constants:
+   * - 1xxx: the transaction is malformed (we expect transactions
+   *   that were generated by our fromtend using router/withdrawal compressor)
+   *   and fields derived from replayed balances
+   *   may be unreliable;
+   * - 2xxx: the transaction may be fine, but the SDK could not fully
+   *   evaluate the preview (e.g. a token could not be priced).
+   */
+  code: number;
+  /**
+   * Human-readable details of the specific failure
+   */
+  message: string;
+}
+interface PoolOperationPreview {
+  operation: PoolOperationType;
+  /**
+   * Pool address
+   */
+  pool: Address;
+  /**
+   * Human-readable pool name
+   */
+  name: string;
+  /**
+   * Token that goes from user to pool
+   * In case of deposit, underlying for direct deposit, zapper input for zapper-routed deposit
+   * In case of withdraw, pool shares (diesel token) for direct withdraw or zapper token out
+   *
+   * For mint/withdraw the amount of tokenIn cannot be determined from
+   * transaction calldata alone and requires an additional async call
+   * (previewMint/previewWithdraw).
+   */
+  tokenIn: TokenAmount;
+  /**
+   * Token that goes from pool to user
+   * In case of deposit, pool shares (diesel token) for direct deposit or zapper token out
+   * In case of withdraw, underlying for direct withdraw or zapper token in
+   *
+   * For deposit/redeem the amount of tokenOut cannot be determined from
+   * transaction calldata alone and requires an additional async call
+   * (previewDeposit/previewRedeem).
+   */
+  tokenOut: TokenAmount;
+  /**
+   * Diesel rate of the pool: underlying per 1 diesel share, RAY-scaled
+   * (`1e27`).
+   */
+  shareRate: bigint;
+  /**
+   * Set when preview encountered non-fatal errors, all fields are
+   * still computed best-effort
+   */
+  error?: OperationPreviewError;
+}
+interface OpenCreditAccountPreview {
+  operation: "OpenCreditAccount" | "RWAOpenCreditAccount";
+  /**
+   * Health factor in basis points: below `10000` the account is liquidatable.
+   *
+   * @example `12500` for a health factor of 1.25
+   **/
+  healthFactor: Bps;
+  /**
+   * Cost of the debt, broken down by source.
+   **/
+  borrowRate: BorrowRateBreakdown;
+  /**
+   * Estimated milliseconds until the health factor decays to `10000` under
+   * the current borrow rate, or `null` when the debt carries no rate (or the
+   * account is already liquidatable).
+   **/
+  timeToLiquidation: bigint | null;
+  /**
+   * Price of the single non-underlying collateral at which the account
+   * becomes liquidatable, in the oracle's 8-decimal fixed point, or `null`
+   * when the account holds zero or several non-underlying assets.
+   **/
+  liquidationPrice: bigint | null;
+  /**
+   * Total-value leverage: `totalValue / (totalValue − totalDebt)`. `1` =
+   * unleveraged; `0` if underwater.
+   **/
+  leverage: Leverage;
+  /**
+   * Credit manager the account is opened in
+   */
+  creditManager: Address;
+  /**
+   * Human-readable credit manager name
+   */
+  name: string;
+  /**
+   * Target token of strategy: the first quoted token, with its balance taken
+   * from `assets`. Undefined when nothing is quoted.
+   */
+  target?: TokenAmount;
+  /**
+   * Tokens that were added as collateral during account opening.
+   *
+   * When the transaction has native value attached, it is represented as a
+   * `NATIVE_ADDRESS` entry, with the wrapped native token amount reduced
+   * accordingly (omitted entirely when it reaches zero).
+   */
+  collateral: TokenAmount[];
+  /**
+   * Sum of collateral tokens in underlying
+   */
+  collateralValue: bigint;
+  /**
+   * Total account value after opening: collateral plus borrowed amount, in
+   * underlying.
+   */
+  totalValue: bigint;
+  /**
+   * Borrowed amount in underlying
+   */
+  debt: bigint;
+  /**
+   * WARNING: unlike every other `TokenAmount` in this model, `value` is
+   * denominated in the market underlying, NOT in `token`. `token` only
+   * identifies which collateral the quota applies to; `valueUsd` prices the
+   * underlying amount.
+   *
+   * Desired quotas
+   */
+  quotas: TokenAmount[];
+  /**
+   * Minimum amount of assets on credit account after it's opened,
+   * as estimated by router
+   */
+  assets: TokenAmount[];
+  /**
+   * Set when preview encountered non-fatal errors, all fields are
+   * still computed best-effort, but derived fields (`assets`, `target`,
+   * `collateralValue`) may be unreliable in that case.
+   */
+  error?: OperationPreviewError;
+}
+interface AdjustCreditAccountPreview {
+  operation: "AdjustCreditAccount";
+  /**
+   * Health factor in basis points: below `10000` the account is liquidatable.
+   *
+   * @example `12500` for a health factor of 1.25
+   **/
+  healthFactor: Bps;
+  /**
+   * Cost of the debt, broken down by source.
+   **/
+  borrowRate: BorrowRateBreakdown;
+  /**
+   * Estimated milliseconds until the health factor decays to `10000` under
+   * the current borrow rate, or `null` when the debt carries no rate (or the
+   * account is already liquidatable).
+   **/
+  timeToLiquidation: bigint | null;
+  /**
+   * Price of the single non-underlying collateral at which the account
+   * becomes liquidatable, in the oracle's 8-decimal fixed point, or `null`
+   * when the account holds zero or several non-underlying assets.
+   **/
+  liquidationPrice: bigint | null;
+  /**
+   * Total-value leverage: `totalValue / (totalValue − totalDebt)`. `1` =
+   * unleveraged; `0` if underwater.
+   **/
+  leverage: Leverage;
+  /**
+   * Credit manager the account is opened in
+   */
+  creditManager: Address;
+  /**
+   * Human-readable credit manager name
+   */
+  name: string;
+  /**
+   * Credit account that is being adjusted
+   */
+  creditAccount: Address;
+  /**
+   * Tokens that were added as collateral during account opening.
+   *
+   * When the transaction has native value attached, it is represented as a
+   * `NATIVE_ADDRESS` entry, with the wrapped native token amount reduced
+   * accordingly (omitted entirely when it reaches zero).
+   */
+  collateralAdded: TokenAmount[];
+  /**
+   * Tokens that were withdrawn as collateral during account adjustment.
+   */
+  collateralWithdrawn: TokenAmount[];
+  /**
+   * Sum of collateral tokens in underlying
+   */
+  totalValue: bigint;
+  /**
+   * What the account owes in underlying once the operation lands: principal
+   * plus accrued interest and fees, which is the amount it would take to
+   * settle the loan — the same quantity `prepare` projects as `accountDebt`.
+   */
+  debt: bigint;
+  /**
+   * Debt after minus debt before. A repayment settles interest and fees
+   * before principal, so this is the payment itself rather than the part of
+   * it the principal happened to absorb.
+   */
+  debtChange: bigint;
+  /**
+   * WARNING: unlike every other `TokenAmount` in this model, `value` is
+   * denominated in the market underlying, NOT in `token`. `token` only
+   * identifies which collateral the quota applies to; `valueUsd` prices the
+   * underlying amount.
+   *
+   * Desired quotas
+   */
+  quotas: TokenAmount[];
+  /**
+   * WARNING: unlike every other `TokenAmount` in this model, `value` is
+   * denominated in the market underlying, NOT in `token`. `token` only
+   * identifies which collateral the quota applies to; `valueUsd` prices the
+   * underlying amount.
+   *
+   * Quotas after minus quotas before
+   */
+  quotasChange: TokenAmount[];
+  /**
+   * Minimum amount of assets on credit account after the operation,
+   * as estimated by router
+   */
+  assets: TokenAmount[];
+  /**
+   * Assets after minus assets before
+   */
+  assetsChange: TokenAmount[];
+  /**
+   * Intent of the delayed withdrawal this transaction claims; set when the
+   * multicall claims a delayed withdrawal
+   */
+  intent?: DelayedIntent;
+  /**
+   * Set when preview encountered non-fatal errors, all fields are
+   * still computed best-effort, but derived fields (`assets`, `assetsChange`,
+   * `totalValue`) may be unreliable in that case.
+   */
+  error?: OperationPreviewError;
+}
+interface CloseCreditAccountPreview {
+  operation: "CloseCreditAccount";
+  /**
+   * True when the account is closed permanently (facade `closeCreditAccount`
+   * entry point), false when the debt is zeroed but the account stays open
+   * (plain multicall).
+   */
+  permanent: boolean;
+  /**
+   * Credit manager the account belongs to
+   */
+  creditManager: Address;
+  /**
+   * Human-readable credit manager name
+   */
+  name: string;
+  /**
+   * Credit account that is being closed
+   */
+  creditAccount: Address;
+  /**
+   * Token withdrawn to the user and its minimal guaranteed amount, from the
+   * multicall replay (all collateral is swapped into the received token
+   * before withdrawal). The token is the market underlying or, on RWA
+   * markets, the unwrapped RWA underlying (the ERC4626 vault asset the
+   * underlying share converts 1:1 into)
+   */
+  receivedAmount: TokenAmount;
+  /**
+   * Intent of the delayed withdrawal this transaction claims; set when the
+   * multicall claims a delayed withdrawal
+   */
+  intent?: DelayedIntent;
+  /**
+   * Set when preview encountered non-fatal errors, all fields are
+   * still computed best-effort, but the
+   * balance-derived `receivedAmount` may be unreliable in that case.
+   */
+  error?: OperationPreviewError;
+}
+interface RepayCreditAccountPreview {
+  operation: "RepayCreditAccount";
+  /**
+   * True when the account is closed permanently (facade `closeCreditAccount`
+   * entry point), false when the debt is zeroed but the account stays open
+   * (plain multicall).
+   */
+  permanent: boolean;
+  /**
+   * Credit manager the account belongs to
+   */
+  creditManager: Address;
+  /**
+   * Human-readable credit manager name
+   */
+  name: string;
+  /**
+   * Credit account that is being repaid
+   */
+  creditAccount: Address;
+  /**
+   * Tokens added from the wallet to cover the debt (`addCollateral` calls).
+   *
+   * When the transaction has native value attached, it is represented as a
+   * `NATIVE_ADDRESS` entry, with the wrapped native token amount reduced
+   * accordingly (omitted entirely when it reaches zero).
+   */
+  collateralAdded: TokenAmount[];
+  /**
+   * Tokens returned to the user in-kind (`withdrawCollateral` calls, with the
+   * MAX_UINT256 sentinel resolved against replayed balances)
+   */
+  collateralWithdrawn: TokenAmount[];
+  /**
+   * Total debt repaid: principal + accrued interest + fees, in underlying
+   */
+  debtRepaid: bigint;
+  /**
+   * Intent of the delayed withdrawal this transaction claims; set when the
+   * multicall claims a delayed withdrawal
+   */
+  intent?: DelayedIntent;
+  /**
+   * Set when preview encountered non-fatal errors, all fields are
+   * still computed best-effort, but the
+   * balance-derived `collateralWithdrawn` may be unreliable in that case.
+   */
+  error?: OperationPreviewError;
+}
+/**
+ * Preview of the "instant" part of an operation on an existing credit
+ * account: what the transaction does in the same block, before any delayed
+ * withdrawal is claimed.
+ */
+type InstantOperationPreview = AdjustCreditAccountPreview | CloseCreditAccountPreview | RepayCreditAccountPreview;
+/**
+ * Preview of a multicall that requests a delayed withdrawal (e.g. Securitize
+ * redemption): the source token is spent now and a withdrawal phantom token is received;
+ * the actual claim token materializes later, when the withdrawal is claimed and
+ * the recorded (if any) is resumed
+ */
+interface DelayedCreditAccountOperationPreview {
+  operation: "DelayedCreditAccountOperation";
+  /**
+   * Credit account the operation is performed on
+   */
+  creditAccount: Address;
+  /**
+   * Credit manager the account belongs to
+   */
+  creditManager: Address;
+  /**
+   * Human-readable credit manager name
+   */
+  name: string;
+  /**
+   * Decoded from the withdrawal request's extraData; undefined when the
+   * request carries no intent (e.g. Mellow)
+   */
+  intent?: DelayedIntent;
+  /**
+   * What this transaction does right now: the delayed withdrawal is
+   * represented by the phantom token among the account's assets
+   */
+  instantPreview: InstantOperationPreview;
+  /**
+   * Best-effort state after the withdrawal is claimed and the intent is
+   * resumed; claim-only (phantom burned, claim token received) when
+   * `intent` is undefined
+   */
+  delayedPreview: InstantOperationPreview;
+}
+/**
+ * Result of previewing a raw operation calldata: currently pool operations and
+ * credit account opening, adjustment, closure, repayment and delayed
+ * withdrawal operations are supported.
+ */
+type OperationPreview = PoolOperationPreview | OpenCreditAccountPreview | AdjustCreditAccountPreview | CloseCreditAccountPreview | RepayCreditAccountPreview | DelayedCreditAccountOperationPreview;
+//#endregion
+export { AdjustCreditAccountPreview, CloseCreditAccountPreview, DelayedCreditAccountOperationPreview, ERROR_ADAPTER_CALL_OUTSIDE_BRACKET, ERROR_INVALID_TRANSACTION_VALUE, ERROR_MALFORMED_BRACKET, ERROR_NON_ADAPTER_CALL_IN_BRACKET, ERROR_UNPREVIEWABLE_ADAPTER_CALL, ERROR_UNPREVIEWABLE_RWA_WRAP_UNWRAP, ERROR_UNPRICEABLE_TOKEN, InstantOperationPreview, OpenCreditAccountPreview, OperationPreview, OperationPreviewError, PoolOperationPreview, PoolOperationType, PreviewOperationInput, PreviewOperationOptions, RepayCreditAccountPreview };

package/dist/types/model/primitives.d.ts

@@ -62,6 +62,20 @@ type AssetType = "Stable" | "ETH" | "BTC";
  * ```
  **/
 type Leverage = number;
+/**
+ * A token address paired with a balance, used throughout the SDK to
+ * represent holdings, collateral inputs, and leftover targets.
+ **/
+interface Asset {
+  /**
+   * ERC-20 token address.
+   **/
+  token: Address;
+  /**
+   * Token amount in the token's native decimals.
+   **/
+  balance: bigint;
+}
 /**
  * A token amount together with its USD valuation.
  *
@@ -114,6 +128,10 @@ interface Token {
   /**
    * Ticker symbol.
    *
+   * Display ticker, not necessarily the on-chain ERC-20 `symbol()`. The SDK
+   * may rewrite it (curated pretty names, `"source -> target"` for redemption
+   * phantom tokens).
+   *
    * @example `"USDC"`
    **/
   symbol: string;
@@ -168,4 +186,4 @@ interface TxCall {
   value?: bigint;
 }
 //#endregion
-export { Amount, AssetType, Bps, ChainId, Leverage, Timestamp, Token, TokenAmount, TxCall };
+export { Amount, Asset, AssetType, Bps, ChainId, Leverage, Timestamp, Token, TokenAmount, TxCall };

package/dist/types/new-sdk/AbstractNamespace.d.ts

@@ -1,7 +1,8 @@
 import { ILogger } from "../sdk/types/logger.js";
+import { ChainId } from "../model/primitives.js";
 import { DataResponse } from "../model/response.js";
 import "../model/index.js";
-import { NamespaceOptions } from "./types.js";
+import { EnsureFreshChains, NamespaceOptions } from "./types.js";
 import { EntityMerger, ListMerger } from "./utils/types.js";
 import "./utils/index.js";
 //#region src/new-sdk/AbstractNamespace.d.ts
@@ -17,6 +18,11 @@ interface MergedQuery<Onchain, Offchain, T> {
   fromChain: (source: Onchain) => Promise<DataResponse<T>>;
   fromBackend: (source: Offchain) => Promise<DataResponse<T>>;
   merge: ListMerger<T> | EntityMerger<T>;
+  /**
+   * Chains the on-chain leg touches, so only they are revalidated before it;
+   * omitted when the read fans out to every chain.
+   **/
+  chainIds?: readonly ChainId[];
 }
 /**
  * Base class of every {@link GearboxSDK} namespace: holds the two source
@@ -33,9 +39,16 @@ declare abstract class AbstractNamespace<Onchain, Offchain> {
    **/
   protected readonly maxOffchainLagSeconds: number;
   protected readonly logger?: ILogger;
+  /**
+   * The SDK's loading policy, awaited before every on-chain leg: attached, and
+   * the touched chains no older than the SDK allows.
+   **/
+  protected readonly ensureFresh?: EnsureFreshChains;
   protected constructor(name: string, onchain: Onchain | undefined, offchain: Offchain | undefined, options: NamespaceOptions);
   /**
-   * The on-chain source namespace on its own. Throws
+   * The on-chain source namespace on its own — every read of it attaches and
+   * revalidates like a merged read does, so a consumer showing the two sources
+   * separately still gets the SDK's loading policy. Throws
    * {@link SourceUnavailableError} in `offchain` mode.
    **/
   get onchain(): Onchain;

package/dist/types/new-sdk/GearboxSDK.d.ts

@@ -1,11 +1,20 @@
 import { NetworkType } from "../sdk/chain/chains.js";
 import "../sdk/index.js";
-import { GearboxSDKOptions, Mode, OffchainByMode, OnchainByMode } from "./types.js";
+import { GearboxSDKOptions, Mode, NoticesByMode, OffchainByMode, OnchainByMode } from "./types.js";
+import { LiquidationsByMode } from "./liquidations/types.js";
+import "./liquidations/index.js";
 import { Opportunities } from "./opportunities/types.js";
 import "./opportunities/index.js";
 import { Positions } from "./positions/types.js";
 import "./positions/index.js";
+import { PreviewByMode } from "./preview/types.js";
+import "./preview/index.js";
 //#region src/new-sdk/GearboxSDK.d.ts
+/**
+ * Default {@link GearboxSDKOptions.maxStateAgeSeconds}: the fastest poll an
+ * app runs, so a 30 s tick sees state no older than itself.
+ **/
+declare const DEFAULT_MAX_STATE_AGE = 30;
 /**
  * Entry point over both sources of Gearbox data: the chain and the Gearbox
  * backend. The {@link Mode} is fixed at construction and decides which methods
@@ -43,6 +52,25 @@ declare class GearboxSDK<const M extends Mode = Mode> {
    * Namespace for the positions a wallet holds.
    **/
   readonly positions: Positions<M>;
+  /**
+   * Namespace for liquidatable credit accounts and delayed-withdrawal
+   * positions a liquidator holds. Onchain-only, hence gated by mode like
+   * every other chain read: absent in `offchain` mode.
+   **/
+  readonly liquidations: LiquidationsByMode[M];
+  /**
+   * Namespace for on-chain previews of raw operation calldata. Onchain-only,
+   * hence gated by mode like every other chain read: absent in `offchain`
+   * mode.
+   **/
+  readonly preview: PreviewByMode[M];
+  /**
+   * The banners the backend attaches to a pool opportunity or a strategy
+   * position, see {@link Notice}. Top-level because the subject is either
+   * kind of entity, so neither namespace owns it. Backend-only, hence gated
+   * by mode like every other backend read: absent in `onchain` mode.
+   **/
+  readonly notices: NoticesByMode[M];
   constructor(options: GearboxSDKOptions<M>);
   /**
    * Attaches the on-chain SDK when this instance owns one; a no-op in `offchain`
@@ -66,4 +94,4 @@ declare class GearboxSDK<const M extends Mode = Mode> {
   get offchain(): OffchainByMode[M];
 }
 //#endregion
-export { GearboxSDK };
+export { DEFAULT_MAX_STATE_AGE, GearboxSDK };

package/dist/types/new-sdk/errors/SourceChainMismatchError.d.ts

@@ -1,7 +1,7 @@
 import { ChainId } from "../../model/primitives.js";
-import { NetworkType } from "../../sdk/chain/chains.js";
 import { DataSource } from "../../model/response.js";
 import "../../model/index.js";
+import { NetworkType } from "../../sdk/chain/chains.js";
 import "../../sdk/index.js";
 import { BaseError } from "viem";
 //#region src/new-sdk/errors/SourceChainMismatchError.d.ts