@gearbox-protocol/sdk 14.12.0-next.65 → 14.12.0-next.67

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

@@ -0,0 +1,11 @@
+import { ChainId } from "./primitives.js";
+//#region src/model/positions.d.ts
+interface PositionFilter {
+  isZeroDebt?: boolean;
+  /**
+   * Keep only opportunities on these chains.
+   **/
+  chainIds?: ChainId[];
+}
+//#endregion
+export { PositionFilter };

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

@@ -0,0 +1,193 @@
+import { Address, Hex } from "viem";
+//#region src/model/primitives.d.ts
+/**
+ * EVM chain id.
+ *
+ * @example
+ * ```ts
+ * const mainnet: ChainId = 1;
+ * const arbitrum: ChainId = 42161;
+ * ```
+ **/
+type ChainId = number;
+/**
+ * Unix timestamp in seconds (not milliseconds).
+ *
+ * @example
+ * ```ts
+ * const t: Timestamp = 1719792000; // 2024-07-01T00:00:00Z
+ * ```
+ **/
+type Timestamp = number;
+/**
+ * Basis points: an integer where `10000` means 100%.
+ *
+ * Every percentage-like value of the read model — utilization, liquidation
+ * threshold, fees, premiums, APY and APR — uses this scale, which is also the
+ * scale the protocol itself stores (`PERCENTAGE_FACTOR`). Values are not
+ * clamped to `0..10000`: an APY can exceed 100%, so `12500` (125%) is valid.
+ *
+ * @example
+ * ```ts
+ * const full: Bps = 10000; // 100%
+ * const lt: Bps = 8600; // 86% liquidation threshold
+ * const apy: Bps = 512; // 5.12% APY
+ * const smallest: Bps = 1; // 0.01%
+ * ```
+ **/
+type Bps = number;
+/**
+ * Coarse denomination class of a token, used to group and filter opportunities
+ * by what they are ultimately priced in.
+ *
+ * This is not read from the chain: it comes from a hardcoded per-chain table
+ * and is maintained only for market underlyings, of which there are few.
+ *
+ * @example
+ * ```ts
+ * const usdc: AssetType = "Stable";
+ * const wsteth: AssetType = "ETH";
+ * ```
+ **/
+type AssetType = "Stable" | "ETH" | "BTC";
+/**
+ * Leverage as a plain multiplier, not a percentage and not in basis points.
+ *
+ * @example
+ * ```ts
+ * const x10: Leverage = 10; // 10x, the maximum at a 90% liquidation threshold
+ * const x1: Leverage = 1; // unleveraged
+ * ```
+ **/
+type Leverage = number;
+/**
+ * A token amount together with its USD valuation.
+ *
+ * The group that owns the field names the token (e.g. `totalBorrow` of an
+ * opportunity is denominated in its `underlyingToken`), so neither the symbol
+ * nor the decimals are repeated here.
+ *
+ * Both fields always come from the same source: a merged opportunity never has
+ * `value` from the chain and `valueUsd` from the backend.
+ *
+ * @example
+ * ```ts
+ * // 1500.5 USDC (6 decimals) worth $1500.50
+ * const amount: Amount = { value: 1_500_500_000n, valueUsd: 1500.5 };
+ * ```
+ **/
+interface Amount {
+  /**
+   * Amount in the base units of the owning group's token, i.e. scaled by
+   * `10 ** decimals`.
+   *
+   * @example `1_500_500_000n` for 1500.5 USDC
+   **/
+  value: bigint;
+  /**
+   * Value of {@link value} in US dollars as a plain float, or `null` when no
+   * price is available for the token.
+   *
+   * @example `1500.5`
+   **/
+  valueUsd: number | null;
+}
+/**
+ * An ERC-20 token as the read model describes it.
+ *
+ * Tokens are always fully inlined rather than referenced by address, so a row
+ * is renderable without a separate token dictionary.
+ **/
+interface Token {
+  /**
+   * Chain the token is deployed on.
+   *
+   * @example `1`
+   **/
+  chainId: ChainId;
+  /**
+   * Checksummed token address.
+   **/
+  address: Address;
+  /**
+   * Ticker symbol.
+   *
+   * @example `"USDC"`
+   **/
+  symbol: string;
+  /**
+   * Full token name.
+   *
+   * @example `"USD Coin"`
+   **/
+  name: string;
+  /**
+   * Number of decimals the token uses.
+   *
+   * @example `6` for USDC, `18` for WETH
+   **/
+  decimals: number;
+  /**
+   * Denomination class of the token, or `undefined` when the token is not
+   * classified.
+   *
+   * Only market underlyings are classified, so a collateral token normally
+   * leaves this unset. Absence means "unknown", never "neither of the three".
+   **/
+  assetType?: AssetType;
+}
+/**
+ * An {@link Amount} that names its own token.
+ **/
+interface TokenAmount extends Amount {
+  /**
+   * Token {@link Amount.value} is denominated in.
+   **/
+  token: Token;
+}
+/**
+ * The minimal transaction the read model hands out: enough to sign and send,
+ * with no ABI metadata attached.
+ **/
+interface TxCall {
+  /**
+   * Contract the transaction is sent to.
+   **/
+  to: Address;
+  /**
+   * Encoded calldata.
+   **/
+  callData: Hex;
+  /**
+   * Wei to send along. Omitted for a plain contract call.
+   *
+   * @example `1_000_000_000_000_000_000n` for 1 ETH
+   **/
+  value?: bigint;
+}
+/**
+ * The entity that curates a market: sets risk parameters, picks collateral and
+ * operates the market configurator.
+ **/
+interface Curator {
+  /**
+   * Address of the market configurator the curator operates. This is the
+   * on-chain identity of a curator, not a personal wallet.
+   **/
+  address: Address;
+  /**
+   * Display name.
+   *
+   * @example `"Chaos Labs"`
+   **/
+  name: string;
+  /**
+   * Link to the curator's page, or `null` when unknown. The chain knows no
+   * URLs, so this is `null` for anything served from the on-chain source.
+   *
+   * @mode offchain
+   **/
+  url: string | null;
+}
+//#endregion
+export { Amount, AssetType, Bps, ChainId, Curator, Leverage, Timestamp, Token, TokenAmount, TxCall };

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

