@gearbox-protocol/sdk 15.1.0-next.1 → 15.1.0-next.11

package/dist/esm/sdk/utils/viem/executeMulticallBatches.js

@@ -0,0 +1,31 @@
+//#region src/sdk/utils/viem/executeMulticallBatches.ts
+/**
+* Executes the calls of several {@link MulticallBatch}es as a single multicall
+* aggregate and dispatches each batch its own slice of the results.
+*
+* Failures are allowed per call: loaders in a batch decide themselves how to
+* treat a reverted call (e.g. `contractType()` reverting on a plain ERC-20 is
+* expected). Use {@link executeDelegatedMulticalls} instead when the calls need
+* price updates applied first.
+*
+* @param client - Viem public client.
+* @param batches - Batches to execute together, empty ones are allowed.
+* @param opts - Block number forwarded to the multicall.
+**/
+async function executeMulticallBatches(client, batches, opts = {}) {
+	const contracts = batches.flatMap((b) => b.contracts);
+	if (!contracts.length) return;
+	const results = await client.multicall({
+		contracts,
+		allowFailure: true,
+		batchSize: 0,
+		blockNumber: opts.blockNumber
+	});
+	let offset = 0;
+	for (const batch of batches) {
+		batch.onResults(results.slice(offset, offset + batch.contracts.length));
+		offset += batch.contracts.length;
+	}
+}
+//#endregion
+export { executeMulticallBatches };

package/dist/esm/sdk/utils/viem/index.js

@@ -1,8 +1,9 @@
 import { generateCastTraceCall, getCastTraceArgs } from "./cast.js";
 import { SimulationError, simulateCall } from "./simulateCall.js";
+import { executeMulticallBatches } from "./executeMulticallBatches.js";
 import { simulateMulticall } from "./simulateMulticall.js";
 import { SimulateWithPriceUpdatesError, getSimulateWithPriceUpdatesError, simulateWithPriceUpdates } from "./simulateWithPriceUpdates.js";
 import { executeDelegatedMulticalls } from "./executeDelegatedMulticalls.js";
 import { estimateRawTxGas, sendRawTx } from "./sendRawTx.js";
 import { watchBlocksAsync } from "./watchBlocksAsync.js";
-export { SimulateWithPriceUpdatesError, SimulationError, estimateRawTxGas, executeDelegatedMulticalls, generateCastTraceCall, getCastTraceArgs, getSimulateWithPriceUpdatesError, sendRawTx, simulateCall, simulateMulticall, simulateWithPriceUpdates, watchBlocksAsync };
+export { SimulateWithPriceUpdatesError, SimulationError, estimateRawTxGas, executeDelegatedMulticalls, executeMulticallBatches, generateCastTraceCall, getCastTraceArgs, getSimulateWithPriceUpdatesError, sendRawTx, simulateCall, simulateMulticall, simulateWithPriceUpdates, watchBlocksAsync };

package/dist/types/abi/iExpirable.d.ts

@@ -0,0 +1,14 @@
+//#region src/abi/iExpirable.d.ts
+declare const iExpirableAbi: readonly [{
+  readonly type: "function";
+  readonly inputs: readonly [];
+  readonly name: "isExpired";
+  readonly outputs: readonly [{
+    readonly name: "";
+    readonly internalType: "bool";
+    readonly type: "bool";
+  }];
+  readonly stateMutability: "view";
+}];
+//#endregion
+export { iExpirableAbi };

package/dist/types/common-utils/utils/apy/get-single-quota-borrow-rate.d.ts

