@gearbox-protocol/sdk 15.0.1 → 15.1.0-next.10

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

@@ -0,0 +1,508 @@
+import { ClaimableWithdrawal } from "../../sdk/accounts/withdrawal-compressor/types.js";
+import { Asset } from "../../sdk/base/types.js";
+import { PoolOpportunityKey, StrategyOpportunityKey } from "../../model/opportunities.js";
+import { StrategyPositionKey } from "../../model/positions.js";
+import { DataResponse } from "../../model/response.js";
+import "../../model/index.js";
+import { MultiCall } from "../../sdk/types/transactions.js";
+import { PoolSimulation } from "../../sdk/pools/types.js";
+import { OpenStrategyPreview } from "../../sdk/accounts/intents/open-strategy.js";
+import { DelayedStart, OperationState, PreviewErrorReason, ResumableIntent, RouteRefusals } from "../../sdk/accounts/intents/types.js";
+import { AccountCalculatorOperation } from "../../sdk/accounts/intents/operations.js";
+import "../../sdk/index.js";
+import { Address } from "viem";
+//#region src/new-sdk/simulate/types.d.ts
+/**
+ * What a pool deposit or withdrawal would yield.
+ *
+ * Shaped like {@link StrategySimulate} so both kinds of simulation are consumed
+ * the same way, with the pool's own numbers as the preview: the ERC-4626
+ * conversion applied to the amount, at the rate of the block the market was
+ * loaded at.
+ **/
+type LpSimulate = {
+  ok: true;
+  /**
+   * Always empty: a pool operation is a single transaction, so there is no
+   * chain of steps to show. Present so callers can treat both simulations
+   * alike.
+   **/
+  operations: [];
+  /**
+   * What the wallet parts with and what it receives, plus the zapper the
+   * transaction goes through when one is involved.
+   **/
+  preview: PoolSimulation;
+  /**
+   * The transaction implementing the operation: exactly one, since a pool
+   * operation is a single call on the pool or on its zapper.
+   **/
+  calls: MultiCall[];
+} | {
+  ok: false;
+  reason: PreviewErrorReason;
+};
+/**
+ * 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.
+ **/
+type StrategySimulate = {
+  ok: true;
+  /**
+   * The logical steps, each carrying the amounts it was computed from.
+   * Useful for showing the user what will happen, and for pinning behaviour
+   * in tests.
+   **/
+  operations: AccountCalculatorOperation[];
+  /**
+   * Projected account state once the operations execute: TVL, debt,
+   * balances and quotas.
+   **/
+  preview: OperationState;
+  /**
+   * Credit-facade multicall implementing the operations, ready to be sent
+   * through `sdk.accounts`.
+   **/
+  calls: MultiCall[];
+} | {
+  ok: false;
+  reason: PreviewErrorReason;
+};
+/**
+ * What the leading half of a delayed operation would yield: the request
+ * transaction, plus what it recorded for the tail.
+ *
+ * Shaped like {@link StrategySimulate} with one field more, so the instant and
+ * the delayed route of the same request are compared side by side.
+ **/
+type DelayedStrategySimulate = {
+  ok: true;
+  /**
+   * {@inheritDoc StrategySimulate.operations}
+   **/
+  operations: AccountCalculatorOperation[];
+  /**
+   * State once the request executes: the source token is gone and the
+   * withdrawal position stands in its place, with debt untouched — the
+   * repayment belongs to the tail.
+   **/
+  preview: OperationState;
+  /**
+   * {@inheritDoc StrategySimulate.calls}
+   **/
+  calls: MultiCall[];
+  /**
+   * When the tail can be run, and what the request recorded for it, see
+   * {@link DelayedStart}.
+   **/
+  delayed: DelayedStart;
+} | {
+  ok: false;
+  reason: PreviewErrorReason;
+};
+/**
+ * What one of the two flows that sell a position asset —
+ * {@link OpportunitiesSimulate.withdrawStrategy} and
+ * {@link OpportunitiesSimulate.adjustLeverage} — would yield each way it can be
+ * served.
+ *
+ * Whether the account can sell that asset on the router, redeem it through its
+ * 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.
+ **/
+type StrategyRoutesSimulate = {
+  ok: true;
+  /**
+   * The router route: one transaction, settled on the spot. `undefined`
+   * when the asset cannot be sold, see `refused.instant`.
+   **/
+  instant: Extract<StrategySimulate, {
+    ok: true;
+  }> | undefined;
+  /**
+   * The request half of the redemption route, which
+   * {@link DelayedSimulate.finish} 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<DelayedStrategySimulate, {
+    ok: true;
+  }> | undefined;
+  /**
+   * Why a missing route was refused, see {@link RouteRefusals}.
+   **/
+  refused: RouteRefusals;
+} | {
+  ok: false;
+  /**
+   * 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.
+   **/
+  reason: PreviewErrorReason;
+  /**
+   * {@inheritDoc StrategyRoutesSimulate.refused}
+   **/
+  refused: RouteRefusals;
+};
+/**
+ * What opening a new leveraged position would yield.
+ *
+ * The only simulation that reports both an expected and a floor branch: opening
+ * takes both from a single pathfinder call, and `openCA` consumes both.
+ **/
+type OpenStrategySimulate = {
+  ok: true;
+  preview: OpenStrategyPreview;
+} | {
+  ok: false;
+  reason: PreviewErrorReason;
+};
+/**
+ * Shared knobs. Both default to the SDK's own defaults when omitted.
+ **/
+interface SimulateOptions {
+  /** Router slippage in PERCENTAGE_FORMAT (100% = 10_000). */
+  slippage?: number;
+  /**
+   * Extra quota headroom in PERCENTAGE_FORMAT, to survive price drift between
+   * the simulation and execution.
+   **/
+  quotaReserve?: number;
+}
+/**
+ * Position to simulate against. A `StrategyPosition` from
+ * `sdk.positions.list()` satisfies this, as does a bare key.
+ **/
+type PositionInput = StrategyPositionKey;
+/**
+ * Pool to simulate against. A `PoolOpportunity` from
+ * `sdk.opportunities.list()` satisfies this, as does a bare key.
+ **/
+type PoolInput = PoolOpportunityKey;
+/**
+ * Market to open a new position in. A `StrategyOpportunity` from
+ * `sdk.opportunities.list()` satisfies this, as does a bare key.
+ **/
+type StrategyInput = StrategyOpportunityKey;
+interface DepositStrategyParams extends SimulateOptions {
+  /**
+   * Collateral to add: the market underlying, or its unwrapped asset on an RWA
+   * market (USDC rather than dcUSDC).
+   **/
+  token: Address;
+  amount: bigint;
+  /** Native value to attach when paying a wrapped-native market in the coin. */
+  value?: bigint;
+  /**
+   * Token the position ends up in. Defaults to the account's most valuable
+   * non-phantom, non-underlying balance.
+   **/
+  positionToken?: Address;
+  /**
+   * Target total leverage scaled by `LEVERAGE_DECIMALS` (300n = 3x). Omit to
+   * keep the account's current leverage.
+   **/
+  targetLeverage?: bigint;
+}
+interface WithdrawStrategyParams extends SimulateOptions {
+  /**
+   * Amount the wallet receives, denominated in `tokenOut`. `MAX_UINT256`, or
+   * anything at or above the account's net value, turns the flow into an exit,
+   * see {@link OpportunitiesSimulate.withdrawStrategy}.
+   **/
+  amount: bigint;
+  /** Wallet receiving the payout. */
+  to: Address;
+  /**
+   * Token the wallet receives. Defaults to the market underlying, force-unwrapped
+   * to the RWA asset on an RWA market.
+   **/
+  tokenOut?: Address;
+  /**
+   * Token liquidated to fund the withdrawal. Defaults to the account's most
+   * valuable non-phantom balance.
+   **/
+  sourceToken?: Address;
+}
+interface RepayStrategyParams extends SimulateOptions {
+  /**
+   * Funding token: the market underlying, which needs no conversion and is
+   * repaid where it lands, or — on an RWA market — the unwrapped asset behind
+   * it (USDC rather than dcUSDC), which this flow wraps on the way in.
+   **/
+  token: Address;
+  /**
+   * Amount taken from the wallet. Anything above the outstanding debt settles
+   * it in full and stays on the account as collateral, so a caller clearing the
+   * account can add a buffer for the interest that accrues before the
+   * transaction lands, see {@link OpportunitiesSimulate.maxRepay}.
+   * `MAX_UINT256` settles the debt and sizes that buffer itself.
+   **/
+  amount: bigint;
+  /** Native value to attach when paying a wrapped-native market in the coin. */
+  value?: bigint;
+}
+interface AdjustLeverageParams extends SimulateOptions {
+  /**
+   * Target total leverage scaled by `LEVERAGE_DECIMALS` (300n = 3x); 100n means
+   * no debt.
+   **/
+  targetLeverage: bigint;
+  /**
+   * Position token to buy into or sell out of. Defaults to the account's most
+   * valuable non-phantom, non-underlying balance.
+   **/
+  token?: Address;
+}
+interface AddCollateralParams extends SimulateOptions {
+  /** Position token to deposit; nothing else is accepted. */
+  token: Address;
+  amount: bigint;
+  /** Native value to attach when paying a wrapped-native market in the coin. */
+  value?: bigint;
+}
+interface WithdrawCollateralParams extends SimulateOptions {
+  /** Token to move out; must already sit on the account. */
+  token: Address;
+  amount: bigint;
+  /** Wallet receiving the tokens. */
+  to: Address;
+}
+interface OpenStrategyParams extends SimulateOptions {
+  /** Collateral coming from the wallet, in their own tokens. */
+  collateral: Asset[];
+  /**
+   * Target total leverage scaled by `LEVERAGE_DECIMALS` (300n = 3x).
+   **/
+  leverage: bigint;
+  /**
+   * Token the position ends up in. Defaults to the opportunity's target
+   * collateral.
+   **/
+  targetToken?: Address;
+  /** Collateral to leave unswapped; everything else is routed into the target. */
+  leftoverBalances?: Asset[];
+}
+interface LpParams {
+  /**
+   * On deposit: amount of `tokenIn`. On withdraw: amount of `tokenOut`, which
+   * the pool's `withdraw` takes as is and prices in shares itself.
+   **/
+  amount: bigint;
+  /**
+   * Wallet funding the deposit or receiving the withdrawal. Required because it
+   * is baked into the calldata.
+   **/
+  wallet: Address;
+  /**
+   * Token the user parts with. Defaults to the pool underlying on deposit and to
+   * the pool shares on withdrawal.
+   **/
+  tokenIn?: Address;
+  /**
+   * Token the user receives. Defaults to the only route available for `tokenIn`;
+   * required when the pool offers several, otherwise the simulation reports
+   * `unsupportedTokenPair`.
+   **/
+  tokenOut?: Address;
+}
+/**
+ * Same shape as {@link LpParams}, but {@link OpportunitiesSimulate.redeem}
+ * treats `amount` as the pool shares to burn rather than the underlying to
+ * receive.
+ **/
+interface LpRedeemParams {
+  /**
+   * Amount of `tokenIn` — pool shares, or the zapper token that wraps them —
+   * to redeem.
+   **/
+  amount: bigint;
+  wallet: Address;
+  tokenIn?: Address;
+  tokenOut?: Address;
+}
+interface FinishDelayedParams extends SimulateOptions {
+  /**
+   * The matured withdrawal to claim, from
+   * `sdk.onchain.chain(chainId).withdrawalCompressor.getCurrentWithdrawals()`.
+   **/
+  claimable: ClaimableWithdrawal;
+  /**
+   * The operation to resume. Defaults to the one the request recorded in the
+   * withdrawal's `extraData`, which is what {@link ClaimableWithdrawal.intent}
+   * decodes; pass it explicitly when the compressor is too old to report it.
+   **/
+  intent?: ResumableIntent;
+}
+/**
+ * The delayed route of the two operations that can take it: a source that only
+ * redeems through its issuer — a Securitize dsToken, a Mellow share — instead of
+ * through the router.
+ *
+ * Two transactions rather than one: the request, then the tail once the
+ * redemption matures, which is days later. In between, nothing has to be kept on
+ * the client — the request writes the operation into the withdrawal's
+ * `extraData`, and reading the claimable decodes it back.
+ **/
+interface DelayedSimulate {
+  /**
+   * The delayed counterpart of {@link OpportunitiesSimulate.withdrawStrategy},
+   * on its own: that flow already quotes this route alongside the instant one,
+   * so reach for this when the delayed route is the only one of interest.
+   *
+   * Reports `noDelayedRoute` when the account has no redemption venue for the
+   * source at all.
+   **/
+  withdrawStrategy(position: PositionInput, params: WithdrawStrategyParams): Promise<DataResponse<DelayedStrategySimulate>>;
+  /**
+   * The delayed counterpart of {@link OpportunitiesSimulate.adjustLeverage} on
+   * its own, which only deleveraging reaches: raising leverage buys the position
+   * token and never redeems it. That flow already quotes this route alongside
+   * the instant one, so reach for this when it is the only one of interest.
+   **/
+  adjustLeverage(position: PositionInput, params: AdjustLeverageParams): Promise<DataResponse<DelayedStrategySimulate>>;
+  /**
+   * The tail: claim the matured withdrawal, then whatever the recorded
+   * operation still owes — repaying debt and paying the wallet out for a
+   * withdrawal, repaying alone for a deleveraging, nothing beyond the claim for
+   * the rest.
+   *
+   * Answers like the instant flows, so both halves are consumed the same way.
+   * Reports `noRecordedIntent` when the claim names no operation to resume.
+   **/
+  finish(position: PositionInput, params: FinishDelayedParams): Promise<DataResponse<StrategySimulate>>;
+}
+/**
+ * Simulations of everything a wallet can do to a pool or a credit account.
+ *
+ * On-chain only: every method reads live state and, for strategies, asks the
+ * pathfinder for real swap paths. Nothing is executed and nothing is signed —
+ * the result is the numbers plus the calldata that would produce them.
+ *
+ * Not to be confused with `src/preview/simulate`, which goes the other way: it
+ * takes calldata that already exists and reports what it would do.
+ **/
+interface OpportunitiesSimulate {
+  /**
+   * Depositing into a pool: underlying in, shares out.
+   *
+   * Synchronous, unlike every strategy simulation below: the answer is the
+   * pool's share rate applied to the amount, and that rate is already loaded.
+   **/
+  deposit(pool: PoolInput, params: LpParams): LpSimulate;
+  /**
+   * Taking underlying out of a pool: `amount` is the `tokenOut` the wallet
+   * wants back, and the pool burns whatever shares that costs.
+   *
+   * The LP counterpart of {@link withdrawStrategy} / {@link withdrawCollateral},
+   * which act on credit accounts.
+   **/
+  withdraw(pool: PoolInput, params: LpParams): LpSimulate;
+  /**
+   * Redeeming pool shares: `amount` is the `tokenIn` the wallet parts with,
+   * and the preview is the underlying it converts to.
+   **/
+  redeem(pool: PoolInput, params: LpRedeemParams): LpSimulate;
+  /**
+   * 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<OpenStrategySimulate>>;
+  /**
+   * 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<StrategySimulate>>;
+  /**
+   * Shrinking a position: part of its net value goes to the wallet and debt is
+   * repaid in the same proportion, so leverage is unchanged.
+   *
+   * 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 StrategyRoutesSimulate}.
+   *
+   * `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
+   * many-to-one route, the debt is settled in full and every balance left goes
+   * to `to`. `tokenOut` is ignored, since the proceeds are already the
+   * underlying (unwrapped on an RWA market). The account stays open with
+   * nothing on it. An exit has no delayed route.
+   *
+   * @see withdrawCollateral to move an asset out without touching debt, which
+   * raises leverage instead.
+   **/
+  withdrawStrategy(position: PositionInput, params: WithdrawStrategyParams): Promise<DataResponse<StrategyRoutesSimulate>>;
+  /**
+   * Largest partial withdrawal {@link withdrawStrategy} accepts, in underlying
+   * units: the amount whose proportional repayment leaves the debt at the
+   * credit manager's `minDebt`. Between this and the account's net value the
+   * flow refuses — the leftover loan would sit below `minDebt` — and at the net
+   * value it turns into an exit.
+   *
+   * Taking everything out needs none of this arithmetic: send `MAX_UINT256` to
+   * {@link withdrawStrategy} and the exit is what runs.
+   **/
+  maxWithdraw(position: PositionInput): Promise<DataResponse<bigint>>;
+  /**
+   * 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
+   * rises. The flow to reach for when a position is close to liquidation.
+   *
+   * A partial repayment is two calls and nothing else: the funding lands and
+   * the debt shrinks, quotas untouched — they still back a loan.
+   *
+   * A repayment that covers the whole debt clears the account's quotas with it,
+   * which the facade requires of a loan going to zero, and asks for the full
+   * outstanding amount, so nothing is left owing because interest moved between
+   * this simulation and the transaction. `MAX_UINT256` is how to ask for that
+   * settlement without naming a figure: the wallet is charged the debt plus a
+   * 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<StrategySimulate>>;
+  /**
+   * 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.
+   **/
+  maxRepay(position: PositionInput): Promise<DataResponse<bigint>>;
+  /**
+   * Retargeting leverage at fixed collateral: debt moves, own funds do not.
+   *
+   * Answers with both routes, like {@link withdrawStrategy}, since deleveraging
+   * sells the position token and may only be able to redeem it. Raising leverage
+   * buys instead, so there the delayed route is always absent with
+   * `refused.delayed: "noDelayedRoute"`.
+   **/
+  adjustLeverage(position: PositionInput, params: AdjustLeverageParams): Promise<DataResponse<StrategyRoutesSimulate>>;
+  /**
+   * 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<StrategySimulate>>;
+  /**
+   * Moving one asset that already sits on the account out to the wallet, at
+   * fixed debt — so TVL falls and leverage rises.
+   *
+   * @see withdrawStrategy for the deleveraging withdrawal, which repays debt in
+   * proportion and leaves leverage unchanged.
+   **/
+  withdrawCollateral(position: PositionInput, params: WithdrawCollateralParams): Promise<DataResponse<StrategySimulate>>;
+  /**
+   * The same requests routed through a delayed redemption instead of the
+   * router, and the tail that finishes them, see {@link DelayedSimulate}.
+   **/
+  readonly delayed: DelayedSimulate;
+}
+//#endregion
+export { AddCollateralParams, AdjustLeverageParams, DelayedSimulate, DelayedStrategySimulate, DepositStrategyParams, FinishDelayedParams, LpParams, LpRedeemParams, LpSimulate, OpenStrategyParams, OpenStrategySimulate, OpportunitiesSimulate, PoolInput, PositionInput, RepayStrategyParams, SimulateOptions, StrategyInput, StrategyRoutesSimulate, StrategySimulate, WithdrawCollateralParams, WithdrawStrategyParams };

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

