@gauntlet-xyz/sdk 2.5.0 → 3.1.1

package/src/api/http.ts

@@ -39,6 +39,7 @@ export async function apiGet<T>(
 
   const fetchImpl = config.fetch ?? fetch;
   const response = await fetchImpl(url, {
+    redirect: 'error',
     headers: {
       accept: 'application/json',
       ...(config.apiKey ? { 'x-api-key': config.apiKey } : {}),

package/src/api/index.ts

@@ -19,7 +19,10 @@ export type {
   TimeseriesMeta,
   TimeWindowOptions,
   TokenRef,
+  TvlBreakdownMode,
   TvlResponse,
+  TvlTimeseriesPoint,
+  TvlTimeseriesResponse,
   UserActivity,
   UserActivityResponse,
   UserAllPositionsResponse,
@@ -28,7 +31,12 @@ export type {
   UserPositionsTimeseriesResponse,
   VaultDetail,
   VaultDetailResponse,
+  VaultAllocations,
+  VaultAllocationsResponse,
   VaultMetrics,
+  VaultsOptions,
+  VaultGroupTimeseriesPoint,
+  VaultGroupTimeseriesResponse,
   VaultTimeseriesPoint,
   VaultTimeseriesResponse,
 } from './client';

package/src/api/positionHistory.ts

@@ -1,3 +1,4 @@
+import { activityLifecycles, orderActivityRows, requireSameToken } from './activityRows';
 import { GauntletSDKError } from '../errors';
 import type { GauntletApi, TokenRef, UserActivity } from './client';
 import { bigIntToDecimal, decimalToBigInt, sharesToBigInt } from './decimal';
@@ -57,8 +58,11 @@ export function buildPositionHistory(rows: UserActivity[]): PositionHistory {
     );
   }
 
-  const ordered = [...rows].sort((a, b) => a.block_timestamp - b.block_timestamp);
-  const token = ordered.find((r) => r.assets_delta.token)?.assets_delta.token ?? null;
+  const ordered = orderActivityRows(rows);
+  activityLifecycles(ordered);
+  const tokenRow = ordered.find((r) => r.assets_delta.token) ?? ordered[0];
+  const token = tokenRow.assets_delta.token ?? null;
+  for (const row of ordered) requireSameToken(tokenRow, row);
 
   let sharesBalance = 0n;
   let pendingDepositAssets = 0n;
@@ -95,9 +99,14 @@ export function buildPositionHistory(rows: UserActivity[]): PositionHistory {
         if (row.request_hash != null) pendingDepositByHash.set(row.request_hash, assetsDelta);
         break;
       case 'deposit_refunded':
-        // Row carries the unwound request as a negative delta.
+        if (
+          row.request_hash == null ||
+          pendingDepositByHash.get(row.request_hash) !== -assetsDelta
+        ) {
+          throw new GauntletSDKError('The deposit refund does not match its escrow');
+        }
         pendingDepositAssets += assetsDelta;
-        if (row.request_hash != null) pendingDepositByHash.delete(row.request_hash);
+        pendingDepositByHash.delete(row.request_hash);
         break;
       case 'withdraw':
         // Sync withdraws and async terminal solves both carry the asset
@@ -121,8 +130,11 @@ export function buildPositionHistory(rows: UserActivity[]): PositionHistory {
         break;
       }
       case 'withdraw_refunded':
+        if (row.request_hash == null || pendingRedeemByHash.get(row.request_hash) !== sharesDelta) {
+          throw new GauntletSDKError('The withdrawal refund does not match its escrow');
+        }
         pendingRedeemShares -= sharesDelta;
-        if (row.request_hash != null) pendingRedeemByHash.delete(row.request_hash);
+        pendingRedeemByHash.delete(row.request_hash);
         break;
       case 'transfer_in':
       case 'transfer_out':
@@ -131,6 +143,9 @@ export function buildPositionHistory(rows: UserActivity[]): PositionHistory {
         throw new GauntletSDKError(`Unknown activity row type "${row.type}"`);
     }
 
+    if (sharesBalance < 0n || pendingDepositAssets < 0n || pendingRedeemShares < 0n) {
+      throw new GauntletSDKError('The activity history produces a negative position balance');
+    }
     points.push({
       timestamp: new Date(row.block_timestamp * 1000),
       txHash: row.tx_hash,

package/src/attribution/index.ts

@@ -8,13 +8,14 @@ export { encodeBuilderCode } from './erc8021';
 export type PreparedPayloadWithAttribution = {
   type: string;
   to: Address;
+  chainId: number;
   data: Hex;
   account?: Address;
 };
 
 export type PreparedTx = {
   payload: PreparedPayloadWithAttribution;
-  tx: TxStep;
+  tx: TxStep & { chainId: number };
 };
 
 /**
@@ -38,7 +39,8 @@ export async function buildAttribution(client: GauntletClient): Promise<Hex> {
 
 export async function encodeTransactionWithAttribution(
   client: GauntletClient,
-  transaction: TxStep
+  transaction: TxStep,
+  chainId: number
 ): Promise<PreparedTx> {
   const customAttribution = await buildAttribution(client);
   const encodedTx = encodeFunctionData({
@@ -52,10 +54,12 @@ export async function encodeTransactionWithAttribution(
       type: transaction.type,
       account: transaction.account,
       to: transaction.address,
+      chainId,
       data: encodedTxWithAttribution,
     },
     tx: {
       ...transaction,
+      chainId,
       attribution: customAttribution,
     },
   };

package/src/client.ts

@@ -20,6 +20,9 @@ export enum AttributionMode {
 
 export type ChainId = string | number;
 
+/** The static vault manifest bundled with this SDK release; the GauntletClient default. */
+export const bundledVaultManifest = bundledManifest as VaultManifest;
+
 export interface GauntletClientConfig {
   /** Gaia API key, sent as `x-api-key` on `client.api` requests. Anonymous access is rate-limited. */
   apiKey?: string;
@@ -68,7 +71,7 @@ export class GauntletClient {
   /** Typed client for the Gaia REST API (vaults, positions, activity, tvl, prices). */
   readonly api: GauntletApi;
 
-  private _manifest: VaultManifest = bundledManifest as VaultManifest;
+  private _manifest: VaultManifest = bundledVaultManifest;
 
   constructor(config: GauntletClientConfig) {
     this.apiKey = config.apiKey;

package/src/constants.ts

@@ -17,6 +17,7 @@ export const CHAIN_NAMES: Record<number, string> = {
   8453: 'base',
   42161: 'arbitrum',
   10: 'optimism',
+  5042: 'arc',
 };
 
 // Approximate 3-day block lookback per chain based on avg block time.
@@ -25,6 +26,7 @@ export const BLOCKS_3_DAYS: Record<number, bigint> = {
   8453: 129_600n,
   42161: 1_036_800n,
   10: 129_600n,
+  5042: 518_400n,
 };
 export const DEFAULT_BLOCKS_3_DAYS = 129_600n;
 

package/src/errors.ts

@@ -202,3 +202,10 @@ export class InvalidSlippageBPSError extends GauntletSDKError {
     this.slippage = slippage;
   }
 }
+
+export class InvalidSyncDepositBoundError extends GauntletSDKError {
+  constructor() {
+    super('Sync deposit minUnitsOut requires explicit sync mode and must be greater than zero');
+    this.name = 'InvalidSyncDepositBoundError';
+  }
+}

package/src/evm/adapters/aera.ts

@@ -225,6 +225,7 @@ export const aeraAdapter: EvmProtocolAdapter = {
       solverTip = DEFAULT_SOLVER_TIP,
       maxPriceAge = DEFAULT_MAX_PRICE_AGE,
       aeraRuntime,
+      minUnitsOut: requestedMinUnitsOut,
     } = params;
 
     const runtime = requireAeraRuntime(aeraRuntime);
@@ -238,17 +239,19 @@ export const aeraAdapter: EvmProtocolAdapter = {
       throw new UnsupportedFeatureError('Aera: sync operations on V1');
     }
 
-    const tokensInForUnits = isAsync ? subtractSolverTip(amount, solverTip) : amount;
-    const vaultUnits = await getDepositUnitsOut({
-      publicClient,
-      runtime,
-      vault: vault.vaultAddress,
-      token: asset.address,
-      tokensIn: tokensInForUnits,
-      isAsync,
-    });
-
-    const minUnitsOut = applySlippageDown(vaultUnits, slippageBps);
+    const minUnitsOut =
+      requestedMinUnitsOut ??
+      applySlippageDown(
+        await getDepositUnitsOut({
+          publicClient,
+          runtime,
+          vault: vault.vaultAddress,
+          token: asset.address,
+          tokensIn: isAsync ? subtractSolverTip(amount, solverTip) : amount,
+          isAsync,
+        }),
+        slippageBps
+      );
 
     if (isAsync) {
       const deadline = getRequestDeadline(vault.expirationDays);
@@ -427,17 +430,35 @@ export const aeraAdapter: EvmProtocolAdapter = {
         throw new InvalidWithdrawParamsError();
       }
 
-      const tokenOutBeforeTip = await getAsyncRedeemTokenOut(
-        publicClient,
-        runtime,
-        vault.vaultAddress,
-        asset.address,
-        shares
-      );
-      minTokenOut = applySlippageDown(subtractSolverTip(tokenOutBeforeTip, solverTip), slippageBps);
+      const tokensOut =
+        'amount' in params && params.amount != null
+          ? params.amount
+          : subtractSolverTip(
+              await getAsyncRedeemTokenOut(
+                publicClient,
+                runtime,
+                vault.vaultAddress,
+                asset.address,
+                shares
+              ),
+              solverTip
+            );
+      minTokenOut = applySlippageDown(tokensOut, slippageBps);
       maxUnitsIn = shares;
     }
 
+    if (params.maxShares !== undefined) {
+      if (
+        isAsync ||
+        typeof params.maxShares !== 'bigint' ||
+        params.maxShares <= 0n ||
+        (!isV2ExactTokenWithdraw && shares !== undefined && shares > params.maxShares)
+      ) {
+        throw new InvalidWithdrawParamsError();
+      }
+      if (maxUnitsIn > params.maxShares) maxUnitsIn = params.maxShares;
+    }
+
     const steps: EvmTxStep[] = [];
 
     if (isAsync) {

package/src/evm/adapters/types.ts

@@ -38,6 +38,8 @@ export interface AdapterDepositParams {
   /** Maximum price age passed to async Aera provisioner requests. Defaults to 10 days. */
   maxPriceAge?: bigint;
   aeraRuntime?: AeraRuntimeContracts;
+  /** Caller-reviewed minimum output for an explicit synchronous deposit. */
+  minUnitsOut?: bigint;
 }
 
 export type AdapterWithdrawParams = {
@@ -55,6 +57,7 @@ export type AdapterWithdrawParams = {
   maxPriceAge?: bigint;
   aeraRuntime?: AeraRuntimeContracts;
   syncWithdrawQuote?: SyncWithdrawQuoteBounds;
+  maxShares?: bigint;
 } & (
   | { shares: bigint; amount?: never; entireAmount?: never }
   | { amount: bigint; shares?: never; entireAmount?: never }

package/src/evm/aeraContracts/v2.ts

@@ -4,11 +4,14 @@ import {
   type GetContractReturnType,
   type PublicClient,
   getContract,
+  zeroAddress,
 } from 'viem';
+import { erc20Abi } from '../abis/erc20';
 import { priceAndFeeCalculatorV2Abi } from '../abis/priceAndFeeCalculatorV2';
 import { provisionerV2Abi } from '../abis/provisionerV2';
 import {
   Rounding,
+  convertTokenToNumeraire,
   convertTokenToUnitsIfActive,
   convertUnitsToTokenIfActive,
 } from './priceAndFeeCalculator';
@@ -74,7 +77,31 @@ async function getTokenDetails(
   });
 }
 
-async function getDepositUnitsOut({
+/**
+ * Returns the vault's currently known sync-redeem liquidity in tokens.
+ *
+ * When a pull-funds pointer is configured, the provisioner may source more tokens during the
+ * redemption, so the vault's current token balance is not a reliable liquidity limit.
+ */
+export async function getKnownSyncRedeemLiquidityTokens(
+  client: PublicClient,
+  vault: Address,
+  token: Address,
+  hasPullFundsSubmitData: boolean,
+  options: SyncRedeemReadOptions = {}
+): Promise<bigint | undefined> {
+  if (hasPullFundsSubmitData) return undefined;
+
+  return client.readContract({
+    address: token,
+    abi: erc20Abi,
+    functionName: 'balanceOf',
+    args: [vault],
+    ...readAtBlock(options),
+  });
+}
+
+async function getDepositQuote({
   client,
   provisioner,
   feeCalculator,
@@ -94,12 +121,12 @@ async function getDepositUnitsOut({
   tokensIn: bigint;
   multiplierIndex: 4 | 6;
   options?: SyncRedeemReadOptions;
-}): Promise<bigint> {
+}): Promise<{ unitsOut: bigint; multiplierBps: bigint }> {
   const tokenDetails = await getTokenDetails(client, provisioner, token, options);
-  const multiplier = BigInt(tokenDetails[multiplierIndex]);
-  const adjustedTokensIn = (tokensIn * multiplier) / MAX_BPS;
+  const multiplierBps = BigInt(tokenDetails[multiplierIndex]);
+  const adjustedTokensIn = (tokensIn * multiplierBps) / MAX_BPS;
 
-  return convertTokenToUnitsIfActive(
+  const unitsOut = await convertTokenToUnitsIfActive(
     client,
     feeCalculator,
     feeCalculatorVersion,
@@ -109,6 +136,8 @@ async function getDepositUnitsOut({
     Rounding.Floor,
     options
   );
+
+  return { unitsOut, multiplierBps };
 }
 
 async function getRedeemTokenOut({
@@ -198,20 +227,22 @@ export interface SyncRedeemRate {
 }
 
 /**
- * Reads the live sync redeem rate, replicating the provisioner's effective-multiplier
- * derivation (base multiplier minus a price-age-proportional dynamic premium).
+ * Reads the live sync redeem rate and whether pull-funds calldata is configured.
+ *
+ * Both values come from the same token-details read, avoiding another RPC request when a quote
+ * needs to determine whether the vault balance is a reliable liquidity limit.
  *
  * @throws {StalePriceError} If the oracle price is older than the configured max age,
  *   in which case the on-chain sync redeem would revert.
  */
-export async function getSyncRedeemRate(
+export async function getSyncRedeemRateContext(
   client: PublicClient,
   provisioner: Address,
   vault: Address,
   token: Address,
   feeCalculator: Address,
   options: SyncRedeemReadOptions = {}
-): Promise<SyncRedeemRate> {
+): Promise<{ rate: SyncRedeemRate; hasPullFundsSubmitData: boolean }> {
   const readContext = await resolveReadContext(client, options);
   const [tokenDetails, syncRedeemDetails, anchorTimestamp] = await client.multicall({
     contracts: [
@@ -256,12 +287,28 @@ export async function getSyncRedeemRate(
       : ((blockTimestamp - priceTimestamp) * maxDynamicPremiumBps + maxPriceAge - 1n) / maxPriceAge;
 
   return {
-    baseMultiplierBps,
-    dynamicPremiumBps,
-    effectiveMultiplierBps: baseMultiplierBps - dynamicPremiumBps,
+    rate: {
+      baseMultiplierBps,
+      dynamicPremiumBps,
+      effectiveMultiplierBps: baseMultiplierBps - dynamicPremiumBps,
+    },
+    hasPullFundsSubmitData: tokenDetails[9] !== zeroAddress,
   };
 }
 
+/** Preserves the existing rate-only API for callers that do not need pull-funds state. */
+export async function getSyncRedeemRate(
+  client: PublicClient,
+  provisioner: Address,
+  vault: Address,
+  token: Address,
+  feeCalculator: Address,
+  options: SyncRedeemReadOptions = {}
+): Promise<SyncRedeemRate> {
+  return (await getSyncRedeemRateContext(client, provisioner, vault, token, feeCalculator, options))
+    .rate;
+}
+
 async function getSyncRedeemMultiplier(
   client: PublicClient,
   provisioner: Address,
@@ -315,7 +362,7 @@ export async function getAsyncDepositUnitsOut(
   token: Address,
   tokensIn: bigint
 ): Promise<bigint> {
-  return getDepositUnitsOut({
+  const quote = await getDepositQuote({
     client,
     provisioner,
     feeCalculator,
@@ -325,9 +372,10 @@ export async function getAsyncDepositUnitsOut(
     tokensIn,
     multiplierIndex: 4,
   });
+  return quote.unitsOut;
 }
 
-export async function getSyncDepositUnitsOut(
+const getSyncDepositQuote = (
   client: PublicClient,
   provisioner: Address,
   feeCalculator: Address,
@@ -335,8 +383,8 @@ export async function getSyncDepositUnitsOut(
   vault: Address,
   token: Address,
   tokensIn: bigint
-): Promise<bigint> {
-  return getDepositUnitsOut({
+) =>
+  getDepositQuote({
     client,
     provisioner,
     feeCalculator,
@@ -346,6 +394,66 @@ export async function getSyncDepositUnitsOut(
     tokensIn,
     multiplierIndex: 6,
   });
+
+export async function getSyncDepositUnitsOut(
+  client: PublicClient,
+  provisioner: Address,
+  feeCalculator: Address,
+  feeCalculatorVersion: ContractVersion,
+  vault: Address,
+  token: Address,
+  tokensIn: bigint
+): Promise<bigint> {
+  const quote = await getSyncDepositQuote(
+    client,
+    provisioner,
+    feeCalculator,
+    feeCalculatorVersion,
+    vault,
+    token,
+    tokensIn
+  );
+  return quote.unitsOut;
+}
+
+export async function getSyncDepositQuoteValues(
+  client: PublicClient,
+  provisioner: Address,
+  feeCalculator: Address,
+  feeCalculatorVersion: ContractVersion,
+  vault: Address,
+  token: Address,
+  tokensIn: bigint
+): Promise<{ unitsOut: bigint; feeBps: bigint; numeraireOut: bigint }> {
+  const { unitsOut, multiplierBps } = await getSyncDepositQuote(
+    client,
+    provisioner,
+    feeCalculator,
+    feeCalculatorVersion,
+    vault,
+    token,
+    tokensIn
+  );
+  const numeraireOut = await convertTokenToNumeraire(
+    client,
+    feeCalculator,
+    feeCalculatorVersion,
+    vault,
+    token,
+    (tokensIn * multiplierBps) / MAX_BPS
+  );
+  return { unitsOut, feeBps: MAX_BPS - multiplierBps, numeraireOut };
+}
+
+/** Reads the live Instant Supply fee for a vault token, independent of the deposit amount. */
+export async function getSyncDepositFeeBps(
+  client: PublicClient,
+  provisioner: Address,
+  token: Address,
+  options: SyncRedeemReadOptions = {}
+): Promise<bigint> {
+  const tokenDetails = await getTokenDetails(client, provisioner, token, options);
+  return MAX_BPS - BigInt(tokenDetails[6]);
 }
 
 export async function getAsyncRedeemTokenOut(

package/src/evm/aeraContracts.ts

@@ -17,8 +17,6 @@ import { MAX_BPS } from '../constants';
 import { ContractVersion, type EvmVaultDeployment } from './types';
 import { readAtBlock } from './aeraContracts/readOptions';
 
-const contractVersionCache = new Map<string, ContractVersion>();
-
 const contractVersionAbi = [
   {
     type: 'function',
@@ -81,10 +79,6 @@ export function applySlippageUp(amount: bigint, slippageBps: number): bigint {
   return (amount * (MAX_BPS + BigInt(slippageBps)) + MAX_BPS - 1n) / MAX_BPS;
 }
 
-function contractVersionCacheKey(client: PublicClient, address: Address): string {
-  return `${client.chain?.id ?? 'unknown'}:${address.toLowerCase()}`;
-}
-
 function isVersionUnavailableError(error: unknown): boolean {
   if (!(error instanceof ContractFunctionExecutionError) || error.functionName !== 'version') {
     return false;
@@ -122,15 +116,35 @@ export function getMultiDepositorVault<T extends Client>(
   });
 }
 
+// Latest-block versions per client. Historical reads and failed reads are not cached.
+const latestContractVersions = new WeakMap<PublicClient, Map<string, ContractVersion>>();
+
 export async function resolveContractVersion(
   client: PublicClient,
   address: Address,
   options: AeraReadOptions = {}
 ): Promise<ContractVersion> {
-  const cacheKey = contractVersionCacheKey(client, address);
-  const cached = contractVersionCache.get(cacheKey);
-  if (cached) return cached;
+  if (options.blockNumber !== undefined) return readContractVersion(client, address, options);
 
+  let versions = latestContractVersions.get(client);
+  if (versions === undefined) {
+    versions = new Map();
+    latestContractVersions.set(client, versions);
+  }
+  const key = address.toLowerCase();
+  const cached = versions.get(key);
+  if (cached !== undefined) return cached;
+
+  const version = await readContractVersion(client, address, options);
+  versions.set(key, version);
+  return version;
+}
+
+async function readContractVersion(
+  client: PublicClient,
+  address: Address,
+  options: AeraReadOptions
+): Promise<ContractVersion> {
   try {
     const versionString = await client.readContract({
       address,
@@ -138,14 +152,15 @@ export async function resolveContractVersion(
       functionName: 'version',
       ...readAtBlock(options),
     });
-    const version = versionString.startsWith('2.') ? ContractVersion.V2 : ContractVersion.V1;
-    contractVersionCache.set(cacheKey, version);
-
-    return version;
+    if (!/^[12]\./.test(versionString)) {
+      throw new UnsupportedFeatureError(`Aera: unsupported contract version ${versionString}`);
+    }
+    return versionString.startsWith('2.') ? ContractVersion.V2 : ContractVersion.V1;
   } catch (error) {
     if (!isVersionUnavailableError(error)) throw error;
 
-    contractVersionCache.set(cacheKey, ContractVersion.V1);
+    const code = await client.getCode({ address, ...readAtBlock(options) });
+    if (code === undefined || code === '0x') throw error;
     return ContractVersion.V1;
   }
 }