@@ -6,6 +6,8 @@ interface GetSingleQuotaBorrowRateRate extends CalcQuotaBorrowRateProps {
 /**
  * Under the hood sums up rates for all given quotas and then multiplies them by 1+feeInterest,
  * but it is expected that the ONLY quota will be passed
+ *
+ * @deprecated Use `calcBorrowRate` from `sdk/positions` instead.
  */
 declare function getSingleQuotaBorrowRate(props: GetSingleQuotaBorrowRateRate): bigint;
 //#endregion

package/dist/types/common-utils/utils/creditAccount/calc-health-factor.d.ts

@@ -23,6 +23,9 @@ interface CalcHealthFactorProps {
  * @param props Credit account balances, quotas, prices, thresholds, and debt context.
  * @returns Health factor as a number in `PERCENTAGE_FACTOR` scale,
  * or `65535` when debt is zero.
+ *
+ * @deprecated Use `calcHealthFactor` from `sdk/positions` instead; this
+ * wrapper only maps the legacy props onto an `AccountSnapshot`.
  */
 declare function calcHealthFactor({ assets, quotas, quotasInfo, liquidationThresholds, underlyingToken, debt, prices, tokensList }: CalcHealthFactorProps): number;
 //#endregion

package/dist/types/common-utils/utils/creditAccount/calc-quota-borrow-rate.d.ts

@@ -16,6 +16,8 @@ interface CalcQuotaBorrowRateProps {
  *
  * @param props Quota balances and per-token quota rates.
  * @returns Sum of `balance * rate` terms in percentage-factor scale.
+ *
+ * @deprecated Use `calcBorrowRate` from `sdk/positions` instead.
  */
 declare function calcQuotaBorrowRate({ quotas, quotaRates }: CalcQuotaBorrowRateProps): bigint;
 //#endregion

package/dist/types/common-utils/utils/creditAccount/get-time-to-liquidation.d.ts

@@ -10,9 +10,14 @@ interface TimeToLiquidationProps {
  * and returns a millisecond duration until `healthFactor` decays to `1.0`
  * (`PERCENTAGE_FACTOR` in internal scale).
  *
- * @param props Current health factor and `totalBorrowRate * debt` term.
+ * @param props Current health factor and `totalBorrowRate_debt`, both `Bps`
+ * (`10000` = 100%) — not the legacy `PERCENTAGE_FACTOR_1KK` (`1_000_000` =
+ * 100%) scale the pre-rewrite frontend fed this under the same name.
  * @returns Milliseconds to liquidation as `bigint`, or `null` when already at/under
  * liquidation threshold or when borrow-rate exposure is zero.
+ *
+ * @deprecated Use `calcTimeToLiquidationMs` from `sdk/positions` instead;
+ * this wrapper only forwards to the new implementation.
  */
 declare function getTimeToLiquidation({ healthFactor, totalBorrowRate_debt }: TimeToLiquidationProps): bigint | null;
 //#endregion

package/dist/types/common-utils/utils/creditAccount/liquidation-price.d.ts

@@ -22,6 +22,9 @@ interface LiquidationPriceProps {
  * @param props Debt context, assets, thresholds, and token metadata.
  * @returns Target token price in `PRICE_DECIMALS` precision that corresponds
  * to liquidation boundary; returns `0n` when target balance or LT is non-positive.
+ *
+ * @deprecated Use `calcLiquidationPriceForTarget` from `sdk/positions`
+ * instead; this wrapper only maps the legacy props onto an `AccountSnapshot`.
  */
 declare function liquidationPrice({ liquidationThresholds, debt, underlyingToken, targetToken, assets, tokensList }: LiquidationPriceProps): bigint;
 //#endregion

package/dist/types/dev/compareOpportunities.d.ts

@@ -0,0 +1,105 @@
+import { ChainId } from "../model/primitives.js";
+import { Opportunity, OpportunityId, OpportunityKind } from "../model/opportunities.js";
+import { ChainMetadata, DataResponse } from "../model/response.js";
+import "../model/index.js";
+import { ChainCompareCounts, CompareCounts, DiffKind, DiffPathCount, ExpectedDiffReason, FieldDiff } from "./fieldDiff.js";
+import { Address } from "viem";
+//#region src/dev/compareOpportunities.d.ts
+/**
+ * Enough of an opportunity to identify it in a report without carrying the
+ * whole row.
+ **/
+interface OpportunityRef {
+  id: OpportunityId;
+  kind: OpportunityKind;
+  chainId: ChainId;
+  name: string;
+  /**
+   * Set on a pool opportunity.
+   **/
+  pool?: Address;
+  /**
+   * Set on a strategy opportunity, together with {@link targetCollateral}.
+   **/
+  creditManager?: Address;
+  targetCollateral?: Address;
+}
+/**
+ * One opportunity both sources listed, and everything they disagree on.
+ **/
+interface OpportunityMatch {
+  id: OpportunityId;
+  kind: OpportunityKind;
+  chainId: ChainId;
+  /**
+   * Name each source gave the row, which is itself a frequent diff.
+   **/
+  onchainName: string;
+  offchainName: string;
+  /**
+   * No diffs at all, including the documented offchain-only ones.
+   **/
+  identical: boolean;
+  /**
+   * No unexpected diffs: every disagreement is mode-scoped or within tolerance.
+   **/
+  clean: boolean;
+  diffs: FieldDiff[];
+}
+/**
+ * Totals of the comparison plus the fields that differed most often.
+ **/
+interface CompareSummary extends CompareCounts {
+  byChain: ChainCompareCounts[];
+  diffsByPath: DiffPathCount[];
+}
+/**
+ * Everything one comparison run produced, ready to be written out as JSON.
+ **/
+interface OpportunityCompareReport {
+  generatedAt: string;
+  backendUrl: string;
+  networks: string[];
+  /**
+   * Per-chain metadata of the on-chain read, which says which block each chain
+   * answered from.
+   **/
+  onchainChains: ChainMetadata[];
+  /**
+   * Per-chain metadata of the backend read, see {@link onchainChains}.
+   **/
+  offchainChains: ChainMetadata[];
+  summary: CompareSummary;
+  onlyOnchain: OpportunityRef[];
+  onlyOffchain: OpportunityRef[];
+  matched: OpportunityMatch[];
+}
+/**
+ * The two listings to compare, plus what the run was pointed at.
+ **/
+interface CompareOpportunitiesInput {
+  onchain: DataResponse<Opportunity[]>;
+  offchain: DataResponse<Opportunity[]>;
+  backendUrl: string;
+  networks: string[];
+  /**
+   * ISO timestamp stamped onto the report, defaulting to now. Pinned by tests.
+   **/
+  generatedAt?: string;
+}
+/**
+ * Matches two opportunity listings by {@link opportunityId} and reports every
+ * field the two sources disagree on.
+ *
+ * Nothing is filtered out. A field only the backend can fill, or a USD value
+ * that drifted within snapshot-lag noise, is still reported — tagged
+ * {@link FieldDiff.expected} so that {@link CompareCounts.clean} can ignore it
+ * while {@link CompareCounts.identical} stays strict.
+ **/
+declare function compareOpportunities(input: CompareOpportunitiesInput): OpportunityCompareReport;
+/**
+ * Every field two versions of one opportunity disagree on.
+ **/
+declare function diffOpportunity(onchain: Opportunity, offchain: Opportunity): FieldDiff[];
+//#endregion
+export { type ChainCompareCounts, type CompareCounts, CompareOpportunitiesInput, CompareSummary, type DiffKind, type DiffPathCount, type ExpectedDiffReason, type FieldDiff, OpportunityCompareReport, OpportunityMatch, OpportunityRef, compareOpportunities, diffOpportunity };

package/dist/types/dev/comparePositions.d.ts

@@ -0,0 +1,149 @@
+import { ChainId } from "../model/primitives.js";
+import { Position, PositionId, PositionKind } from "../model/positions.js";
+import { ChainMetadata, DataResponse } from "../model/response.js";
+import "../model/index.js";
+import { ChainCompareCounts, CompareCounts, DiffPathCount, FieldDiff } from "./fieldDiff.js";
+import { Address } from "viem";
+//#region src/dev/comparePositions.d.ts
+/**
+ * Enough of a position to identify it in a report without carrying the whole
+ * row.
+ **/
+interface PositionRef {
+  id: PositionId;
+  kind: PositionKind;
+  chainId: ChainId;
+  name: string;
+  /**
+   * Set on a pool position.
+   **/
+  pool?: Address;
+  /**
+   * Set on a strategy position.
+   **/
+  creditAccount?: Address;
+  creditManager?: Address;
+}
+/**
+ * One position both sources listed for a wallet, and everything they disagree
+ * on.
+ **/
+interface PositionMatch {
+  id: PositionId;
+  kind: PositionKind;
+  chainId: ChainId;
+  onchainName: string;
+  offchainName: string;
+  /**
+   * No diffs at all, including the documented mode-scoped ones.
+   **/
+  identical: boolean;
+  /**
+   * No unexpected diffs: every disagreement is mode-scoped or within tolerance.
+   **/
+  clean: boolean;
+  diffs: FieldDiff[];
+}
+/**
+ * One wallet's comparison, or the error that stopped it.
+ **/
+interface WalletComparison {
+  wallet: Address;
+  /**
+   * Why both listings of this wallet could not be read. When set, the rest of
+   * the fields are empty.
+   **/
+  error?: string;
+  onlyOnchain: PositionRef[];
+  onlyOffchain: PositionRef[];
+  matched: PositionMatch[];
+}
+/**
+ * Counts of one wallet.
+ **/
+interface WalletCompareCounts extends CompareCounts {
+  wallet: Address;
+  /**
+   * Present when the wallet's listings could not be read.
+   **/
+  error?: string;
+}
+/**
+ * Totals of the comparison plus the fields that differed most often.
+ **/
+interface PositionsCompareSummary extends CompareCounts {
+  wallets: number;
+  /**
+   * Wallets whose listings were read and that have no membership gaps and no
+   * unexpected field diffs.
+   **/
+  walletsClean: number;
+  walletsFailed: number;
+  byChain: ChainCompareCounts[];
+  byWallet: WalletCompareCounts[];
+  diffsByPath: DiffPathCount[];
+}
+/**
+ * Everything one comparison run produced, ready to be written out as JSON.
+ **/
+interface PositionsCompareReport {
+  generatedAt: string;
+  backendUrl: string;
+  networks: string[];
+  /**
+   * Per-chain metadata collected from the on-chain reads, which says which
+   * block each chain answered from. Taken from the first successful wallet
+   * listing of each chain.
+   **/
+  onchainChains: ChainMetadata[];
+  /**
+   * Per-chain metadata of the backend reads, see {@link onchainChains}.
+   **/
+  offchainChains: ChainMetadata[];
+  summary: PositionsCompareSummary;
+  wallets: WalletComparison[];
+}
+/**
+ * Both listings of one wallet.
+ **/
+interface WalletPositions {
+  wallet: Address;
+  onchain: DataResponse<Position[]>;
+  offchain: DataResponse<Position[]>;
+}
+/**
+ * A wallet whose listings could not be read from one or both sources.
+ **/
+interface WalletPositionsFailure {
+  wallet: Address;
+  error: string;
+}
+/**
+ * The per-wallet listings to compare, plus what the run was pointed at.
+ **/
+interface ComparePositionsInput {
+  wallets: WalletPositions[];
+  failures?: WalletPositionsFailure[];
+  backendUrl: string;
+  networks: string[];
+  /**
+   * ISO timestamp stamped onto the report, defaulting to now. Pinned by tests.
+   **/
+  generatedAt?: string;
+}
+/**
+ * Matches two position listings per wallet by {@link positionId} and reports
+ * every field the two sources disagree on.
+ *
+ * Nothing is filtered out. A field only one mode can fill, or a USD value that
+ * drifted within snapshot-lag noise, is still reported — tagged
+ * {@link FieldDiff.expected} so that {@link CompareCounts.clean} can ignore it
+ * while {@link CompareCounts.identical} stays strict.
+ **/
+declare function comparePositions(input: ComparePositionsInput): PositionsCompareReport;
+/**
+ * Every field two versions of one position disagree on.
+ **/
+declare function diffPosition(onchain: Position, offchain: Position): FieldDiff[];
+//#endregion
+export { ComparePositionsInput, PositionMatch, PositionRef, PositionsCompareReport, PositionsCompareSummary, WalletCompareCounts, WalletComparison, WalletPositions, WalletPositionsFailure, comparePositions, diffPosition };

package/dist/types/dev/fieldDiff.d.ts

@@ -0,0 +1,167 @@
+import { ChainId } from "../model/primitives.js";
+import "../model/index.js";
+//#region src/dev/fieldDiff.d.ts
+/**
+ * What kind of disagreement a {@link FieldDiff} describes, so that a reader can
+ * bucket the report without re-deriving it from the values.
+ *
+ * - `"presence"` — one side has no value at all (`undefined` or `null`).
+ * - `"usd"` — an {@link Amount.valueUsd}, i.e. a price-derived float.
+ * - `"numeric"` — any other number or bigint.
+ * - `"other"` — everything else: strings, booleans, array shapes.
+ **/
+type DiffKind = "presence" | "usd" | "numeric" | "other";
+/**
+ * Why a {@link FieldDiff} is expected rather than a real disagreement.
+ *
+ * - `"mode-scoped"` — a field documented `@mode offchain` or `@mode onchain`,
+ *   so the other source has nothing to put there.
+ * - `"tolerance"` — snapshot lag or float-path noise within the thresholds
+ *   below, not a formula or membership mismatch.
+ **/
+type ExpectedDiffReason = "mode-scoped" | "tolerance";
+/**
+ * One field of one row where the two sources disagree.
+ **/
+interface FieldDiff {
+  /**
+   * Dotted path into the row, with array elements keyed by their own identity
+   * rather than by index, e.g. `collateralTokens[0xa0b8...].symbol`.
+   **/
+  path: string;
+  /**
+   * Value the chain reported, `undefined` when it has no such field.
+   **/
+  onchain: unknown;
+  /**
+   * Value the backend reported, see {@link onchain}.
+   **/
+  offchain: unknown;
+  kind: DiffKind;
+  /**
+   * Present when this disagreement is documented or within snapshot-lag noise,
+   * so it does not keep the row from being counted as clean.
+   **/
+  expected?: true;
+  reason?: ExpectedDiffReason;
+}
+/**
+ * How often one field disagreed across all matched rows, with array keys
+ * collapsed, e.g. `collateralTokens[].symbol`.
+ **/
+interface DiffPathCount {
+  path: string;
+  kinds: DiffKind[];
+  count: number;
+  expected: number;
+  unexpected: number;
+}
+/**
+ * Counts of one chain, one wallet, or of the whole report when those ids are
+ * absent.
+ **/
+interface CompareCounts {
+  onchainRows: number;
+  offchainRows: number;
+  matched: number;
+  identical: number;
+  /**
+   * Matched rows with no unexpected diffs, including the identical ones.
+   **/
+  clean: number;
+  differing: number;
+  onlyOnchain: number;
+  onlyOffchain: number;
+}
+/**
+ * Counts of one chain.
+ **/
+interface ChainCompareCounts extends CompareCounts {
+  chainId: ChainId;
+}
+/**
+ * Identity of an array element, used so a token present on one side only is
+ * reported as such rather than shifting every later element into a diff.
+ *
+ * Return a string to key the element; `undefined` falls back to the default
+ * (`address`, `id`, `token`, or nested `token.address`).
+ **/
+type ArrayElementKey = (path: string, value: unknown) => string | undefined;
+/**
+ * How to walk two values. Callers that need identity-bearing arrays whose
+ * key is not one of the defaults pass {@link DiffOptions.keyOf}.
+ **/
+interface DiffOptions {
+  keyOf?: ArrayElementKey;
+}
+/**
+ * Relative drift allowed on {@link Amount.valueUsd} before a USD float is a
+ * real disagreement: 0.1%.
+ **/
+declare const USD_RELATIVE_EPSILON = 0.001;
+/**
+ * Relative drift allowed on lag-bounded bigint amounts: 0.05%.
+ **/
+declare const AMOUNT_RELATIVE_EPSILON = 0.0005;
+/**
+ * Absolute drift allowed on bps rates before rounding and a one-block lag are
+ * no longer enough to explain it.
+ **/
+declare const BPS_ABSOLUTE_EPSILON = 1;
+/**
+ * Every field two versions of one value disagree on. Nothing is filtered or
+ * tagged: the caller marks expected diffs afterwards.
+ **/
+declare function diffValue(path: string, onchain: unknown, offchain: unknown, out: FieldDiff[], options?: DiffOptions): void;
+/**
+ * Deep-diff two values and return the disagreements, in path order of
+ * discovery.
+ **/
+declare function diffObjects(onchain: unknown, offchain: unknown, options?: DiffOptions): FieldDiff[];
+/**
+ * Mark a diff expected, so a later `clean` count can ignore it.
+ **/
+declare function withExpected(diff: FieldDiff, reason: ExpectedDiffReason): FieldDiff;
+/**
+ * How often each field differed, with array keys collapsed so that the same
+ * field of a hundred collateral tokens counts as one path. Sorted so the
+ * unexpected disagreements come first.
+ **/
+declare function countPaths(diffs: Iterable<FieldDiff>): DiffPathCount[];
+/**
+ * Collapse `collateralTokens[0xa0b8...].symbol` to `collateralTokens[].symbol`.
+ **/
+declare function collapseArrayKeys(path: string): string;
+/**
+ * Membership and match totals of one comparison, from already-built lists.
+ **/
+declare function toCompareCounts(onchainRows: number, offchainRows: number, onlyOnchain: number, onlyOffchain: number, matched: ReadonlyArray<{
+  identical: boolean;
+  clean: boolean;
+}>): CompareCounts;
+/**
+ * USD floats within {@link USD_RELATIVE_EPSILON}.
+ **/
+declare function isUsdWithinTolerance(onchain: unknown, offchain: unknown): boolean;
+/**
+ * Bps rates that differ by at most {@link BPS_ABSOLUTE_EPSILON}.
+ **/
+declare function isBpsWithinTolerance(onchain: unknown, offchain: unknown): boolean;
+/**
+ * Bigint amounts within {@link AMOUNT_RELATIVE_EPSILON}.
+ **/
+declare function isAmountWithinTolerance(onchain: unknown, offchain: unknown): boolean;
+/**
+ * Finite numbers within a relative epsilon of each other.
+ **/
+declare function withinRelative(onchain: number | undefined, offchain: number | undefined, epsilon: number): boolean;
+/**
+ * `diff / max(|a|, |b|) <= epsilon`, computed in integer arithmetic so a
+ * 1e18-scale amount does not round through `Number`.
+ **/
+declare function withinRelativeBigint(onchain: bigint, offchain: bigint, epsilon: number): boolean;
+declare function asFiniteNumber(value: unknown): number | undefined;
+declare function union(left: string[], right: string[]): string[];
+declare function isRecord(value: unknown): value is Record<string, unknown>;
+//#endregion
+export { AMOUNT_RELATIVE_EPSILON, ArrayElementKey, BPS_ABSOLUTE_EPSILON, ChainCompareCounts, CompareCounts, DiffKind, DiffOptions, DiffPathCount, ExpectedDiffReason, FieldDiff, USD_RELATIVE_EPSILON, asFiniteNumber, collapseArrayKeys, countPaths, diffObjects, diffValue, isAmountWithinTolerance, isBpsWithinTolerance, isRecord, isUsdWithinTolerance, toCompareCounts, union, withExpected, withinRelative, withinRelativeBigint };