@gearbox-protocol/sdk 18.1.0 → 18.2.0-next.10

package/dist/types/onchain/market/adapters/types.d.ts

@@ -15,7 +15,7 @@ export interface IAdapterContract extends IBaseContract {
   openingCalls(): Promise<MultiCall[]>;
 }
 export type VersionedAbi = Record<number, readonly AbiParameter[]>;
-export type AdapterContractType = "ADAPTER::ACCOUNT_MIGRATOR" | "ADAPTER::BALANCER_V3_ROUTER" | "ADAPTER::BALANCER_V3_WRAPPER" | "ADAPTER::CAMELOT_V3_ROUTER" | "ADAPTER::CURVE_STABLE_NG" | "ADAPTER::CURVE_V1_2ASSETS" | "ADAPTER::CURVE_V1_3ASSETS" | "ADAPTER::CURVE_V1_4ASSETS" | "ADAPTER::CURVE_V1_STECRV_POOL" | "ADAPTER::CVX_V1_BASE_REWARD_POOL" | "ADAPTER::CVX_V1_BOOSTER" | "ADAPTER::DAI_USDS_EXCHANGE" | "ADAPTER::ERC4626_VAULT" | "ADAPTER::ERC4626_VAULT_REFERRAL" | "ADAPTER::FLUID_DEX" | "ADAPTER::INFINIFI_GATEWAY" | "ADAPTER::INFINIFI_UNWINDING" | "ADAPTER::KELP_DEPOSIT_POOL" | "ADAPTER::KELP_WITHDRAWAL" | "ADAPTER::LIDO_V1" | "ADAPTER::LIDO_WSTETH_V1" | "ADAPTER::MELLOW_CLAIMER" | "ADAPTER::MELLOW_DVV" | "ADAPTER::MELLOW_ERC4626_VAULT" | "ADAPTER::MELLOW_WRAPPER" | "ADAPTER::MIDAS_GATEWAY" | "ADAPTER::MIDAS_ISSUANCE_VAULT" | "ADAPTER::MIDAS_REDEMPTION_VAULT" | "ADAPTER::PENDLE_ROUTER" | "ADAPTER::SECURITIZE_ONRAMP" | "ADAPTER::SECURITIZE_REDEMPTION" | "ADAPTER::STAKING_REWARDS" | "ADAPTER::TRADERJOE_ROUTER" | "ADAPTER::UNISWAP_V2_ROUTER" | "ADAPTER::UNISWAP_V3_ROUTER" | "ADAPTER::UNISWAP_V4_GATEWAY" | "ADAPTER::UPSHIFT_VAULT" | "ADAPTER::VELODROME_V2_ROUTER";
+export type AdapterContractType = "ADAPTER::ACCOUNT_MIGRATOR" | "ADAPTER::BALANCER_V3_ROUTER" | "ADAPTER::BALANCER_V3_WRAPPER" | "ADAPTER::CAMELOT_V3_ROUTER" | "ADAPTER::CURVE_STABLE_NG" | "ADAPTER::CURVE_V1_2ASSETS" | "ADAPTER::CURVE_V1_3ASSETS" | "ADAPTER::CURVE_V1_4ASSETS" | "ADAPTER::CURVE_V1_STECRV_POOL" | "ADAPTER::CVX_V1_BASE_REWARD_POOL" | "ADAPTER::CVX_V1_BOOSTER" | "ADAPTER::DAI_USDS_EXCHANGE" | "ADAPTER::ERC4626_VAULT" | "ADAPTER::ERC4626_VAULT_REFERRAL" | "ADAPTER::FLUID_DEX" | "ADAPTER::INFINIFI_GATEWAY" | "ADAPTER::INFINIFI_UNWINDING" | "ADAPTER::KELP_DEPOSIT_POOL" | "ADAPTER::KELP_WITHDRAWAL" | "ADAPTER::LIDO_V1" | "ADAPTER::LIDO_WSTETH_V1" | "ADAPTER::MELLOW_CLAIMER" | "ADAPTER::MELLOW_DVV" | "ADAPTER::MELLOW_ERC4626_VAULT" | "ADAPTER::MELLOW_WRAPPER" | "ADAPTER::MIDAS_GATEWAY" | "ADAPTER::MIDAS_ISSUANCE_VAULT" | "ADAPTER::MIDAS_REDEMPTION_VAULT" | "ADAPTER::PENDLE_ROUTER" | "ADAPTER::SECURITIZE_ONRAMP" | "ADAPTER::SECURITIZE_REDEMPTION" | "ADAPTER::STAKING_REWARDS" | "ADAPTER::TRADERJOE_ROUTER" | "ADAPTER::TREEHOUSE_FASTLANE" | "ADAPTER::TREEHOUSE_GATEWAY" | "ADAPTER::TREEHOUSE_ROUTER" | "ADAPTER::UNISWAP_V2_ROUTER" | "ADAPTER::UNISWAP_V3_ROUTER" | "ADAPTER::UNISWAP_V4_GATEWAY" | "ADAPTER::UPSHIFT_VAULT" | "ADAPTER::VELODROME_V2_ROUTER";
 export declare enum AdapterType {
   ACCOUNT_MIGRATOR = "ACCOUNT_MIGRATOR",
   BALANCER_V3_ROUTER = "BALANCER_V3_ROUTER",
@@ -50,6 +50,9 @@ export declare enum AdapterType {
   SECURITIZE_REDEMPTION = "SECURITIZE_REDEMPTION",
   STAKING_REWARDS = "STAKING_REWARDS",
   TRADERJOE_ROUTER = "TRADERJOE_ROUTER",
+  TREEHOUSE_FASTLANE = "TREEHOUSE_FASTLANE",
+  TREEHOUSE_GATEWAY = "TREEHOUSE_GATEWAY",
+  TREEHOUSE_ROUTER = "TREEHOUSE_ROUTER",
   UNISWAP_V2_ROUTER = "UNISWAP_V2_ROUTER",
   UNISWAP_V3_ROUTER = "UNISWAP_V3_ROUTER",
   UNISWAP_V4_GATEWAY = "UNISWAP_V4_GATEWAY",

package/dist/types/permissionless/api/GearboxPermissionless.d.ts

@@ -1,4 +1,5 @@
 import { GearboxPermissionlessOptions } from "./types.js";
+import { PermissionlessAnalytics } from "./analytics/PermissionlessAnalytics.js";
 import { AttachChainsArgs } from "./chains/types.js";
 import { ChainsNamespace } from "./chains/ChainsNamespace.js";
 import { PermissionlessDeploy } from "./deploy/PermissionlessDeploy.js";
@@ -26,11 +27,11 @@ import { InstanceOwnerTransactions } from "./transactions/InstanceOwnerTransacti
  * const store = await permissionless.oracles.store({ chainId: chain.chainId });
  * ```
  *
- * Only what needs a server goes to one. {@link chains} and {@link oracles}
- * are the backend's reads; {@link deploy} and {@link transactions} read the
- * target chain directly, because everything they answer is derived from there
- * and a round trip would only move the derivation further from the wallet
- * that has to sign for it.
+ * Only what needs a server goes to one. {@link chains}, {@link oracles} and
+ * {@link analytics} are the backend's reads; {@link deploy} and
+ * {@link transactions} read the target chain directly, because everything
+ * they answer is derived from there and a round trip would only move the
+ * derivation further from the wallet that has to sign for it.
  **/
 export declare class GearboxPermissionless {
   /**
@@ -42,6 +43,11 @@ export declare class GearboxPermissionless {
    * Namespace for price feeds: the store and its prices.
    **/
   readonly oracles: PermissionlessOracles;
+  /**
+   * Namespace for history: what a feed's price did over a window, see
+   * {@link PermissionlessAnalytics}.
+   **/
+  readonly analytics: PermissionlessAnalytics;
   /**
    * Namespace for the Safe batches an instance owner executes. Backend-free,
    * see {@link InstanceOwnerTransactions}.

package/dist/types/permissionless/api/analytics/PermissionlessAnalytics.d.ts

@@ -0,0 +1,38 @@
+import { AbstractOffchainNamespace } from "../../../offchain/AbstractOffchainNamespace.js";
+import { GearboxPermissionlessOptions } from "../types.js";
+import { PriceChartArgs, PriceFeedPriceChart } from "./types.js";
+//#region src/permissionless/api/analytics/PermissionlessAnalytics.d.ts
+/**
+ * History of the permissionless stack: what a thing did, rather than what it
+ * is.
+ *
+ * Separate from {@link PermissionlessOracles} because the two are read on
+ * different clocks. A feed's identity settles when a curator uploads it and
+ * is read once per page; its price moves every block and is re-read whenever
+ * a window changes. Folding the series into the feed would make every range
+ * switch re-fetch the identity, and every identity read carry a series the
+ * caller may never draw.
+ *
+ * ```ts
+ * const chart = await permissionless.analytics.priceChart({
+ *   chainId: 1,
+ *   address: feed,
+ *   range: "1w",
+ * });
+ * ```
+ **/
+export declare class PermissionlessAnalytics extends AbstractOffchainNamespace {
+  constructor(options: GearboxPermissionlessOptions);
+  /**
+   * The price one feed reported over a window.
+   *
+   * Backend-only by construction: the chain serves the present, and
+   * reconstructing a series from it would mean an archive read per point.
+   *
+   * @throws When the PriceFeedStore does not carry the feed. An address the
+   * store never held has no indexed history, and answering an empty series
+   * would read as "no price yet" rather than as the mistake it is.
+   **/
+  priceChart({ chainId, address, range }: PriceChartArgs): Promise<PriceFeedPriceChart>;
+}
+//#endregion

package/dist/types/permissionless/api/analytics/index.d.ts

@@ -0,0 +1,3 @@
+import { PriceChartArgs, PriceFeedChartPoint, PriceFeedPriceChart } from "./types.js";
+import { PermissionlessAnalytics } from "./PermissionlessAnalytics.js";
+export { PermissionlessAnalytics, PriceChartArgs, PriceFeedChartPoint, PriceFeedPriceChart };

package/dist/types/permissionless/api/analytics/schemas.d.ts

@@ -0,0 +1,32 @@
+import { z } from "zod/v4";
+//#region src/permissionless/api/analytics/schemas.d.ts
+/**
+ * Runtime schemas for {@link ./types.js}.
+ *
+ * Loose for the same reason the oracles schemas are: the backend assembles
+ * these rows from its own indexes and may report more about a window than the
+ * hand-written types declare.
+ **/
+/** {@link PriceFeedChartPoint} */
+export declare const priceFeedChartPointSchema: z.ZodObject<{
+  timestamp: z.ZodNumber;
+  value: z.ZodNumber;
+}, z.core.$loose>;
+/** {@link PriceFeedPriceChart} */
+export declare const priceFeedChartSchema: z.ZodObject<{
+  range: z.ZodEnum<{
+    "1d": "1d";
+    "1m": "1m";
+    "1w": "1w";
+    "1y": "1y";
+    max: "max";
+  }>;
+  from: z.ZodNumber;
+  to: z.ZodNumber;
+  intervalSeconds: z.ZodNumber;
+  points: z.ZodArray<z.ZodObject<{
+    timestamp: z.ZodNumber;
+    value: z.ZodNumber;
+  }, z.core.$loose>>;
+}, z.core.$loose>;
+//#endregion

package/dist/types/permissionless/api/analytics/types.d.ts

@@ -0,0 +1,38 @@
+import { Timestamp } from "../../../model/primitives.js";
+import { ChartRange } from "../../../model/charts.js";
+import { Address } from "viem";
+//#region src/permissionless/api/analytics/types.d.ts
+/** One sampled price, in whole US dollars. */
+export interface PriceFeedChartPoint {
+  timestamp: Timestamp;
+  value: number;
+}
+/**
+ * A feed's price over one window, sampled onto an epoch-aligned grid.
+ *
+ * Only the buckets with an observation are present: a gap is an absent point,
+ * never a zero and never a value carried over from a neighbour. The window is
+ * echoed back because `max` resolves against the feed's own first observation
+ * and is therefore not derivable from the range alone.
+ *
+ * Deliberately not a {@link ChartBundle}. A bundle carries one series per
+ * {@link ChartMetric}, and that union is closed over what the read model
+ * charts — a price feed's own price is not one of them, and widening it would
+ * reach every chart the protocol serves to add a series only this page draws.
+ **/
+export interface PriceFeedPriceChart {
+  range: ChartRange;
+  from: Timestamp;
+  to: Timestamp;
+  /** Distance between two consecutive buckets. */
+  intervalSeconds: number;
+  points: PriceFeedChartPoint[];
+}
+/** Args of {@link PermissionlessAnalytics.priceChart}. */
+export interface PriceChartArgs {
+  chainId: number;
+  address: Address;
+  /** Window to cover. The same set every other Gearbox chart offers. */
+  range: ChartRange;
+}
+//#endregion

package/dist/types/permissionless/api/index.d.ts

@@ -1,17 +1,20 @@
 import { GearboxPermissionlessOptions } from "./types.js";
+import { PriceChartArgs, PriceFeedChartPoint, PriceFeedPriceChart } from "./analytics/types.js";
+import { PermissionlessAnalytics } from "./analytics/PermissionlessAnalytics.js";
 import { AttachChainsArgs, ChainScope, ChainSummaryArgs, PermissionlessChain, PermissionlessChainSummary } from "./chains/types.js";
 import { ChainsNamespace } from "./chains/ChainsNamespace.js";
 import { DeployArgs, DeployContractArgs, DeployPriceFeedArgs, PreparedDeployment, PreparedPriceFeedDeployment } from "./deploy/types.js";
 import { DEFAULT_DEPLOY_SALT, PermissionlessDeploy, priceFeedSalt } from "./deploy/PermissionlessDeploy.js";
-import { GetPricesArgs, PermissionlessAsset, PermissionlessPriceFeedStore, PermissionlessPrices } from "./oracles/types.js";
+import { AssetArgs, AssetCap, AssetsArgs, FeedCap, MarketCap, PermissionlessAsset, PermissionlessAssetDetails, PermissionlessAssetMarket, PermissionlessAssetMarketFeed, PermissionlessAssetQuota, PermissionlessAssetSummary, PermissionlessIndexedAssetDetails, PermissionlessIndexedAssetSummary, PermissionlessIndexedPriceFeedDetails, PermissionlessIndexedPriceFeedMarket, PermissionlessMarket, PermissionlessPriceFeedAsset, PermissionlessPriceFeedDetails, PermissionlessPriceFeedMarket, PermissionlessPriceFeedStore, PermissionlessQuotaTotals, PriceFeedArgs, PriceFeedPrice, PriceFeedRef } from "./oracles/types.js";
 import { GET_PRICES_CHUNK_SIZE, GET_PRICES_GAS_LIMIT_BY_CHAIN_ID, PermissionlessOracles } from "./oracles/PermissionlessOracles.js";
 import { AddFeedsArgs, ChangeNamesArgs, ChangeStalenessPeriodsArgs, ForbidFeedsArgs, InstanceTxsArgs, PriceFeedPair } from "./transactions/types.js";
 import { InstanceOwnerTransactions } from "./transactions/InstanceOwnerTransactions.js";
 import { GearboxPermissionless } from "./GearboxPermissionless.js";
+import "./analytics/index.js";
 import "./chains/index.js";
 import { deriveEffectiveStalenessPeriod } from "./deploy/effective-staleness.js";
 import "./deploy/index.js";
 import { PermissionlessChainUnreachableError, PermissionlessNotAttachedError, PriceFeedNotInStoreError, PriceFeedSaltMissingError, PriceFeedStalenessUnknownError } from "./errors.js";
 import "./oracles/index.js";
 import "./transactions/index.js";
-export { AddFeedsArgs, AttachChainsArgs, ChainScope, ChainSummaryArgs, ChainsNamespace, ChangeNamesArgs, ChangeStalenessPeriodsArgs, DEFAULT_DEPLOY_SALT, DeployArgs, DeployContractArgs, DeployPriceFeedArgs, ForbidFeedsArgs, GET_PRICES_CHUNK_SIZE, GET_PRICES_GAS_LIMIT_BY_CHAIN_ID, GearboxPermissionless, GearboxPermissionlessOptions, GetPricesArgs, InstanceOwnerTransactions, InstanceTxsArgs, PermissionlessAsset, PermissionlessChain, PermissionlessChainSummary, PermissionlessChainUnreachableError, PermissionlessDeploy, PermissionlessNotAttachedError, PermissionlessOracles, PermissionlessPriceFeedStore, PermissionlessPrices, PreparedDeployment, PreparedPriceFeedDeployment, PriceFeedNotInStoreError, PriceFeedPair, PriceFeedSaltMissingError, PriceFeedStalenessUnknownError, deriveEffectiveStalenessPeriod, priceFeedSalt };
+export { AddFeedsArgs, AssetArgs, AssetCap, AssetsArgs, AttachChainsArgs, ChainScope, ChainSummaryArgs, ChainsNamespace, ChangeNamesArgs, ChangeStalenessPeriodsArgs, DEFAULT_DEPLOY_SALT, DeployArgs, DeployContractArgs, DeployPriceFeedArgs, FeedCap, ForbidFeedsArgs, GET_PRICES_CHUNK_SIZE, GET_PRICES_GAS_LIMIT_BY_CHAIN_ID, GearboxPermissionless, GearboxPermissionlessOptions, InstanceOwnerTransactions, InstanceTxsArgs, MarketCap, PermissionlessAnalytics, PermissionlessAsset, PermissionlessAssetDetails, PermissionlessAssetMarket, PermissionlessAssetMarketFeed, PermissionlessAssetQuota, PermissionlessAssetSummary, PermissionlessChain, PermissionlessChainSummary, PermissionlessChainUnreachableError, PermissionlessDeploy, PermissionlessIndexedAssetDetails, PermissionlessIndexedAssetSummary, PermissionlessIndexedPriceFeedDetails, PermissionlessIndexedPriceFeedMarket, PermissionlessMarket, PermissionlessNotAttachedError, PermissionlessOracles, PermissionlessPriceFeedAsset, PermissionlessPriceFeedDetails, PermissionlessPriceFeedMarket, PermissionlessPriceFeedStore, PermissionlessQuotaTotals, PreparedDeployment, PreparedPriceFeedDeployment, PriceChartArgs, PriceFeedArgs, PriceFeedChartPoint, PriceFeedNotInStoreError, PriceFeedPair, PriceFeedPrice, PriceFeedPriceChart, PriceFeedRef, PriceFeedSaltMissingError, PriceFeedStalenessUnknownError, deriveEffectiveStalenessPeriod, priceFeedSalt };

package/dist/types/permissionless/api/oracles/PermissionlessOracles.d.ts

@@ -1,8 +1,8 @@
+import { PriceFeedData } from "../../../model/opportunities.js";
 import { AbstractOffchainNamespace } from "../../../offchain/AbstractOffchainNamespace.js";
 import { GearboxPermissionlessOptions } from "../types.js";
 import { ChainsNamespace } from "../chains/ChainsNamespace.js";
-import { GetPricesArgs, PermissionlessPriceFeedStore, PermissionlessPrices } from "./types.js";
-import { Address } from "viem";
+import { AssetArgs, AssetCap, AssetsArgs, FeedCap, MarketCap, PermissionlessAssetDetails, PermissionlessAssetSummary, PermissionlessPriceFeedDetails, PermissionlessPriceFeedStore, PriceFeedArgs, PriceFeedPrice, PriceFeedRef } from "./types.js";
 //#region src/permissionless/api/oracles/PermissionlessOracles.d.ts
 export declare const GET_PRICES_GAS_LIMIT_BY_CHAIN_ID: Record<number, bigint>;
 export declare const GET_PRICES_CHUNK_SIZE = 200;
@@ -12,9 +12,17 @@ export declare const GET_PRICES_CHUNK_SIZE = 200;
  *
  * ```ts
  * const store = await permissionless.oracles.store({ chainId: 1 });
- * const { prices } = await permissionless.oracles.prices({ chainId: 1 });
+ * const prices = await permissionless.oracles.getPrices(
+ *   store.priceFeeds.map(({ address }) => ({ chainId: 1, address })),
+ * );
  * ```
  *
+ * The backend answers what it has indexed; anything that is only true at a
+ * block — a price, a market cap, a quota in one currency, the period an
+ * oracle holds for a slot — is read here, off the chain, and folded into what
+ * it answered. That is why these reads mix a request with a multicall rather
+ * than being either one.
+ *
  * Read-only. What the store carries is decided on chain, so putting a feed
  * there is a batch the instance owner executes — see
  * {@link InstanceOwnerTransactions} — not a row a client writes here.
@@ -24,40 +32,169 @@ export declare class PermissionlessOracles extends AbstractOffchainNamespace {
   constructor(options: GearboxPermissionlessOptions, chains: ChainsNamespace);
   /**
    * The store with the assets and feeds of one chain.
+   *
+   * {@link stores} narrowed to one and unwrapped, which is the whole of it:
+   * there is one route either way, and a chain the backend does not serve has
+   * no store to answer with rather than an empty one.
+   *
+   * @throws When the backend serves no store for the chain.
    **/
   store({ chainId }: {
     chainId: number;
   }): Promise<PermissionlessPriceFeedStore>;
   /**
-   * A price per feed, and a market cap per feed and asset. The feeds the
-   * indexer has not seen are read off the chain by the backend, so the store
-   * is priced whole.
+   * The same stores for every chain the backend serves.
+   *
+   * One request rather than {@link store} per chain, which is what a page
+   * showing all of them would otherwise do: the backend assembles them in the
+   * same few queries it assembles one in, so the chains cost little more than
+   * the largest of them.
+   *
+   * Each entry names its own chain, so a store is never attributed by
+   * position. `chainId` narrows it to one, for a caller that wants the list
+   * shape either way.
+   *
+   * ```ts
+   * const stores = await permissionless.oracles.stores();
+   * ```
    **/
-  prices({ chainId }: {
-    chainId: number;
-  }): Promise<PermissionlessPrices>;
+  stores({ chainId }?: AssetsArgs): Promise<PermissionlessPriceFeedStore[]>;
   /**
-   * The price each of the named feeds reports, read off the chain.
+   * One feed of the store: what it is, which assets it may price, and which
+   * market slots it currently fills.
+   *
+   * Singular where {@link store} is plural, and not a filter over it: the
+   * store answers what a list renders, while this answers what a feed is used
+   * for, which the store does not carry at all.
+   *
+   * ```ts
+   * const { priceFeed, markets } = await permissionless.oracles.feed({
+   *   chainId: 1,
+   *   address: feed,
+   * });
+   * ```
    *
-   * Where {@link prices} answers for the store as a whole and at whatever
-   * moment the backend priced it, this prices exactly the feeds asked for, at
-   * the current block. A feed the store does not carry prices the same way,
-   * which is what makes this the call to reach for after a deploy, or while a
-   * form is still choosing between candidates.
+   * Each market row also carries the staleness period that market's own
+   * oracle holds for the slot, read off the chain here — see
+   * {@link PermissionlessPriceFeedMarket.marketStalenessPeriod}.
    *
-   * Feeds needing a fresh answer before they can be read are updated inside
-   * the same simulation, so a push-based feed prices as readily as a
-   * pull-based one. `null` is a feed whose read reverted, not a zero.
+   * @throws When the store does not carry the feed. A private draft is not
+   * here — it lives in whichever app wrote it.
+   **/
+  feed({ chainId, address }: PriceFeedArgs): Promise<PermissionlessPriceFeedDetails>;
+  /**
+   * One asset of the store: the feeds allowed for it, and the markets that
+   * take it as collateral.
+   *
+   * The mirror of {@link feed}, and the call to reach for when the question is
+   * "what prices this token and what is it backing" rather than "where is this
+   * feed used". Both read the same market slots; which end they are indexed
+   * from is the difference.
    *
    * ```ts
-   * const prices = await permissionless.oracles.getPrices({
+   * const { priceFeeds, markets, quotaUsedUsd } =
+   *   await permissionless.oracles.asset({ chainId: 1, address: token });
+   * ```
+   *
+   * The quota totals are worked out here, over the very market rows this
+   * answers with — see {@link PermissionlessQuotaTotals}.
+   *
+   * @throws When the chain has no metadata for the address. An asset nothing
+   * was indexed for has no symbol or decimals, so there is no row to answer.
+   **/
+  asset({ chainId, address }: AssetArgs): Promise<PermissionlessAssetDetails>;
+  /**
+   * Every asset the store carries, with what its markets make of it.
+   *
+   * Enough on its own to render a list of assets: the alternative is the
+   * store's whole read for the names plus a call per row for the quotas, and
+   * this is one request either way you scope it.
+   *
+   * Ordered by how central each asset is — the markets it underlies first,
+   * then what is quoted against it, then what it is allowed — so a consumer
+   * renders the rows as they arrive. Omit `chainId` for every chain the
+   * backend serves, ordered the same way across all of them.
+   *
+   * Each row also carries its quota totals and what this SDK's tables say the
+   * asset is, neither of which is served — see
+   * {@link PermissionlessAssetSummary}. The totals are what the last two terms
+   * of the order are over, so this waits for them rather than handing back a
+   * list that would reshuffle a moment later.
+   *
+   * ```ts
+   * const assets = await permissionless.oracles.assets({ chainId: 1 });
+   * const everywhere = await permissionless.oracles.assets();
+   * ```
+   **/
+  assets({ chainId }?: AssetsArgs): Promise<PermissionlessAssetSummary[]>;
+  /**
+   * The feeds one feed reads from, recursively.
+   *
+   * Answers for any feed the chain has indexed, store member or not: a
+   * composite feed's children are rarely in the store themselves, and a tree
+   * that stopped at the first of them would not be one.
+   *
+   * ```ts
+   * const tree = await permissionless.oracles.dependencies({
    *   chainId: 1,
-   *   priceFeeds: [feed],
+   *   address: feed,
    * });
    * ```
+   **/
+  dependencies({ chainId, address }: PriceFeedArgs): Promise<PriceFeedData>;
+  /**
+   * What the named feeds price, read off the chain.
+   *
+   * Prices exactly what is asked for, at the current block, across as many
+   * chains as the list names — one read per chain, so a screen listing every
+   * chain's feeds pays per chain and not per row. A feed the store does not
+   * carry prices the same way, which is what makes this the call to reach for
+   * after a deploy, or while a form is still choosing between candidates.
+   *
+   * Read in two passes. The first asks every feed what it reports as it
+   * stands, which is one multicall per chain; a feed that will not answer
+   * until it has been given a fresh one is then priced inside a simulation
+   * that updates it first, so a push-based feed prices as readily as a
+   * pull-based one. The second pass costs an `OnchainSDK` to attach, hence
+   * only the feeds that need it rather than all of them.
+   *
+   * `null` is a feed neither pass could read, and a chain with no client
+   * configured is every one of its feeds reading `null` rather than a failed
+   * call — the figures built on them are floors either way.
    *
-   * @returns A price per feed, in the 8 decimals every Gearbox feed reports.
+   * ```ts
+   * const [{ price }] = await permissionless.oracles.getPrices([
+   *   { chainId: 1, address: feed },
+   * ]);
+   * ```
+   *
+   * @returns One entry per feed asked for, in the order asked, each price in
+   * the 8 decimals every Gearbox feed reports.
+   **/
+  getPrices(feeds: PriceFeedRef[]): Promise<PriceFeedPrice[]>;
+  /**
+   * What one chain's feeds value one chain's assets at: `price × totalSupply`
+   * per pair.
+   *
+   * Asked from whichever side the caller is looking at — one asset through
+   * each of its feeds, or one feed over each of the assets it prices — because
+   * a screen shows one row per feed or one row per asset, never the full
+   * cross product. Both answer the same pairs in the same shape.
+   *
+   * Two reads per chain: the prices, and one multicall for the assets'
+   * supplies and decimals. Several scopes can be asked at once, which is how a
+   * table of every asset's feeds pays per chain rather than per row; the pairs
+   * come back in the order the scopes named them. A pair neither read could
+   * resolve has a `null` cap, which is not a zero.
+   *
+   * ```ts
+   * const caps = await permissionless.oracles.getMarketCap({
+   *   chainId: 1,
+   *   asset: token,
+   *   priceFeeds: [main, reserve],
+   * });
+   * ```
    **/
-  getPrices({ chainId, priceFeeds }: GetPricesArgs): Promise<Record<Address, bigint | null>>;
+  getMarketCap(scope: AssetCap | FeedCap | Array<AssetCap | FeedCap>): Promise<MarketCap[]>;
 }
 //#endregion

package/dist/types/permissionless/api/oracles/enrich.d.ts

@@ -0,0 +1,59 @@
+import { PermissionlessAssetQuota, PermissionlessIndexedAssetSummary, PermissionlessQuotaTotals, PriceFeedPrice } from "./types.js";
+import { Address } from "viem";
+//#region src/permissionless/api/oracles/enrich.d.ts
+/**
+ * What the oracles namespace works out for itself once the backend has
+ * answered.
+ *
+ * All of it used to be the backend's, and all of it needs the chain: a quota
+ * is denominated in its market's own underlying and a market cap is a supply
+ * times a price, so none of these can be indexed — they can only be read at
+ * the block the reader is on. Keeping them here means one description of each
+ * rule rather than one per service that wants it, and a backend that holds no
+ * viem client at all.
+ **/
+/** Identifies a feed across chains, since an address alone does not. */
+export declare function feedKey(chainId: number, address: Address): string;
+/** Prices looked up the way {@link totalQuotas} and the caps need them. */
+export declare function pricesByFeed(prices: PriceFeedPrice[]): Map<string, bigint | null>;
+/**
+ * The asset's quota across its markets, totalled in USD.
+ *
+ * Each market's figures are converted at the price that market's own oracle
+ * holds for its underlying, which is the same number that market's accounting
+ * uses.
+ *
+ * Limits count only the markets still running, because a shut down market's
+ * limit is not borrowable; what is already quoted counts everywhere, because
+ * debt outstanding is exposure either way. A market whose underlying could not
+ * be priced is skipped, which makes both figures floors, and `null` is nothing
+ * to total rather than a zero.
+ *
+ * @param priceOf - The price each underlying feed reports, in the 8 decimals
+ * every Gearbox feed uses.
+ */
+export declare function totalQuotas(quotas: PermissionlessAssetQuota[], priceOf: (feed: Address) => bigint | null | undefined): PermissionlessQuotaTotals;
+/**
+ * What one feed values one asset's supply at: `price × totalSupply`.
+ *
+ * Multiplied as integers and formatted once, rather than through two floats:
+ * an 8-decimal price times an 18-decimal supply loses its small end to a JS
+ * number long before it loses the large one, and the figure is a total rather
+ * than an estimate.
+ *
+ * `null` if either side could not be read — an asset nobody could price is
+ * not an asset worth nothing.
+ */
+export declare function toCap(price: bigint | null | undefined, totalSupply: bigint | null | undefined, decimals: number): string | null;
+/**
+ * Assets ordered the way a reader scans them: what the protocol is built on
+ * first, then what is actually borrowed against it, then what it is merely
+ * allowed to be borrowed against.
+ *
+ * Applied here and not by the backend because the two middle terms are the
+ * converted quotas, which only exist once the chain has been read. The
+ * backend orders by the first term and the tie-breakers, so a caller reading
+ * the route directly still gets a stable order; this refines it.
+ */
+export declare function byCentrality<T extends PermissionlessIndexedAssetSummary & PermissionlessQuotaTotals>(a: T, b: T): number;
+//#endregion

package/dist/types/permissionless/api/oracles/index.d.ts

@@ -1,3 +1,3 @@
-import { GetPricesArgs, PermissionlessAsset, PermissionlessPriceFeedStore, PermissionlessPrices } from "./types.js";
+import { AssetArgs, AssetCap, AssetsArgs, FeedCap, MarketCap, PermissionlessAsset, PermissionlessAssetDetails, PermissionlessAssetMarket, PermissionlessAssetMarketFeed, PermissionlessAssetQuota, PermissionlessAssetSummary, PermissionlessIndexedAssetDetails, PermissionlessIndexedAssetSummary, PermissionlessIndexedPriceFeedDetails, PermissionlessIndexedPriceFeedMarket, PermissionlessMarket, PermissionlessPriceFeedAsset, PermissionlessPriceFeedDetails, PermissionlessPriceFeedMarket, PermissionlessPriceFeedStore, PermissionlessQuotaTotals, PriceFeedArgs, PriceFeedPrice, PriceFeedRef } from "./types.js";
 import { GET_PRICES_CHUNK_SIZE, GET_PRICES_GAS_LIMIT_BY_CHAIN_ID, PermissionlessOracles } from "./PermissionlessOracles.js";
-export { GET_PRICES_CHUNK_SIZE, GET_PRICES_GAS_LIMIT_BY_CHAIN_ID, GetPricesArgs, PermissionlessAsset, PermissionlessOracles, PermissionlessPriceFeedStore, PermissionlessPrices };
+export { AssetArgs, AssetCap, AssetsArgs, FeedCap, GET_PRICES_CHUNK_SIZE, GET_PRICES_GAS_LIMIT_BY_CHAIN_ID, MarketCap, PermissionlessAsset, PermissionlessAssetDetails, PermissionlessAssetMarket, PermissionlessAssetMarketFeed, PermissionlessAssetQuota, PermissionlessAssetSummary, PermissionlessIndexedAssetDetails, PermissionlessIndexedAssetSummary, PermissionlessIndexedPriceFeedDetails, PermissionlessIndexedPriceFeedMarket, PermissionlessMarket, PermissionlessOracles, PermissionlessPriceFeedAsset, PermissionlessPriceFeedDetails, PermissionlessPriceFeedMarket, PermissionlessPriceFeedStore, PermissionlessQuotaTotals, PriceFeedArgs, PriceFeedPrice, PriceFeedRef };