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

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

@@ -0,0 +1,105 @@
+import { Timestamp } from "./primitives.js";
+import { OpportunityKey } from "./opportunities.js";
+//#region src/model/history.d.ts
+/**
+ * Historical time series of an opportunity.
+ *
+ * History is backend-only by construction: the chain serves the present, and
+ * reconstructing a series from it would mean archive-node reads per point.
+ **/
+/**
+ * Time window a series covers, ending at the present.
+ *
+ * `"max"` is the full history the backend retains for the opportunity.
+ **/
+type HistoryRange = "1d" | "1w" | "1m" | "1y" | "max";
+/**
+ * Series available for a pool opportunity.
+ **/
+type PoolHistoryMetric = "depositApy" | "borrowApy" | "dieselRate" | "supplied" | "borrowed" | "availableLiquidity";
+/**
+ * Every {@link PoolHistoryMetric}, for callers that enumerate them.
+ **/
+declare const POOL_HISTORY_METRICS: readonly ["depositApy", "borrowApy", "dieselRate", "supplied", "borrowed", "availableLiquidity"];
+/**
+ * Series available for a strategy opportunity.
+ *
+ * `collateralPrice` is the collateral/underlying series a liquidation-price
+ * chart draws; the two USD series are the same prices quoted in dollars.
+ **/
+type StrategyHistoryMetric = "netApy" | "borrowApy" | "collateralApy" | "tvl" | "collateralPrice" | "collateralUsdPrice" | "underlyingUsdPrice";
+/**
+ * Every {@link StrategyHistoryMetric}, for callers that enumerate them.
+ **/
+declare const STRATEGY_HISTORY_METRICS: readonly ["netApy", "borrowApy", "collateralApy", "tvl", "collateralPrice", "collateralUsdPrice", "underlyingUsdPrice"];
+/**
+ * Any series the read model can return.
+ **/
+type HistoryMetric = PoolHistoryMetric | StrategyHistoryMetric;
+/**
+ * One sample of a series.
+ **/
+interface HistoryPoint {
+  /**
+   * When the sample was taken.
+   **/
+  timestamp: Timestamp;
+  /**
+   * Sampled value. The unit follows from the metric: APY metrics are in basis
+   * points, amount metrics are in the underlying's base units expressed as a
+   * float, price metrics are plain prices.
+   *
+   * @example `842` for an 8.42% APY sample
+   **/
+  value: number;
+}
+/**
+ * Annotations the backend ships alongside a series, e.g. what a chart drawn
+ * from it should say beyond the points themselves.
+ *
+ * TODO: the backend has not specified this payload yet. It stays empty until
+ * it does, so that filling it in later is additive rather than a rename.
+ **/
+interface HistoryChartMetadata {}
+/**
+ * A named series of samples ordered by ascending timestamp.
+ *
+ * @typeParam M - Metric the series carries.
+ **/
+interface HistorySeries<M extends string = HistoryMetric> {
+  /**
+   * Metric the samples belong to; it also defines their unit, so no separate
+   * unit field ships.
+   **/
+  metric: M;
+  /**
+   * Samples, oldest first.
+   **/
+  points: HistoryPoint[];
+  /**
+   * What the backend says about the series, see {@link HistoryChartMetadata}.
+   **/
+  metadata: HistoryChartMetadata;
+}
+/**
+ * A request for one series of a single opportunity.
+ *
+ * @typeParam M - Metric requested.
+ **/
+interface OpportunityHistoryQuery<M extends HistoryMetric = HistoryMetric> {
+  /**
+   * Opportunity the series belongs to.
+   **/
+  opportunity: OpportunityKey;
+  /**
+   * Window to cover.
+   **/
+  range: HistoryRange;
+  /**
+   * Metric to return. A metric that does not apply to the opportunity's kind
+   * has no series.
+   **/
+  metric: M;
+}
+//#endregion
+export { HistoryChartMetadata, HistoryMetric, HistoryPoint, HistoryRange, HistorySeries, OpportunityHistoryQuery, POOL_HISTORY_METRICS, PoolHistoryMetric, STRATEGY_HISTORY_METRICS, StrategyHistoryMetric };

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