@@ -0,0 +1,130 @@
+import { ILogger } from "../sdk/types/logger.js";
+import { ChainId } from "../model/primitives.js";
+import { NetworkType } from "../sdk/chain/chains.js";
+import { Notice, NoticeSubject } from "../model/notices.js";
+import { DataResponse } from "../model/response.js";
+import "../model/index.js";
+import { MultichainAttachOptions, MultichainSDK, MultichainSDKOptions } from "../sdk/MultichainSDK.js";
+import "../sdk/index.js";
+import { GearboxAPIOptions } from "../offchain/types.js";
+import { GearboxAPI } from "../offchain/GearboxAPI.js";
+import "../offchain/index.js";
+//#region src/new-sdk/types.d.ts
+/**
+ * Which sources a {@link GearboxSDK} reads from, and therefore which of its
+ * methods exist.
+ **/
+type Mode = "onchain" | "offchain" | "both";
+/**
+ * On-chain source of a {@link GearboxSDK}: either an SDK to reuse, which its
+ * owner keeps attaching itself, or the options to build one with.
+ **/
+type OnchainSource = MultichainSDK | PlainMultichainSDKOptions;
+/**
+ * {@link MultichainSDKOptions} without plugin typing.
+ **/
+type PlainMultichainSDKOptions = MultichainSDKOptions<{}>;
+/**
+ * Off-chain source of a {@link GearboxSDK}: either a client to reuse or the
+ * options to build one with. The chains come from
+ * {@link GearboxSDKOptions.networks} either way.
+ **/
+type OffchainSource = GearboxAPI | Omit<GearboxAPIOptions, "chainIds">;
+/**
+ * Options for creating a {@link GearboxSDK}.
+ *
+ * @typeParam M - Mode, which decides which sources are required.
+ **/
+interface GearboxSDKOptions<M extends Mode = Mode> {
+  /**
+   * Sources to read from, see {@link Mode}.
+   **/
+  mode: M;
+  /**
+   * Chains the SDK covers, which every read of every source is scoped to. An
+   * injected source covering a different set is rejected at construction.
+   **/
+  networks: NetworkType[];
+  /**
+   * On-chain source. Required in `onchain` and `both` mode.
+   **/
+  onchain?: OnchainSource;
+  /**
+   * Off-chain source. Required in `offchain` and `both` mode.
+   **/
+  offchain?: OffchainSource;
+  /**
+   * How many seconds the backend may lag the chain and still serve a chain in
+   * `both` mode, see {@link DEFAULT_MAX_OFFCHAIN_LAG}.
+   **/
+  maxOffchainLagSeconds?: number;
+  /**
+   * How old the loaded on-chain state may be, in seconds, before a read syncs
+   * the chains it touches first, see {@link DEFAULT_MAX_STATE_AGE}. A read
+   * inside the window is served from loaded state.
+   **/
+  maxStateAgeSeconds?: number;
+  /**
+   * Options passed to {@link MultichainSDK.attach}, used only when the SDK
+   * builds the on-chain source itself.
+   **/
+  attach?: MultichainAttachOptions;
+  logger?: ILogger;
+}
+/**
+ * What a namespace asks of the on-chain state before it reads it: attached,
+ * and no older than the SDK's `maxStateAgeSeconds` on the chains the read
+ * touches. Owned by {@link GearboxSDK}, which shares one attach and one
+ * in-flight sync per chain across every namespace.
+ *
+ * @internal
+ **/
+type EnsureFreshChains = (chainIds?: readonly ChainId[]) => Promise<void>;
+/**
+ * What a {@link GearboxSDK} hands every namespace it builds.
+ **/
+interface NamespaceOptions {
+  /**
+   * How far the backend may lag the chain, see
+   * {@link GearboxSDKOptions.maxOffchainLagSeconds}.
+   **/
+  maxOffchainLagSeconds: number;
+  /**
+   * Awaited before every on-chain leg of an async read, see
+   * {@link EnsureFreshChains}. Absent when the SDK reads no chain.
+   **/
+  ensureFresh?: EnsureFreshChains;
+  logger?: ILogger;
+}
+/**
+ * On-chain escape hatch per mode: absent when the SDK reads no chain.
+ *
+ * @internal
+ **/
+interface OnchainByMode {
+  onchain: MultichainSDK;
+  offchain: undefined;
+  both: MultichainSDK;
+}
+/**
+ * `sdk.notices` per mode: a backend read, absent when the SDK reads no backend.
+ *
+ * @internal
+ **/
+interface NoticesByMode {
+  onchain: undefined;
+  offchain: (subject: NoticeSubject) => Promise<DataResponse<Notice[]>>;
+  both: (subject: NoticeSubject) => Promise<DataResponse<Notice[]>>;
+}
+/**
+ * Off-chain escape hatch per mode: absent when the SDK reads no backend.
+ *
+ * @internal
+ **/
+interface OffchainByMode {
+  onchain: undefined;
+  offchain: GearboxAPI;
+  both: GearboxAPI;
+}
+//#endregion
+export { EnsureFreshChains, GearboxSDKOptions, Mode, NamespaceOptions, NoticesByMode, OffchainByMode, OffchainSource, OnchainByMode, OnchainSource, PlainMultichainSDKOptions };

