@gearbox-protocol/sdk 16.0.0-next.5 → 16.0.0-next.50

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

@@ -1,7 +1,9 @@
 import { Bps } from "../../model/primitives.js";
 import { BorrowRateBreakdown, Position, StrategyPosition } from "../../model/positions.js";
+import { AccountMetrics, AccountProjection } from "../../model/previews.js";
+import { PositionWithdrawals } from "../../model/withdrawals.js";
 import "../../model/index.js";
-import { AccountSnapshot, ListPositionsProps, ListStrategyPositionsProps } from "./types.js";
+import { AccountSnapshot, GetCurrentWithdrawalsProps, ListPositionsProps, ListStrategyPositionsProps } from "./types.js";
 import { SDKConstruct } from "../base/SDKConstruct.js";
 import "../base/index.js";
 //#region src/onchain/positions/PositionsService.d.ts
@@ -40,6 +42,10 @@ declare class PositionsService extends SDKConstruct {
    * @param props - {@link ListStrategyPositionsProps}
    **/
   listStrategyPositions(props: ListStrategyPositionsProps): Promise<StrategyPosition[]>;
+  /**
+   * Returns delayed withdrawals of a strategy position
+   **/
+  getCurrentWithdrawals(props: GetCurrentWithdrawalsProps): Promise<PositionWithdrawals>;
   /**
    * Health factor of an account state, in basis points (`10000` = 1.0).
    **/
@@ -67,6 +73,43 @@ declare class PositionsService extends SDKConstruct {
    * non-underlying assets.
    **/
   liquidationPrice(snapshot: AccountSnapshot): bigint | null;
+  /**
+   * What the collateral {@link liquidationPrice} is quoted for costs in the
+   * market underlying right now, in the same `PRICE_DECIMALS` fixed point —
+   * the pair a form shows beside the liquidation price. `null` under exactly
+   * the conditions that leave the liquidation price `null`, plus an oracle
+   * that cannot answer for either side.
+   **/
+  currentPrice(snapshot: AccountSnapshot): bigint | null;
+  /**
+   * Every derived number of an account state at once — the whole
+   * {@link AccountMetrics} half of a projection.
+   *
+   * This is what both halves of the SDK fill their answers from: `prepare`, for
+   * a state it walked an intent into, and `preview`, for one it replayed out of
+   * calldata. One snapshot in, one set of metrics out, so the two descriptions
+   * of the same operation cannot disagree because one of them grew its own
+   * formula.
+   *
+   * Identical to the four methods above field for field, and cheaper than
+   * calling them one by one: the market data is collected once, and the health
+   * factor and borrow rate the time to liquidation decays at are the very ones
+   * reported beside it.
+   **/
+  metrics(snapshot: AccountSnapshot, options?: ProjectedPoolOptions): AccountMetrics;
+  /**
+   * A projected account state as both halves of the SDK report it: the holdings
+   * priced and named, and the metrics of {@link PositionsService.metrics}.
+   *
+   * The snapshot is taken at its word — what it lists is what comes back, so a
+   * caller that drops dust before the walk reports an account without it, and
+   * one that keeps wei reports them. That is the whole of the policy left to
+   * the caller; everything downstream of the balances is decided here.
+   *
+   * @param options - The operation's effect on the pool, for the rate the
+   * metrics are quoted at, see {@link ProjectedPoolOptions}.
+   **/
+  projection(snapshot: AccountSnapshot, options?: ProjectedPoolOptions): AccountProjection;
 }
 //#endregion
 export { PositionsService, ProjectedPoolOptions };

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

@@ -1,4 +1,6 @@
+import { AccountSnapshot } from "./types.js";
 import { CalcLiquidationPriceProps } from "./calcLiquidationPriceForTarget.js";
+import { Address } from "viem";
 //#region src/onchain/positions/calcLiquidationPrice.d.ts
 /**
  * Liquidation price of an account state's target collateral, in the oracle's
@@ -8,5 +10,12 @@ import { CalcLiquidationPriceProps } from "./calcLiquidationPriceForTarget.js";
  * holds exactly one non-dust non-underlying asset; otherwise `null`.
  **/
 declare function calcLiquidationPrice(props: CalcLiquidationPriceProps): bigint | null;
+/**
+ * The one collateral a liquidation price — and the current price beside it —
+ * can be quoted for: the account's single non-dust, non-underlying asset.
+ * `null` when it holds none or several, which is the case neither figure
+ * exists for.
+ **/
+declare function soleNonUnderlyingCollateral(snapshot: AccountSnapshot, underlying: Address): Address | null;
 //#endregion
-export { calcLiquidationPrice };
+export { calcLiquidationPrice, soleNonUnderlyingCollateral };

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

@@ -1,9 +1,9 @@
-import { AccountSnapshot, ListPositionsProps, ListPositionsPropsBase, ListStrategyPositionsProps, accountSnapshotFromCreditAccountData } from "./types.js";
+import { AccountSnapshot, GetCurrentWithdrawalsProps, GetCurrentWithdrawalsPropsBase, IMultichainPositionsService, 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 { calcLiquidationPrice, soleNonUnderlyingCollateral } from "./calcLiquidationPrice.js";
 import { calcTimeToLiquidationMs } from "./calcTimeToLiquidationMs.js";
 import { MultichainPositionsService } from "./MultichainPositionsService.js";
 import { PositionsService, ProjectedPoolOptions } from "./PositionsService.js";
-export { AccountSnapshot, CalcBorrowRateProps, CalcHealthFactorProps, CalcLiquidationPriceForTargetProps, CalcLiquidationPriceProps, ListPositionsProps, ListPositionsPropsBase, ListStrategyPositionsProps, MultichainPositionsService, PositionsService, ProjectedPoolOptions, accountSnapshotFromCreditAccountData, calcBorrowRate, calcHealthFactor, calcLiquidationPrice, calcLiquidationPriceForTarget, calcTimeToLiquidationMs };
+export { AccountSnapshot, CalcBorrowRateProps, CalcHealthFactorProps, CalcLiquidationPriceForTargetProps, CalcLiquidationPriceProps, GetCurrentWithdrawalsProps, GetCurrentWithdrawalsPropsBase, IMultichainPositionsService, ListPositionsProps, ListPositionsPropsBase, ListStrategyPositionsProps, MultichainPositionsService, PositionsService, ProjectedPoolOptions, accountSnapshotFromCreditAccountData, calcBorrowRate, calcHealthFactor, calcLiquidationPrice, calcLiquidationPriceForTarget, calcTimeToLiquidationMs, soleNonUnderlyingCollateral };

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

@@ -1,6 +1,9 @@
-import { PositionFilter } from "../../model/positions.js";
+import { ChainId } from "../../model/primitives.js";
+import { Position, PositionFilter } from "../../model/positions.js";
+import { DataResponse } from "../../model/response.js";
+import { PositionWithdrawals } from "../../model/withdrawals.js";
 import "../../model/index.js";
-import { WithBlock } from "../types/multichain.js";
+import { WithBlock, WithMultichain } from "../types/multichain.js";
 import { Asset, CreditAccountData } from "../base/types.js";
 import "../types/index.js";
 import "../base/index.js";
@@ -32,6 +35,47 @@ interface ListPositionsPropsBase {
  * {@link MultichainPositionsService.list}.
  **/
 type ListPositionsProps<Multichain extends boolean = false> = ListPositionsPropsBase & WithBlock<Multichain>;
+/**
+ * Chain-independent part of {@link GetCurrentWithdrawalsProps}.
+ *
+ * {@link GetCurrentWithdrawalsPropsBase.blockNumber} is kept on the
+ * multichain form because the method already targets a single chain.
+ **/
+interface GetCurrentWithdrawalsPropsBase {
+  /**
+   * Credit account whose delayed withdrawals to read.
+   **/
+  creditAccount: Address;
+  /**
+   * Credit manager the account belongs to.
+   *
+   **/
+  creditManager: Address;
+  /**
+   * Block to read at. Defaults to the latest block.
+   **/
+  blockNumber?: bigint;
+}
+/**
+ * Props for {@link PositionsService.getCurrentWithdrawals}.
+ **/
+type GetCurrentWithdrawalsProps<Multichain extends boolean = false> = GetCurrentWithdrawalsPropsBase & WithMultichain<Multichain, {
+  chainId: ChainId;
+}>;
+/**
+ * Cross-chain reads of the positions namespace: everything a wallet holds.
+ **/
+interface IMultichainPositionsService {
+  /**
+   * Positions of a wallet on all queried chains.
+   **/
+  list(props: ListPositionsProps<true>): Promise<DataResponse<Position[]>>;
+  /**
+   * Delayed withdrawals of one credit account, see
+   * {@link PositionsService.getCurrentWithdrawals}.
+   **/
+  getCurrentWithdrawals(props: GetCurrentWithdrawalsProps<true>): Promise<DataResponse<PositionWithdrawals>>;
+}
 /**
  * Props for {@link PositionsService.listStrategyPositions}.
  **/
@@ -86,4 +130,4 @@ interface AccountSnapshot {
  **/
 declare function accountSnapshotFromCreditAccountData(ca: CreditAccountData): AccountSnapshot;
 //#endregion
-export { AccountSnapshot, ListPositionsProps, ListPositionsPropsBase, ListStrategyPositionsProps, accountSnapshotFromCreditAccountData };
+export { AccountSnapshot, GetCurrentWithdrawalsProps, GetCurrentWithdrawalsPropsBase, IMultichainPositionsService, ListPositionsProps, ListPositionsPropsBase, ListStrategyPositionsProps, accountSnapshotFromCreditAccountData };

package/dist/types/onchain/utils/bigint-math.d.ts

@@ -37,6 +37,15 @@ declare class BigIntMath {
    * @returns A non-positive bigint representation of `a`.
    */
   static neg: (a: bigint) => bigint;
+  /**
+   * Divides rounding toward positive infinity.
+   *
+   * @param a - Dividend; must not be negative.
+   * @param b - Divisor; must be positive — zero throws, negative returns
+   * nonsense rather than the ceiling.
+   * @returns The smallest integer that is at least `a / b`.
+   **/
+  static ceilDiv: (a: bigint, b: bigint) => bigint;
 }
 //#endregion
 export { BigIntMath };

package/dist/types/onchain/utils/index.d.ts

@@ -7,6 +7,7 @@ import { bytes32ToString } from "./bytes32ToString.js";
 import { childLogger } from "./childLogger.js";
 import { createRawTx } from "./createRawTx.js";
 import { EtherscanURLParam, etherscanApiUrl, etherscanUrl } from "./etherscan.js";
+import { CallTrace, EXECUTE_BYTES_SELECTOR, collectTraces, findCallTo, findCallWithInput, findExecuteBytes, resolveProtocolCall } from "./trace.js";
 import { FilterDustUSDOptions, filterDust, filterDustUSD } from "./filterDust.js";
 import { fmtBinaryMask, formatBN, formatBNvalue, formatDuration, formatLeverage, formatNumberToString_, formatPercentage, formatTimestamp, numberWithCommas, percentFmt, rayToNumber, shortAddress, shortHash, toBN, toBigInt, toSignificant } from "./formatter.js";
 import { hexEq } from "./hex.js";
@@ -17,4 +18,4 @@ import { RetryOptions, retry } from "./retry.js";
 import { toAddress } from "./toAddress.js";
 import { PickSomeRequired } from "./type-utils.js";
 import { ZodAddress, ZodBigInt, ZodHex } from "./zod.js";
-export { AddressMap, AddressSet, AssetsMap, BigIntMath, EtherscanURLParam, FilterDustUSDOptions, IsDustOptions, Methods, PartialRecord, PickSomeRequired, RetryOptions, SupportedValue, TypedObjectUtils, ZodAddress, ZodBigInt, ZodHex, bytes32ToString, childLogger, createRawTx, etherscanApiUrl, etherscanUrl, filterDust, filterDustUSD, fmtBinaryMask, formatBN, formatBNvalue, formatDuration, formatLeverage, formatNumberToString_, formatPercentage, formatTimestamp, functionArgsToMap, functionArgsToRecord, getFunctionSignature, hexEq, isDust, json_parse, json_stringify, numberWithCommas, percentFmt, rayToNumber, retry, shortAddress, shortHash, toAddress, toBN, toBigInt, toSignificant };
+export { AddressMap, AddressSet, AssetsMap, BigIntMath, CallTrace, EXECUTE_BYTES_SELECTOR, EtherscanURLParam, FilterDustUSDOptions, IsDustOptions, Methods, PartialRecord, PickSomeRequired, RetryOptions, SupportedValue, TypedObjectUtils, ZodAddress, ZodBigInt, ZodHex, bytes32ToString, childLogger, collectTraces, createRawTx, etherscanApiUrl, etherscanUrl, filterDust, filterDustUSD, findCallTo, findCallWithInput, findExecuteBytes, fmtBinaryMask, formatBN, formatBNvalue, formatDuration, formatLeverage, formatNumberToString_, formatPercentage, formatTimestamp, functionArgsToMap, functionArgsToRecord, getFunctionSignature, hexEq, isDust, json_parse, json_stringify, numberWithCommas, percentFmt, rayToNumber, resolveProtocolCall, retry, shortAddress, shortHash, toAddress, toBN, toBigInt, toSignificant };

package/dist/types/{common-utils → onchain}/utils/trace.d.ts

@@ -1,5 +1,5 @@
 import { Address, Hex } from "viem";
-//#region src/common-utils/utils/trace.d.ts
+//#region src/onchain/utils/trace.d.ts
 /**
  * A single frame from Ethereum's `debug_traceTransaction` callTracer output.
  * Recursive: each frame may contain nested sub-calls.

package/dist/types/onchain/validation/checks.d.ts

@@ -0,0 +1,164 @@
+import { Bps, Token, TokenAmount } from "../../model/primitives.js";
+import { IGearboxError } from "../../model/errors.js";
+import { MalformedPreviewError } from "../../model/previews.js";
+import "../../model/index.js";
+import { BorrowLimitBinding, PreviewIssue } from "./refusal.js";
+import { Address } from "viem";
+//#region src/onchain/validation/checks.d.ts
+/**
+ * Every refusal the protocol can pass on an operation, as values.
+ *
+ * Each check is handed the numbers it compares — never a suite, a market or an
+ * SDK — so the engine, `checkOperation` and the strategy lists share one
+ * implementation.
+ *
+ * Ladders stay with the caller because they differ deliberately: the engine
+ * reports the tightest ceiling it found, the account-opening path the first one
+ * exceeded in its own order.
+ */
+/** A factor at or below this is refused; kept for the callers that size on it. */
+declare const MIN_HF_LIMITED = 10100n;
+/** The same bar as a `required` argument — the lowest factor that passes. */
+declare const MIN_HEALTH_FACTOR_FORM = 10101;
+/** The bar the facade itself enforces: an account may end exactly at 1.0. */
+declare const MIN_HEALTH_FACTOR_FACADE = 10000;
+/**
+ * The safe-price bar a form holds an account to. A step above the facade's,
+ * because a factor of exactly 1.0 at safe prices is already a refusal.
+ */
+declare const MIN_SAFE_HEALTH_FACTOR_FORM = 10001;
+/** A refusal names what a limit was measured in, never what it is worth. */
+declare function amountOf(token: Token, value: bigint): TokenAmount;
+/** The credit manager takes no multicall while it is paused. */
+declare function checkCreditManagerPaused(args: {
+  isPaused: boolean;
+  creditManager: Address;
+}): PreviewIssue | null;
+/** Past its expiration date the facade takes no more multicalls. */
+declare function checkMarketExpired(args: {
+  isExpired: boolean;
+  creditManager: Address;
+  /** Unix seconds, as the facade reports it. */
+  expirationDate: number;
+}): PreviewIssue | null;
+/** A paused pool neither takes deposits nor pays out. */
+declare function checkPoolPaused(args: {
+  isPaused: boolean;
+  pool: Address;
+}): PreviewIssue | null;
+/**
+ * A pool winding down still pays out, so only what puts money in is refused.
+ */
+declare function checkPoolSunset(args: {
+  isSunset: boolean;
+  isDeposit: boolean;
+  pool: Address;
+}): PreviewIssue | null;
+/**
+ * What the pool will hand over, against what is asked for.
+ *
+ * `binding` and `available` are the caller's answer to "which ceiling stands in
+ * the way", not this check's: see the ladder note above. `solutionAmount` is
+ * the largest position still openable, left out when none is.
+ */
+declare function checkBorrowLimit(args: {
+  requested: bigint;
+  available: bigint;
+  binding: BorrowLimitBinding;
+  underlying: Token;
+  solutionAmount?: bigint;
+}): PreviewIssue | null;
+/**
+ * What the pool can pay out, against what is being taken out.
+ *
+ * The operator is not `checkBorrowLimit`'s: a pool holding exactly the amount
+ * asked for still cannot serve it, so equality is already a refusal. That is
+ * the rule the legacy withdrawal validator enforced and it is preserved to the
+ * unit.
+ */
+declare function checkPoolPayout(args: {
+  requested: bigint;
+  available: bigint;
+  underlying: Token;
+}): PreviewIssue | null;
+/**
+ * A debt the facade would revert on.
+ *
+ * `allowZero` is the one place the two callers genuinely disagree: an account
+ * being adjusted may end owing nothing, while one being opened may not — so the
+ * exemption is stated rather than assumed.
+ */
+declare function checkDebtInBand(args: {
+  debt: bigint;
+  minDebt: bigint;
+  maxDebt: bigint;
+  underlying: Token;
+  allowZero: boolean;
+}): PreviewIssue | null;
+/** Leverage below 1x is not a position, it is a withdrawal. */
+declare function checkLeverageAtLeastOne(args: {
+  leverage: bigint;
+  min: bigint;
+}): PreviewIssue | null;
+/**
+ * The account against its debt, at whichever bar the caller holds it to.
+ *
+ * An unread factor counts as failing: a check that cannot see the number is not
+ * evidence that the number is fine.
+ */
+declare function checkCollateralised(args: {
+  healthFactor: Bps | undefined;
+  /** The lowest acceptable factor — a factor equal to it passes. */
+  required: Bps;
+  safePrices: boolean;
+  /**
+   * The factor the account stands at now. Given, an operation that raises it
+   * passes even from under the bar: an account already below is rescued by
+   * exactly the top-ups a flat bar would refuse.
+   */
+  improvesFrom?: Bps;
+}): PreviewIssue | null;
+/** A token the market will not let the account hold. */
+declare function checkForbiddenToken(args: {
+  token: Token;
+  isForbidden: boolean;
+}): PreviewIssue | null;
+/**
+ * The room the keeper still has for a token's quota, in the underlying.
+ *
+ * `requested` is absent for a token the market opened no quota for at all —
+ * nothing was weighed against a limit, the token simply counts as no collateral.
+ */
+declare function checkQuotaLimit(args: {
+  token: Token;
+  requested: bigint | undefined;
+  available: bigint;
+  underlying: Token;
+}): PreviewIssue | null;
+/** How many quoted tokens the facade enables at once. */
+declare function checkQuotaCount(args: {
+  count: number;
+  max: number;
+}): PreviewIssue | null;
+/** What the operation is funded from, against what is there. */
+declare function checkFunding(args: {
+  token: Token;
+  required: bigint;
+  held: bigint;
+}): PreviewIssue | null;
+/**
+ * The SDK could not replay the transaction.
+ *
+ * Only a {@link MalformedPreviewError} lands here. An `unpriceableToken`
+ * warning says the transaction is fine and the SDK could not fully evaluate
+ * it, which is a caveat on the numbers rather than a reason to refuse — it
+ * stays on the preview for the caller to surface.
+ */
+declare function checkPreviewError(warning: IGearboxError | undefined): PreviewIssue | null;
+/**
+ * Whether the preview warning means the transaction itself is malformed,
+ * rather than that only the evaluation was incomplete.
+ */
+declare function isMalformedPreviewError(warning: IGearboxError): warning is MalformedPreviewError;
+//#endregion
+export { MIN_HEALTH_FACTOR_FACADE, MIN_HEALTH_FACTOR_FORM, MIN_HF_LIMITED, MIN_SAFE_HEALTH_FACTOR_FORM, amountOf, checkBorrowLimit, checkCollateralised, checkCreditManagerPaused, checkDebtInBand, checkForbiddenToken, checkFunding, checkLeverageAtLeastOne, checkMarketExpired, checkPoolPaused, checkPoolPayout, checkPoolSunset, checkPreviewError, checkQuotaCount, checkQuotaLimit, isMalformedPreviewError };

package/dist/types/onchain/validation/index.d.ts

@@ -0,0 +1,4 @@
+import { BorrowLimitBinding, PreviewErrorDetails, PreviewErrorReason, PreviewIssue, PreviewRefusal, raise, refuse } from "./refusal.js";
+import { MIN_HEALTH_FACTOR_FACADE, MIN_HEALTH_FACTOR_FORM, MIN_HF_LIMITED, MIN_SAFE_HEALTH_FACTOR_FORM, amountOf, checkBorrowLimit, checkCollateralised, checkCreditManagerPaused, checkDebtInBand, checkForbiddenToken, checkFunding, checkLeverageAtLeastOne, checkMarketExpired, checkPoolPaused, checkPoolPayout, checkPoolSunset, checkPreviewError, checkQuotaCount, checkQuotaLimit, isMalformedPreviewError } from "./checks.js";
+import { toToken, toTokenAmount } from "./token.js";
+export { type BorrowLimitBinding, MIN_HEALTH_FACTOR_FACADE, MIN_HEALTH_FACTOR_FORM, MIN_HF_LIMITED, MIN_SAFE_HEALTH_FACTOR_FORM, type PreviewErrorDetails, type PreviewErrorReason, type PreviewIssue, type PreviewRefusal, amountOf, checkBorrowLimit, checkCollateralised, checkCreditManagerPaused, checkDebtInBand, checkForbiddenToken, checkFunding, checkLeverageAtLeastOne, checkMarketExpired, checkPoolPaused, checkPoolPayout, checkPoolSunset, checkPreviewError, checkQuotaCount, checkQuotaLimit, isMalformedPreviewError, raise, refuse, toToken, toTokenAmount };

package/dist/types/onchain/validation/refusal.d.ts

@@ -0,0 +1,242 @@
+import { Bps, Token, TokenAmount } from "../../model/primitives.js";
+import { MalformedPreviewError } from "../../model/previews.js";
+import "../../model/index.js";
+import { Address } from "viem";
+//#region src/onchain/validation/refusal.d.ts
+/**
+ * Why a preview could not be produced.
+ *
+ * Every member is raised by the engine as an {@link IntentPreviewError}, with
+ * the exception of `unsupportedTokenPair` and `noRecordedIntent`, which the
+ * prepare namespace reports for a request it can refuse before planning.
+ */
+type PreviewErrorReason =
+/** The debt the request implies falls outside the facade's band. */
+"debtOutOfRange" |
+/** The leverage asked for cannot be expressed as a plan at all. */
+"leverageOutOfRange" |
+/** Nothing on the account or in the wallet can fund what was asked. */
+"insufficientSourceBalance" |
+/** Input token is not accepted by the flow (e.g. deposit of a non-underlying). */
+"unsupportedCollateralToken" |
+/**
+ * No route for the trade the plan needs: no pool pair between the tokens
+ * requested, several and none was picked, or the pathfinder itself found no
+ * path for the amounts involved.
+ */
+"unsupportedTokenPair" |
+/**
+ * The intent cannot settle with a delay: the source has no redemption config,
+ * the chain has no compressor, or the payout is one the tail cannot serve.
+ */
+"noDelayedRoute" |
+/** Several redemption venues for the source, and nothing says which. */
+"multipleDelayedWithdrawals" |
+/** A redemption of the same asset is already in flight. */
+"withdrawalInProgress" |
+/**
+ * The claim names no operation to resume: requested without an intent, or
+ * read through a compressor too old to report one.
+ */
+"noRecordedIntent" |
+/** The facade or the pool behind it is paused: nothing can be done at all. */
+"marketPaused" |
+/** The facade is past its expiration date and takes no more multicalls. */
+"marketExpired" |
+/**
+ * The pool cannot lend what the plan draws right now — its free liquidity,
+ * the manager's debt limit or the per-block cap stands in the way.
+ */
+"insufficientPoolLiquidity" |
+/** The market takes no more quota for a token the plan wants to hold. */
+"quotaLimitReached" |
+/** The plan would increase the balance of a token the market forbids. */
+"forbiddenToken" |
+/**
+ * The account would end the transaction owing more than its collateral is
+ * worth under liquidation thresholds, which the facade refuses to allow.
+ */
+"insufficientCollateral" |
+/** The pool is winding down: it still pays out, but takes no more deposits. */
+"poolSunset" |
+/**
+ * The account would end up with more quoted tokens than the facade enables
+ * at once. A count, not an amount — unlike `quotaLimitReached`.
+ */
+"quotaCountExceeded" |
+/**
+ * The transaction could not be replayed: it is malformed, and every field
+ * derived from replayed balances is guesswork.
+ */
+"malformedTransaction";
+/**
+ * The numbers behind each refusal, so a caller reads the limit that was missed
+ * instead of re-deriving it.
+ *
+ * Anything with a token and an amount is a {@link TokenAmount}; ratios carry
+ * no token. `undefined` marks a reason raised from several places, only some of
+ * which hold the numbers.
+ */
+interface PreviewErrorDetails {
+  /** All three in the market's underlying. */
+  debtOutOfRange: {
+    requested: TokenAmount;
+    minDebt: TokenAmount;
+    maxDebt: TokenAmount;
+  };
+  /**
+   * Scaled by `LEVERAGE_DECIMALS` (`100n` = 1x), as the intent states it — not
+   * the read model's `Leverage`. `undefined` where the floor is not fixed: the
+   * deposit planner's is a function of the deposit.
+   */
+  leverageOutOfRange: {
+    requested: bigint;
+    min: bigint;
+  } | undefined;
+  /** `undefined` where the request never got as far as naming an amount. */
+  insufficientSourceBalance: {
+    required: TokenAmount;
+    held: TokenAmount;
+  } | undefined;
+  unsupportedCollateralToken: {
+    token: Token;
+  };
+  /**
+   * `to` is absent where the market named no output for `from`. The whole
+   * detail is absent only when the pathfinder reverted rather than answered.
+   */
+  unsupportedTokenPair: {
+    from: Token;
+    to: Token | undefined;
+  } | undefined;
+  noDelayedRoute: {
+    token: Token;
+  } | undefined;
+  multipleDelayedWithdrawals: {
+    token: Token;
+    venues: number;
+  };
+  /** The phantom token standing for the redemption already in flight. */
+  withdrawalInProgress: {
+    inFlight: TokenAmount;
+  };
+  noRecordedIntent: undefined;
+  /**
+   * Which contract is paused. A credit account operation names the manager, an
+   * LP operation the pool — the two are never both present.
+   */
+  marketPaused: {
+    creditManager: Address;
+  } | {
+    pool: Address;
+  };
+  /** `expirationDate` is unix seconds, as the facade reports it. */
+  marketExpired: {
+    creditManager: Address;
+    expirationDate: number;
+  };
+  /**
+   * Both in the market's underlying. `binding` names which of the four ceilings
+   * ran out first, so a caller can say what would fix it — waiting for lenders
+   * and asking governance are opposite answers. `solutionAmount` is the largest
+   * position still openable, absent when even the minimum debt does not fit.
+   */
+  insufficientPoolLiquidity: {
+    requested: TokenAmount;
+    available: TokenAmount;
+    binding: BorrowLimitBinding;
+    solutionAmount?: TokenAmount;
+  };
+  /**
+   * `token` is the one whose quota is asked for; the amounts are in the
+   * **underlying**, which is what a quota is measured in. `requested` is absent
+   * for a token the market opened no quota for at all — nothing was weighed
+   * against a limit.
+   */
+  quotaLimitReached: {
+    token: Token;
+    requested: TokenAmount | undefined;
+    available: TokenAmount;
+  };
+  forbiddenToken: {
+    token: Token;
+  };
+  /**
+   * `required` is the bar the factor was weighed against — the facade's own
+   * `1.0` for a check that asks whether the transaction lands, a form's higher
+   * bar for one that asks whether it is wise. `healthFactor` is the factor
+   * compared, which for a call that hands funds over is the safe-price one;
+   * `safePrices` says which, since a preview always reports main prices.
+   */
+  insufficientCollateral: {
+    healthFactor: Bps;
+    required: Bps;
+    safePrices: boolean;
+  };
+  poolSunset: {
+    pool: Address;
+  };
+  /** How many quoted tokens the account would end with, against the cap. */
+  quotaCountExceeded: {
+    count: number;
+    max: number;
+  };
+  /**
+   * The malformed-preview warning the SDK recorded, and its human-readable
+   * detail.
+   */
+  malformedTransaction: MalformedPreviewError;
+}
+/**
+ * Which ceiling ran out when a borrow could not be served.
+ *
+ * The names are the expressions, not the legacy labels, because the two do not
+ * line up: the legacy `insufficientDebtLimit` was the manager's own headroom
+ * (`managerDebtAvailable`), `insufficientPoolDebtLimit` was `poolDebtLimit`,
+ * and `insufficientPoolLiquidity` was what the manager could still draw
+ * (`poolAvailableLiquidity`).
+ *
+ * `borrowable()` weighs only three of these — the pool's free liquidity, the
+ * manager's remaining allowance and the facade's per-block cap. `poolDebtLimit`
+ * is read by the account-opening path alone, which is why it is not among them.
+ */
+type BorrowLimitBinding = "poolAvailableLiquidity" | "poolDebtLimit" | "managerDebtAvailable" | "facadePerBlockCap";
+/**
+ * The failure half every simulation shares.
+ *
+ * Distributed over the reasons rather than written as `{ reason; detail }`, so
+ * that narrowing on `reason` narrows `detail` with it.
+ */
+type PreviewIssue = { [R in PreviewErrorReason]: {
+  reason: R;
+  detail: PreviewErrorDetails[R];
+}; }[PreviewErrorReason];
+/**
+ * The failure half every simulation shares: an issue, plus the `ok: false`
+ * that tells it apart from a preview.
+ */
+type PreviewRefusal = {
+  ok: false;
+} & PreviewIssue;
+/** Builds the refusal a caller sees. */
+declare function refuse<R extends PreviewErrorReason>(reason: R, detail: PreviewErrorDetails[R]): PreviewRefusal;
+/**
+ * Validation failure that maps onto {@link PreviewErrorReason} rather than
+ * crashing the caller: raised by the planners and the guards, turned into
+ * `{ ok: false }` by `CreditAccountOperationsService`.
+ */
+declare class IntentPreviewError<R extends PreviewErrorReason = PreviewErrorReason> extends Error {
+  readonly reason: R;
+  readonly detail: PreviewErrorDetails[R];
+  constructor(reason: R, detail: PreviewErrorDetails[R], message?: string);
+}
+/**
+ * Throws the issue a check found, with the sentence the engine logs for it.
+ *
+ * Returns normally when there is nothing to raise, so it cannot narrow a type
+ * the way a bare `throw` does — a site that guards a value for the code below
+ * it keeps throwing directly.
+ */
+declare function raise(issue: PreviewIssue | null, message: string): void;
+//#endregion
+export { BorrowLimitBinding, IntentPreviewError, PreviewErrorDetails, PreviewErrorReason, PreviewIssue, PreviewRefusal, raise, refuse };

package/dist/types/onchain/validation/token.d.ts

@@ -0,0 +1,17 @@
+import { Token, TokenAmount } from "../../model/primitives.js";
+import "../../model/index.js";
+import { OnchainSDK } from "../OnchainSDK.js";
+import { Address } from "viem";
+//#region src/onchain/validation/token.d.ts
+/**
+ * The token behind an address, for the refusal details that inline one.
+ *
+ * A token the registry does not know falls back to its own shortened address
+ * as a symbol and `decimals: 0` — an unknown token has no scale, and guessing
+ * 18 would silently misformat every amount denominated in it.
+ */
+declare function toToken(sdk: OnchainSDK, address: Address): Token;
+/** {@link toToken} plus an amount denominated in it. */
+declare function toTokenAmount(sdk: OnchainSDK, address: Address, value: bigint): TokenAmount;
+//#endregion
+export { toToken, toTokenAmount };