@@ -0,0 +1,66 @@
+import { HistoryChartMetadata } from "./history.js";
+import { z } from "zod/v4";
+//#region src/model/history.schema.d.ts
+/**
+ * Runtime schemas for {@link ./history.js}, see the note in
+ * `primitives.schema.ts` on why they are written by hand.
+ **/
+/**
+ * {@link HistoryRange}
+ **/
+declare const historyRangeSchema: z.ZodUnion<readonly [z.ZodLiteral<"1d">, z.ZodLiteral<"1w">, z.ZodLiteral<"1m">, z.ZodLiteral<"1y">, z.ZodLiteral<"max">]>;
+/**
+ * {@link PoolHistoryMetric}
+ **/
+declare const poolHistoryMetricSchema: z.ZodUnion<readonly [z.ZodLiteral<"depositApy">, z.ZodLiteral<"borrowApy">, z.ZodLiteral<"dieselRate">, z.ZodLiteral<"supplied">, z.ZodLiteral<"borrowed">, z.ZodLiteral<"availableLiquidity">]>;
+/**
+ * {@link StrategyHistoryMetric}
+ **/
+declare const strategyHistoryMetricSchema: z.ZodUnion<readonly [z.ZodLiteral<"netApy">, z.ZodLiteral<"borrowApy">, z.ZodLiteral<"collateralApy">, z.ZodLiteral<"tvl">, z.ZodLiteral<"collateralPrice">, z.ZodLiteral<"collateralUsdPrice">, z.ZodLiteral<"underlyingUsdPrice">]>;
+/**
+ * {@link HistoryMetric}
+ **/
+declare const historyMetricSchema: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"depositApy">, z.ZodLiteral<"borrowApy">, z.ZodLiteral<"dieselRate">, z.ZodLiteral<"supplied">, z.ZodLiteral<"borrowed">, z.ZodLiteral<"availableLiquidity">]>, z.ZodUnion<readonly [z.ZodLiteral<"netApy">, z.ZodLiteral<"borrowApy">, z.ZodLiteral<"collateralApy">, z.ZodLiteral<"tvl">, z.ZodLiteral<"collateralPrice">, z.ZodLiteral<"collateralUsdPrice">, z.ZodLiteral<"underlyingUsdPrice">]>]>;
+/**
+ * {@link HistoryPoint}
+ **/
+declare const historyPointSchema: z.ZodObject<{
+  timestamp: z.ZodNumber;
+  value: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * {@link HistoryChartMetadata}
+ *
+ * TODO: empty until the backend specifies the payload.
+ **/
+declare const historyChartMetadataSchema: z.ZodType<HistoryChartMetadata>;
+/**
+ * {@link HistorySeries}
+ **/
+declare const historySeriesSchema: z.ZodObject<{
+  metric: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"depositApy">, z.ZodLiteral<"borrowApy">, z.ZodLiteral<"dieselRate">, z.ZodLiteral<"supplied">, z.ZodLiteral<"borrowed">, z.ZodLiteral<"availableLiquidity">]>, z.ZodUnion<readonly [z.ZodLiteral<"netApy">, z.ZodLiteral<"borrowApy">, z.ZodLiteral<"collateralApy">, z.ZodLiteral<"tvl">, z.ZodLiteral<"collateralPrice">, z.ZodLiteral<"collateralUsdPrice">, z.ZodLiteral<"underlyingUsdPrice">]>]>;
+  points: z.ZodArray<z.ZodObject<{
+    timestamp: z.ZodNumber;
+    value: z.ZodNumber;
+  }, z.core.$strip>>;
+  metadata: z.ZodType<HistoryChartMetadata, unknown, z.core.$ZodTypeInternals<HistoryChartMetadata, unknown>>;
+}, z.core.$strip>;
+/**
+ * {@link OpportunityHistoryQuery}
+ **/
+declare const opportunityHistoryQuerySchema: z.ZodObject<{
+  opportunity: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    chainId: z.ZodNumber;
+    pool: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    kind: z.ZodLiteral<"pool">;
+  }, z.core.$strip>, z.ZodObject<{
+    chainId: z.ZodNumber;
+    creditManager: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    targetCollateral: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    kind: z.ZodLiteral<"strategy">;
+  }, z.core.$strip>], "kind">;
+  range: z.ZodUnion<readonly [z.ZodLiteral<"1d">, z.ZodLiteral<"1w">, z.ZodLiteral<"1m">, z.ZodLiteral<"1y">, z.ZodLiteral<"max">]>;
+  metric: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"depositApy">, z.ZodLiteral<"borrowApy">, z.ZodLiteral<"dieselRate">, z.ZodLiteral<"supplied">, z.ZodLiteral<"borrowed">, z.ZodLiteral<"availableLiquidity">]>, z.ZodUnion<readonly [z.ZodLiteral<"netApy">, z.ZodLiteral<"borrowApy">, z.ZodLiteral<"collateralApy">, z.ZodLiteral<"tvl">, z.ZodLiteral<"collateralPrice">, z.ZodLiteral<"collateralUsdPrice">, z.ZodLiteral<"underlyingUsdPrice">]>]>;
+}, z.core.$strip>;
+//#endregion
+export { historyChartMetadataSchema, historyMetricSchema, historyPointSchema, historyRangeSchema, historySeriesSchema, opportunityHistoryQuerySchema, poolHistoryMetricSchema, strategyHistoryMetricSchema };

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