package/dist/types/new-sdk/utils/filterResponse.d.ts

@@ -0,0 +1,19 @@
+import { ChainScopedFilter } from "../../model/filters.js";
+import { DataResponse } from "../../model/response.js";
+import "../../model/index.js";
+import { FilterResult } from "./types.js";
+//#region src/new-sdk/utils/filterResponse.d.ts
+/**
+ * Narrows an already-read list, rows and metadata alike. `undefined` passes
+ * through, so a read still in flight stays that way, and an envelope narrows to
+ * an envelope, see {@link FilterResult}.
+ *
+ * @typeParam T - Row type.
+ * @typeParam F - Filter type.
+ * @typeParam R - What the response was given as.
+ * @param matches - Whether one row satisfies the filter, e.g.
+ *   `matchesOpportunityFilter`.
+ **/
+declare function filterResponse<T, F extends ChainScopedFilter, R extends DataResponse<T[]> | undefined>(response: R, filter: F | undefined, matches: (row: T, filter?: F) => boolean): FilterResult<R, T>;
+//#endregion
+export { filterResponse };

package/dist/types/new-sdk/utils/index.d.ts

@@ -0,0 +1,4 @@
+import { EntityMerger, FilterResult, ListMerger, MergeListResult } from "./types.js";
+import { filterResponse } from "./filterResponse.js";
+import { DEFAULT_MAX_OFFCHAIN_LAG, mergeChainList, mergeChainOne } from "./mergeChains.js";
+export { DEFAULT_MAX_OFFCHAIN_LAG, type EntityMerger, type FilterResult, type ListMerger, type MergeListResult, filterResponse, mergeChainList, mergeChainOne };