@@ -0,0 +1,81 @@
+import { z } from "zod/v4";
+//#region src/model/primitives.schema.d.ts
+/**
+ * Runtime schemas for {@link ./primitives.js}.
+ *
+ * The hand-written types are the contract; these schemas exist so the offchain
+ * client can reject a backend response that no longer matches it. The two are
+ * kept in sync by the type-level tests in `model.test-d.ts`, not by inferring
+ * one from the other.
+ **/
+/**
+ * {@link ChainId}
+ **/
+declare const chainIdSchema: z.ZodNumber;
+/**
+ * {@link Timestamp}
+ **/
+declare const timestampSchema: z.ZodNumber;
+/**
+ * {@link Bps}. Integer, not bounded to `0..10000`: rates may exceed 100%.
+ **/
+declare const bpsSchema: z.ZodNumber;
+/**
+ * {@link AssetType}
+ **/
+declare const assetTypeSchema: z.ZodUnion<readonly [z.ZodLiteral<"Stable">, z.ZodLiteral<"ETH">, z.ZodLiteral<"BTC">]>;
+/**
+ * {@link Leverage}
+ **/
+declare const leverageSchema: z.ZodNumber;
+/**
+ * {@link Amount}
+ **/
+declare const amountSchema: z.ZodObject<{
+  value: z.ZodBigInt;
+  valueUsd: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * {@link Token}
+ **/
+declare const tokenSchema: z.ZodObject<{
+  chainId: z.ZodNumber;
+  address: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+  symbol: z.ZodString;
+  name: z.ZodString;
+  decimals: z.ZodNumber;
+  assetType: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"Stable">, z.ZodLiteral<"ETH">, z.ZodLiteral<"BTC">]>>;
+}, z.core.$strip>;
+/**
+ * {@link TokenAmount}
+ **/
+declare const tokenAmountSchema: z.ZodObject<{
+  value: z.ZodBigInt;
+  valueUsd: z.ZodNullable<z.ZodNumber>;
+  token: z.ZodObject<{
+    chainId: z.ZodNumber;
+    address: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    symbol: z.ZodString;
+    name: z.ZodString;
+    decimals: z.ZodNumber;
+    assetType: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"Stable">, z.ZodLiteral<"ETH">, z.ZodLiteral<"BTC">]>>;
+  }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * {@link TxCall}
+ **/
+declare const txCallSchema: z.ZodObject<{
+  to: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+  callData: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+  value: z.ZodOptional<z.ZodBigInt>;
+}, z.core.$strip>;
+/**
+ * {@link Curator}
+ **/
+declare const curatorSchema: z.ZodObject<{
+  address: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+  name: z.ZodString;
+  url: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+//#endregion
+export { amountSchema, assetTypeSchema, bpsSchema, chainIdSchema, curatorSchema, leverageSchema, timestampSchema, tokenAmountSchema, tokenSchema, txCallSchema };

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

@@ -0,0 +1,119 @@
+import { ILogger } from "../sdk/types/logger.js";
+import { ChainId } from "../model/primitives.js";
+import { NetworkType } from "../sdk/chain/chains.js";
+import { MultichainNetworkMeta } from "../sdk/types/multichain.js";
+import "../model/index.js";
+import { MultichainSDK } from "../sdk/MultichainSDK.js";
+import "../sdk/index.js";
+import { OffchainResult } from "../offchain/types.js";
+import { GearboxAPI } from "../offchain/GearboxAPI.js";
+import "../offchain/index.js";
+import { OffchainSourceStatus, ReadResult, SourceMeta } from "./types.js";
+//#region src/new-sdk/AbstractNamespace.d.ts
+/**
+ * What the on-chain source contributed, after per-chain failures have been
+ * turned into metadata.
+ *
+ * @internal
+ **/
+interface OnchainContribution<T> {
+  value?: T;
+  chains: MultichainNetworkMeta[];
+}
+/**
+ * What the off-chain source contributed, after a rejection has been turned into
+ * metadata.
+ *
+ * @internal
+ **/
+interface OffchainContribution<T> {
+  value?: T;
+  status?: OffchainSourceStatus;
+}
+/**
+ * How a read turns the two contributions into one payload. Either side is
+ * absent when its source was not asked, or was asked and failed.
+ *
+ * @internal
+ **/
+type CombineSources<T> = (onchain: T | undefined, offchain: T | undefined) => T;
+/**
+ * Shared machinery of every {@link GearboxSDK} namespace.
+ *
+ * A namespace is a stateless router: it asks the sources its mode allows, in
+ * parallel, merges what came back and reports what did not. This class owns
+ * that routing — per-chain failure capture, backend degradation, the response
+ * envelope and the all-sources-failed rule — so a namespace holds nothing but
+ * its reads and its merge policy.
+ *
+ * The sources are whatever it was handed, and their readiness is their owner's
+ * business: a source that is not ready to answer fails the read it was given,
+ * and that failure is reported like any other.
+ *
+ * All protocol knowledge lives in the sources: `MultichainSDK` for the chain,
+ * `GearboxAPI` for the backend. None of it is repeated here or in a subclass.
+ *
+ * @typeParam ListRow - Row type of the namespace's list read.
+ **/
+declare abstract class AbstractNamespace<ListRow extends object> {
+  #private;
+  protected readonly logger?: ILogger;
+  protected constructor(name: string, onchain: MultichainSDK | undefined, offchain: GearboxAPI | undefined, logger?: ILogger);
+  /**
+   * Per-field source policy for one row of this namespace.
+   **/
+  protected abstract mergeOne<T extends object>(onchain: T, offchain: T): T;
+  /**
+   * Union policy for this namespace's list read.
+   **/
+  protected abstract mergeList(onchain: ListRow[], offchain: ListRow[]): ListRow[];
+  /**
+   * Asks both sources in parallel and combines whatever answered.
+   *
+   * The action name is only used in diagnostics and in the error raised when
+   * every source the read had failed.
+   **/
+  protected read<T>(action: string, fromChain: (sdk: MultichainSDK) => Promise<OnchainContribution<T>>, fromBackend: (api: GearboxAPI) => Promise<OffchainResult<T>>, combine: CombineSources<T>): Promise<ReadResult<T>>;
+  /**
+   * Reads the namespace's list from both sources, unioned by
+   * {@link AbstractNamespace.mergeList}.
+   **/
+  protected readList(action: string, fromChain: (sdk: MultichainSDK) => Promise<OnchainContribution<ListRow[]>>, fromBackend: (api: GearboxAPI) => Promise<OffchainResult<ListRow[]>>): Promise<ReadResult<ListRow[]>>;
+  /**
+   * Reads one row from both sources and merges them under
+   * {@link AbstractNamespace.mergeOne}. The key names the chain, so the
+   * on-chain leg queries exactly one.
+   **/
+  protected readOne<T extends object>(action: string, chainId: ChainId, fromChain: (sdk: MultichainSDK) => Promise<T>, fromBackend: (api: GearboxAPI) => Promise<OffchainResult<T>>): Promise<ReadResult<T>>;
+  /**
+   * Reads something only the backend can answer.
+   *
+   * The fallback stands in for a backend that answered with nothing, which is
+   * a different thing from a backend that failed and was dropped.
+   **/
+  protected readOffchain<T>(action: string, fromBackend: (api: GearboxAPI) => Promise<OffchainResult<T>>, fallback: T): Promise<ReadResult<T>>;
+  /**
+   * Runs a read against the chain, or reports the chain as absent when the
+   * namespace has no on-chain source at all.
+   **/
+  protected fromChain<T>(run: (sdk: MultichainSDK) => Promise<OnchainContribution<T>>): Promise<OnchainContribution<T>>;
+  /**
+   * Runs a read against the backend, turning any rejection into metadata so
+   * that a dead backend degrades a `both`-mode read instead of failing it.
+   **/
+  protected fromBackend<T>(run: (api: GearboxAPI) => Promise<OffchainResult<T>>): Promise<OffchainContribution<T>>;
+  /**
+   * Runs a read against one chain, turning a rejection into that chain's
+   * metadata entry.
+   **/
+  protected onOneChain<T>(action: string, network: NetworkType, run: () => Promise<T>): Promise<OnchainContribution<T>>;
+  /**
+   * A read that reached at least one source returns what it has; a read where
+   * every source it had failed throws, because an empty result would otherwise
+   * be indistinguishable from "there is nothing here".
+   **/
+  protected assertAnySourceSucceeded(action: string, meta: SourceMeta): void;
+  protected networkOf(chainId: ChainId): NetworkType | undefined;
+}
+//#endregion
+export { AbstractNamespace, CombineSources, OffchainContribution, OnchainContribution };

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

@@ -0,0 +1,78 @@
+import { NetworkType } from "../sdk/chain/chains.js";
+import "../sdk/index.js";
+import { GearboxSDKOptions, Mode, OffchainByMode, OnchainByMode } from "./types.js";
+import { Opportunities } from "./opportunities/types.js";
+import "./opportunities/index.js";
+//#region src/new-sdk/GearboxSDK.d.ts
+/**
+ * Combined 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 exist,
+ * not what they return, so a screen written against `both` cannot silently
+ * degrade to a subset when someone reconfigures the SDK:
+ *
+ * ```ts
+ * const sdk = new GearboxSDK({
+ *   mode: "both",
+ *   networks: ["Mainnet"],
+ *   onchain: { chains: { Mainnet: { rpcURLs } } },
+ *   offchain: { baseUrl: "https://api.gearbox.fi" },
+ * });
+ * await sdk.attach();
+ *
+ * const { result, meta } = await sdk.opportunities.list({ kind: "strategy" });
+ * ```
+ *
+ * Every read answers with `{ result, meta }`: `meta` says which chains and
+ * which backend answered, because a partial answer is the normal case for a
+ * multi-chain read.
+ *
+ * @typeParam M - Mode the instance was built in.
+ **/
+declare class GearboxSDK<const M extends Mode = Mode> {
+  #private;
+  /**
+   * Sources this instance reads from.
+   **/
+  readonly mode: M;
+  /**
+   * Chains this instance covers. Authoritative even when an injected on-chain
+   * SDK covers a different set.
+   **/
+  readonly networks: readonly NetworkType[];
+  /**
+   * Namespace for pool and strategy opportunities.
+   **/
+  readonly opportunities: Opportunities<M>;
+  constructor(options: GearboxSDKOptions<M>);
+  /**
+   * Attaches the on-chain SDK when this instance owns one.
+   *
+   * Reads issued before this resolves still reach the chain and fail there, so
+   * in `both` mode they are served from the backend alone and report the chain
+   * as failed in their meta, rather than blocking.
+   *
+   * A no-op in `offchain` mode and when an already-attached SDK was injected.
+   **/
+  attach(): Promise<void>;
+  /**
+   * Whether the on-chain source is ready to be read from. Always `true` in
+   * `offchain` mode, where there is nothing to wait for.
+   **/
+  get attached(): boolean;
+  /**
+   * The underlying on-chain SDK, for everything this facade does not expose
+   * yet: markets, credit accounts, transaction building.
+   *
+   * `undefined` in `offchain` mode. Otherwise it exists from construction on,
+   * but only answers reads once {@link attach} has resolved.
+   **/
+  get onchain(): OnchainByMode[M];
+  /**
+   * The underlying backend client. `undefined` in `onchain` mode.
+   **/
+  get offchain(): OffchainByMode[M];
+}
+//#endregion
+export { GearboxSDK };

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

@@ -0,0 +1,9 @@
+import { AllSourcesFailedError, GearboxSDKOptions, Mode, OffchainByMode, OffchainSource, OffchainSourceStatus, OnchainByMode, OnchainSource, PlainMultichainSDKOptions, ReadResult, SourceMeta } from "./types.js";
+import { AbstractNamespace, CombineSources, OffchainContribution, OnchainContribution } from "./AbstractNamespace.js";
+import { Chart, ChartMetadata, HistoryReader } from "./utils/history.js";
+import "./utils/index.js";
+import { Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesOffchainOnly, OpportunitiesOnchainOnly } from "./opportunities/types.js";
+import { OpportunitiesNamespace } from "./opportunities/OpportunitiesNamespace.js";
+import "./opportunities/index.js";
+import { GearboxSDK } from "./GearboxSDK.js";
+export { AbstractNamespace, AllSourcesFailedError, Chart, ChartMetadata, CombineSources, GearboxSDK, GearboxSDKOptions, HistoryReader, Mode, OffchainByMode, OffchainContribution, OffchainSource, OffchainSourceStatus, OnchainByMode, OnchainContribution, OnchainSource, Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesNamespace, OpportunitiesOffchainOnly, OpportunitiesOnchainOnly, PlainMultichainSDKOptions, ReadResult, SourceMeta };

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

@@ -0,0 +1,69 @@
+import { ILogger } from "../../sdk/types/logger.js";
+import { Opportunity, OpportunityFilter, PoolOpportunityDetail, PoolOpportunityKey, PoolOpportunityRef, StrategyOpportunityDetail, StrategyOpportunityKey, StrategyOpportunityRef } from "../../model/opportunities.js";
+import { PoolHistoryMetric, StrategyHistoryMetric } from "../../model/history.js";
+import "../../model/index.js";
+import { MultichainSDK } from "../../sdk/MultichainSDK.js";
+import "../../sdk/index.js";
+import { GearboxAPI } from "../../offchain/GearboxAPI.js";
+import "../../offchain/index.js";
+import { ReadResult } from "../types.js";
+import { AbstractNamespace } from "../AbstractNamespace.js";
+import { HistoryReader } from "../utils/history.js";
+import "../utils/index.js";
+import { OpportunitiesBase, OpportunitiesOffchainOnly } from "./types.js";
+//#region src/new-sdk/opportunities/OpportunitiesNamespace.d.ts
+/**
+ * The `opportunities` namespace of the combined SDK.
+ *
+ * A stateless router over the two sources, see {@link AbstractNamespace} for
+ * the routing itself. What is specific to opportunities is the reads below and
+ * the merge policy at the bottom of the class.
+ *
+ * The class implements the methods of every mode; {@link GearboxSDK} exposes it
+ * as its mode's slice of {@link OpportunitiesByMode}, so calling a method the
+ * mode does not have is a compile error rather than a runtime one.
+ **/
+declare class OpportunitiesNamespace extends AbstractNamespace<Opportunity> implements OpportunitiesBase, OpportunitiesOffchainOnly {
+  #private;
+  constructor(onchain: MultichainSDK | undefined, offchain: GearboxAPI | undefined, logger?: ILogger);
+  /**
+   * {@inheritDoc OpportunitiesBase.list}
+   **/
+  list(filter?: OpportunityFilter): Promise<ReadResult<Opportunity[]>>;
+  /**
+   * {@inheritDoc OpportunitiesBase.getPool}
+   **/
+  getPool(key: PoolOpportunityKey): Promise<ReadResult<PoolOpportunityDetail>>;
+  /**
+   * {@inheritDoc OpportunitiesBase.getStrategy}
+   **/
+  getStrategy(key: StrategyOpportunityKey): Promise<ReadResult<StrategyOpportunityDetail>>;
+  /**
+   * {@inheritDoc OpportunitiesOffchainOnly.history}
+   **/
+  history(key: PoolOpportunityRef): HistoryReader<PoolHistoryMetric>;
+  history(key: StrategyOpportunityRef): HistoryReader<StrategyHistoryMetric>;
+  /**
+   * Merges the two versions of one opportunity.
+   *
+   * The chain wins every field it fills; the backend fills the rest and owns
+   * {@link OFFCHAIN_OWNED_FIELDS}.
+   *
+   * The rule is onchain-first, field-wise, and never deeper than one level: a
+   * group like `totalSupply` or `supplyApy` is taken whole from one source, so
+   * a row never mixes an on-chain token amount with a backend dollar value
+   * derived from a different block.
+   **/
+  protected mergeOne<T extends object>(onchain: T, offchain: T): T;
+  /**
+   * Unions the two lists by canonical opportunity id.
+   *
+   * Rows present in both are merged by {@link OpportunitiesNamespace.mergeOne}.
+   * Rows only the backend knows are appended: a chain the SDK does not cover,
+   * or a market it has not loaded, is a reason to show more rather than fewer
+   * opportunities.
+   **/
+  protected mergeList(onchain: Opportunity[], offchain: Opportunity[]): Opportunity[];
+}
+//#endregion
+export { OpportunitiesNamespace };

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

@@ -0,0 +1,3 @@
+import { Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesOffchainOnly, OpportunitiesOnchainOnly } from "./types.js";
+import { OpportunitiesNamespace } from "./OpportunitiesNamespace.js";
+export { Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesNamespace, OpportunitiesOffchainOnly, OpportunitiesOnchainOnly };

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

@@ -0,0 +1,66 @@
+import { Opportunity, OpportunityFilter, PoolOpportunityDetail, PoolOpportunityKey, PoolOpportunityRef, StrategyOpportunityDetail, StrategyOpportunityKey, StrategyOpportunityRef } from "../../model/opportunities.js";
+import { PoolHistoryMetric, StrategyHistoryMetric } from "../../model/history.js";
+import "../../model/index.js";
+import { Mode, ReadResult } from "../types.js";
+import { HistoryReader } from "../utils/history.js";
+//#region src/new-sdk/opportunities/types.d.ts
+/**
+ * Reads every mode supports, because either source alone can answer them.
+ **/
+interface OpportunitiesBase {
+  /**
+   * All pool and strategy opportunities, optionally narrowed.
+   *
+   * In `both` mode the two lists are unioned by canonical opportunity id and
+   * merged field-wise, with the chain winning any field both sources fill.
+   **/
+  list(filter?: OpportunityFilter): Promise<ReadResult<Opportunity[]>>;
+  /**
+   * Detailed view of one pool opportunity.
+   **/
+  getPool(key: PoolOpportunityKey): Promise<ReadResult<PoolOpportunityDetail>>;
+  /**
+   * Detailed view of one strategy opportunity.
+   **/
+  getStrategy(key: StrategyOpportunityKey): Promise<ReadResult<StrategyOpportunityDetail>>;
+}
+/**
+ * Reads only a backend can answer.
+ **/
+interface OpportunitiesOffchainOnly {
+  /**
+   * Historical charts of one opportunity, one metric and one range at a time:
+   * `history(key).chart("depositApy", "1m")`.
+   *
+   * The key's kind decides which metrics exist, so asking a pool for a
+   * strategy series does not compile.
+   *
+   * Absent in `onchain` mode: the chain serves the present, and rebuilding a
+   * series from it would mean an archive read per point.
+   **/
+  history(key: PoolOpportunityRef): HistoryReader<PoolHistoryMetric>;
+  history(key: StrategyOpportunityRef): HistoryReader<StrategyHistoryMetric>;
+}
+/**
+ * Reads only the chain can answer. Empty for now — every on-chain read the
+ * namespace exposes has a backend counterpart.
+ **/
+interface OpportunitiesOnchainOnly {}
+/**
+ * Which methods the `opportunities` namespace has in each mode.
+ *
+ * A lookup map rather than a conditional type: `both` is spelled out instead of
+ * being inferred, and a widened mode degrades to the intersection of what all
+ * modes offer rather than silently distributing into a union of everything.
+ **/
+interface OpportunitiesByMode {
+  onchain: OpportunitiesBase & OpportunitiesOnchainOnly;
+  offchain: OpportunitiesBase & OpportunitiesOffchainOnly;
+  both: OpportunitiesBase & OpportunitiesOffchainOnly & OpportunitiesOnchainOnly;
+}
+/**
+ * The `opportunities` namespace of a {@link GearboxSDK} in mode `M`.
+ **/
+type Opportunities<M extends Mode = Mode> = OpportunitiesByMode[M];
+//#endregion
+export { Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesOffchainOnly, OpportunitiesOnchainOnly };