@@ -0,0 +1,9 @@
+import { Amount, AssetType, Bps, ChainId, Curator, Leverage, Timestamp, Token, TokenAmount, TxCall } from "./primitives.js";
+import { ApyBreakdown, Opportunity, OpportunityBase, OpportunityDetail, OpportunityFilter, OpportunityId, OpportunityKey, OpportunityKind, PointRewards, PointsProgram, PoolOpportunity, PoolOpportunityDetail, PoolOpportunityKey, PoolOpportunityRef, PriceFeedData, PriceFeedSummary, QuotaAsset, RateCurve, RateCurvePoint, Rewards, StrategyOpportunity, StrategyOpportunityDetail, StrategyOpportunityKey, StrategyOpportunityRef, TokenRewards, matchesOpportunityFilter, opportunityId, poolOpportunityId, strategyOpportunityId } from "./opportunities.js";
+import { HistoryChartMetadata, HistoryMetric, HistoryPoint, HistoryRange, HistorySeries, OpportunityHistoryQuery, POOL_HISTORY_METRICS, PoolHistoryMetric, STRATEGY_HISTORY_METRICS, StrategyHistoryMetric } from "./history.js";
+import { historyChartMetadataSchema, historyMetricSchema, historyPointSchema, historyRangeSchema, historySeriesSchema, opportunityHistoryQuerySchema, poolHistoryMetricSchema, strategyHistoryMetricSchema } from "./history.schema.js";
+import { DelayedReceivedAsset, InstantReceivedAsset, LiquidatableAccount, LiquidatableAccountFilter, LiquidationApproval, LiquidationDetails, LiquidationPosition, ReceivedAsset, matchesLiquidatableAccountFilter } from "./liquidations.js";
+import { delayedReceivedAssetSchema, instantReceivedAssetSchema, liquidatableAccountFilterSchema, liquidatableAccountSchema, liquidationApprovalSchema, liquidationDetailsSchema, liquidationPositionSchema, receivedAssetSchema } from "./liquidations.schema.js";
+import { apyBreakdownSchema, opportunityBaseSchema, opportunityDetailSchema, opportunityFilterSchema, opportunityKeySchema, opportunityKindSchema, opportunitySchema, pointRewardsSchema, pointsProgramSchema, poolOpportunityDetailSchema, poolOpportunityKeySchema, poolOpportunitySchema, priceFeedDataSchema, priceFeedSummarySchema, quotaAssetSchema, rateCurvePointSchema, rateCurveSchema, rewardsSchema, strategyOpportunityDetailSchema, strategyOpportunityKeySchema, strategyOpportunitySchema, tokenRewardsSchema } from "./opportunities.schema.js";
+import { amountSchema, assetTypeSchema, bpsSchema, chainIdSchema, curatorSchema, leverageSchema, timestampSchema, tokenAmountSchema, tokenSchema, txCallSchema } from "./primitives.schema.js";
+export { Amount, ApyBreakdown, AssetType, Bps, ChainId, Curator, DelayedReceivedAsset, HistoryChartMetadata, HistoryMetric, HistoryPoint, HistoryRange, HistorySeries, InstantReceivedAsset, Leverage, LiquidatableAccount, LiquidatableAccountFilter, LiquidationApproval, LiquidationDetails, LiquidationPosition, Opportunity, OpportunityBase, OpportunityDetail, OpportunityFilter, OpportunityHistoryQuery, OpportunityId, OpportunityKey, OpportunityKind, POOL_HISTORY_METRICS, PointRewards, PointsProgram, PoolHistoryMetric, PoolOpportunity, PoolOpportunityDetail, PoolOpportunityKey, PoolOpportunityRef, PriceFeedData, PriceFeedSummary, QuotaAsset, RateCurve, RateCurvePoint, ReceivedAsset, Rewards, STRATEGY_HISTORY_METRICS, StrategyHistoryMetric, StrategyOpportunity, StrategyOpportunityDetail, StrategyOpportunityKey, StrategyOpportunityRef, Timestamp, Token, TokenAmount, TokenRewards, TxCall, amountSchema, apyBreakdownSchema, assetTypeSchema, bpsSchema, chainIdSchema, curatorSchema, delayedReceivedAssetSchema, historyChartMetadataSchema, historyMetricSchema, historyPointSchema, historyRangeSchema, historySeriesSchema, instantReceivedAssetSchema, leverageSchema, liquidatableAccountFilterSchema, liquidatableAccountSchema, liquidationApprovalSchema, liquidationDetailsSchema, liquidationPositionSchema, matchesLiquidatableAccountFilter, matchesOpportunityFilter, opportunityBaseSchema, opportunityDetailSchema, opportunityFilterSchema, opportunityHistoryQuerySchema, opportunityId, opportunityKeySchema, opportunityKindSchema, opportunitySchema, pointRewardsSchema, pointsProgramSchema, poolHistoryMetricSchema, poolOpportunityDetailSchema, poolOpportunityId, poolOpportunityKeySchema, poolOpportunitySchema, priceFeedDataSchema, priceFeedSummarySchema, quotaAssetSchema, rateCurvePointSchema, rateCurveSchema, receivedAssetSchema, rewardsSchema, strategyHistoryMetricSchema, strategyOpportunityDetailSchema, strategyOpportunityId, strategyOpportunityKeySchema, strategyOpportunitySchema, timestampSchema, tokenAmountSchema, tokenRewardsSchema, tokenSchema, txCallSchema };

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