package/dist/types/new-sdk/utils/mergeChains.d.ts

@@ -0,0 +1,22 @@
+import { ChainScoped, DataResponse } from "../../model/response.js";
+import "../../model/index.js";
+import { MergeListResult } from "./types.js";
+//#region src/new-sdk/utils/mergeChains.d.ts
+/**
+ * How many seconds the backend may lag the chain and still be used.
+ **/
+declare const DEFAULT_MAX_OFFCHAIN_LAG = 120;
+/**
+ * Merges two lists chain by chain: a chain is served by the backend when it is
+ * within `maxLagSeconds` of the chain, by the chain otherwise, and reported as
+ * an error when neither source succeeded. Answers with an envelope as soon as
+ * either side has arrived, see {@link MergeListResult}.
+ **/
+declare function mergeChainList<T extends ChainScoped, Onchain extends DataResponse<T[]> | undefined, Offchain extends DataResponse<T[]> | undefined>(onchain: Onchain, offchain: Offchain, maxLagSeconds?: number): MergeListResult<Onchain, Offchain, T[]>;
+/**
+ * Merges two versions of one entity under the same freshness rule as
+ * {@link mergeChainList}, returning the winning response whole.
+ **/
+declare function mergeChainOne<T>(onchain: DataResponse<T> | undefined, offchain: DataResponse<T> | undefined, maxLagSeconds?: number): DataResponse<T> | undefined;
+//#endregion
+export { DEFAULT_MAX_OFFCHAIN_LAG, mergeChainList, mergeChainOne };