@@ -0,0 +1,230 @@
+import { AssetType, ChainId, Timestamp, Token, TokenAmount, TxCall } from "./primitives.js";
+import { Address } from "viem";
+//#region src/model/liquidations.d.ts
+/**
+ * Optional narrowing of a liquidatable accounts list.
+ *
+ * Every criterion is optional and an omitted one matches any value, so an empty
+ * filter is the same as no filter at all. Criteria combine with AND.
+ **/
+interface LiquidatableAccountFilter {
+  /**
+   * Keep only accounts on these chains.
+   **/
+  chainIds?: ChainId[];
+  /**
+   * Keep only accounts whose underlying — the token of
+   * {@link LiquidatableAccount.totalValue} — is of this class.
+   **/
+  underlyingType?: AssetType;
+  /**
+   * Keep only accounts of paused credit facades, or only of unpaused ones.
+   **/
+  paused?: boolean;
+  /**
+   * Keep only accounts in markets that accept RWA collateral, or only the ones
+   * outside them.
+   **/
+  rwa?: boolean;
+  /**
+   * Keep only accounts with (`true`) or without (`false`) delayed
+   * (phantom-token) withdrawals.
+   **/
+  delayed?: boolean;
+}
+/**
+ * A credit account that can be liquidated, with amounts precomputed for
+ * manual liquidation.
+ **/
+interface LiquidatableAccount {
+  /**
+   * Chain the account lives on.
+   **/
+  chainId: ChainId;
+  /**
+   * Credit account address.
+   **/
+  creditAccount: Address;
+  /**
+   * Credit manager the account is opened in.
+   **/
+  creditManager: Address;
+  /**
+   * Main asset being liquidated: the most valuable enabled non-underlying
+   * collateral token. For delayed-withdrawal phantom tokens, the source
+   * asset (e.g. ACRED) is reported instead of the phantom token. Falls back
+   * to the underlying when the account holds no other collateral.
+   **/
+  asset: Token;
+  /**
+   * Account total value. The token is the unwrapped asset (e.g. USDC) for
+   * RWA credit managers (1:1 with the wrapped underlying), the credit
+   * manager underlying otherwise.
+   **/
+  totalValue: TokenAmount;
+  /**
+   * Estimated amount the liquidator pays to fully liquidate the account:
+   * `totalValue * liquidationDiscount`. Same token as {@link totalValue}.
+   **/
+  repaymentAmount: TokenAmount;
+  /**
+   * Estimated liquidator profit: `totalValue * (1 - liquidationDiscount)`.
+   * Same token as {@link totalValue}.
+   **/
+  estimatedProfit: TokenAmount;
+  /**
+   * `true` when the account holds a delayed-withdrawal phantom token above
+   * dust, i.e. the liquidation transfers withdrawal redeemers into the
+   * liquidator's ownership instead of instantly receivable tokens.
+   **/
+  isDelayed: boolean;
+  /**
+   * `true` when the credit manager's facade is paused. Liquidations of such
+   * accounts only succeed for emergency liquidators approved in the market.
+   **/
+  paused: boolean;
+  /**
+   * Whether the account's market accepts real-world-asset collateral. Read
+   * from a hardcoded per-chain list rather than from the chain.
+   **/
+  rwa: boolean;
+}
+/**
+ * Whether a liquidatable account satisfies every criterion of a filter.
+ *
+ * This is the single definition of what each criterion means: every source
+ * builds its rows first and runs them through here, so the chain and the
+ * backend cannot disagree on what a filter selects.
+ *
+ * @param account - Row to test.
+ * @param filter - Criteria to test against. An absent filter matches anything.
+ **/
+declare function matchesLiquidatableAccountFilter(account: LiquidatableAccount, filter?: LiquidatableAccountFilter): boolean;
+/**
+ * A token received directly from the credit account balance upon liquidation.
+ **/
+interface InstantReceivedAsset extends TokenAmount {
+  isDelayed: false;
+}
+/**
+ * A token produced by a delayed withdrawal whose redeemer is transferred to
+ * the liquidator upon liquidation.
+ *
+ * The amount is exact for claimable withdrawals, estimated for pending ones.
+ **/
+interface DelayedReceivedAsset extends TokenAmount {
+  isDelayed: true;
+  /**
+   * Redeemer contract transferred to the liquidator, from which the token
+   * becomes claimable. `undefined` when the compressor does not report one.
+   **/
+  redeemerAddress?: Address;
+  /**
+   * Estimated moment a pending withdrawal becomes claimable. `undefined`
+   * means the withdrawal is claimable now.
+   **/
+  claimableAt?: Timestamp;
+}
+/**
+ * A single asset the liquidator receives when fully liquidating an account.
+ **/
+type ReceivedAsset = InstantReceivedAsset | DelayedReceivedAsset;
+/**
+ * ERC-20 approval the liquidator must grant before sending the liquidation
+ * transaction.
+ *
+ * The token is the one the compressor reports for the liquidation path it
+ * selected: the credit manager underlying for standard liquidations, the
+ * unwrapped stablecoin (e.g. USDC) for RWA ones. The value is what the
+ * transaction pulls plus 0.5% of headroom.
+ **/
+interface LiquidationApproval extends TokenAmount {
+  /**
+   * Address to approve
+   **/
+  spender: Address;
+}
+/**
+ * A single delayed-withdrawal position owned by the liquidator.
+ **/
+interface LiquidationPosition {
+  /**
+   * Chain the withdrawal lives on.
+   **/
+  chainId: ChainId;
+  /**
+   * Source asset spent by the delayed withdrawal (e.g. ACRED).
+   **/
+  sourceToken: Token;
+  /**
+   * Receivable asset (e.g. USDC) and its amount: exact for claimable
+   * withdrawals, estimated for pending ones.
+   **/
+  output: TokenAmount;
+  /**
+   * Estimated moment a pending withdrawal becomes claimable. `undefined`
+   * means the withdrawal is claimable now.
+   **/
+  claimableAt?: Timestamp;
+  /**
+   * Transaction that claims the withdrawal. `undefined` for pending
+   * withdrawals and when the compressor reports no claim call.
+   **/
+  claimTx?: TxCall;
+  /**
+   * Redeemer contract the withdrawal is claimed from, owned by the liquidator.
+   * `undefined` on compressor versions below 313, which do not report it.
+   **/
+  redeemer?: Address;
+}
+/**
+ * Detailed information about a liquidatable credit account, including
+ * the full breakdown of assets the liquidator receives.
+ **/
+interface LiquidationDetails extends LiquidatableAccount {
+  /**
+   * Exact amount the liquidator pays for the liquidation, superseding
+   * the estimate of {@link LiquidatableAccount}. The token is
+   * {@link LiquidationApproval}'s, which for RWA markets is the
+   * unwrapped stablecoin rather than {@link LiquidatableAccount.totalValue}'s
+   * token; it falls back to the latter when nothing is pulled.
+   **/
+  repaymentAmount: TokenAmount;
+  /**
+   * Assets the liquidator receives upon full liquidation: direct credit
+   * account balances plus outputs of delayed withdrawals (claimable and
+   * pending).
+   **/
+  receivedAssets: ReceivedAsset[];
+  /**
+   * Whether the liquidator passes the KYC checks of the liquidated assets.
+   * When the liquidator wallet was not provided, `false` only means that the
+   * liquidation is KYC-gated, not that a particular wallet was rejected.
+   **/
+  isLiquidatorEligible: boolean;
+  /**
+   * `true` when the credit account is frozen by the RWA factory
+   * (`isFrozen`) and cannot move its RWA collateral. Always `false` for
+   * non-RWA liquidation paths.
+   **/
+  isCreditAccountFrozen: boolean;
+  /**
+   * Name of the KYC protocol the liquidator must be whitelisted in
+   * (e.g. `"securitize"`). `undefined` when the liquidation is not KYC-gated.
+   **/
+  kycProtocol?: string;
+  /**
+   * Token the liquidator must be whitelisted for in {@link kycProtocol}.
+   * `undefined` when the liquidation is not KYC-gated, and when the token is
+   * not in the SDK's token registry.
+   **/
+  kycToken?: Token;
+  /**
+   * ERC-20 approval required before sending the liquidation transaction.
+   * `undefined` when the selected liquidation path needs no capital from the
+   * liquidator, i.e. {@link repaymentAmount} is zero.
+   **/
+  approve?: LiquidationApproval;
+}
+//#endregion
+export { DelayedReceivedAsset, InstantReceivedAsset, LiquidatableAccount, LiquidatableAccountFilter, LiquidationApproval, LiquidationDetails, LiquidationPosition, ReceivedAsset, matchesLiquidatableAccountFilter };