@gauntlet-xyz/sdk 2.3.0 → 3.0.1

package/src/api/index.ts

@@ -3,18 +3,26 @@ export type {
   ActivityOptions,
   AmountPair,
   ChainSyncStatus,
+  FeaturedVault,
+  FeaturedVaultsResponse,
   HealthResponse,
   LatestPriceOptions,
   LatestPriceResponse,
   PageOptions,
   PartialResponseError,
+  PositionsOptions,
   PositionTimeseriesPoint,
   PriceTimeseriesOptions,
   PriceTimeseriesResponse,
+  StrategyCard,
+  StrategyListResponse,
   TimeseriesMeta,
   TimeWindowOptions,
   TokenRef,
+  TvlBreakdownMode,
   TvlResponse,
+  TvlTimeseriesPoint,
+  TvlTimeseriesResponse,
   UserActivity,
   UserActivityResponse,
   UserAllPositionsResponse,
@@ -23,7 +31,12 @@ export type {
   UserPositionsTimeseriesResponse,
   VaultDetail,
   VaultDetailResponse,
+  VaultAllocations,
+  VaultAllocationsResponse,
   VaultMetrics,
+  VaultsOptions,
+  VaultGroupTimeseriesPoint,
+  VaultGroupTimeseriesResponse,
   VaultTimeseriesPoint,
   VaultTimeseriesResponse,
 } from './client';

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

@@ -53,7 +53,7 @@ export class UnsupportedDepositModeError extends GauntletSDKError {
   readonly available: string;
 
   constructor(vaultId: string, requested: string, available: string) {
-    super(`Vault "${vaultId}" does not support ${requested} deposits (available: ${available})`);
+    super(`Vault "${vaultId}" does not support ${requested} operations (available: ${available})`);
     this.name = 'UnsupportedDepositModeError';
     this.vaultId = vaultId;
     this.requested = requested;
@@ -73,11 +73,25 @@ export class RpcNotConfiguredError extends GauntletSDKError {
 
 export class AccountRequiredError extends GauntletSDKError {
   constructor() {
-    super('No account specified. Provide a wallet in the client config.');
+    super(
+      'No account specified. Pass the required account, or configure a wallet when building transactions.'
+    );
     this.name = 'AccountRequiredError';
   }
 }
 
+export class AccountMismatchError extends GauntletSDKError {
+  readonly expected: string;
+  readonly received: string;
+
+  constructor(expected: string, received: string) {
+    super(`Account mismatch: expected "${expected}", received "${received}"`);
+    this.name = 'AccountMismatchError';
+    this.expected = expected;
+    this.received = received;
+  }
+}
+
 export class UnsupportedProtocolError extends GauntletSDKError {
   readonly protocol: string;
 
@@ -95,6 +109,22 @@ export class InvalidWithdrawParamsError extends GauntletSDKError {
   }
 }
 
+export type SyncWithdrawBound = 'tokensOut' | 'minTokensOut' | 'unitsIn' | 'maxUnitsIn';
+
+export class InvalidSyncWithdrawBoundError extends GauntletSDKError {
+  readonly bound: SyncWithdrawBound;
+
+  constructor(bound: SyncWithdrawBound) {
+    super(`Sync withdraw cannot submit zero ${bound}; increase the amount or reduce slippage`);
+    this.name = 'InvalidSyncWithdrawBoundError';
+    this.bound = bound;
+  }
+}
+
+export function requireNonZeroSyncWithdrawBound(value: bigint, bound: SyncWithdrawBound) {
+  if (value === 0n) throw new InvalidSyncWithdrawBoundError(bound);
+}
+
 export class UnimplementedFeatureError extends GauntletSDKError {
   readonly feature: string;
 
@@ -172,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/abis/priceAndFeeCalculatorV2.ts

@@ -47,6 +47,28 @@ export const priceAndFeeCalculatorV2Abi = [
     outputs: [{ name: 'tokenAmount', internalType: 'uint256', type: 'uint256' }],
     stateMutability: 'view',
   },
+  {
+    type: 'function',
+    inputs: [
+      { name: 'vault', internalType: 'address', type: 'address' },
+      { name: 'token', internalType: 'contract IERC20', type: 'address' },
+      { name: 'tokenAmount', internalType: 'uint256', type: 'uint256' },
+    ],
+    name: 'convertTokenToNumeraire',
+    outputs: [{ name: 'numeraireAmount', internalType: 'uint256', type: 'uint256' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    inputs: [
+      { name: 'vault', internalType: 'address', type: 'address' },
+      { name: 'token', internalType: 'contract IERC20', type: 'address' },
+      { name: 'numeraireAmount', internalType: 'uint256', type: 'uint256' },
+    ],
+    name: 'convertNumeraireToToken',
+    outputs: [{ name: 'tokenAmount', internalType: 'uint256', type: 'uint256' }],
+    stateMutability: 'view',
+  },
   {
     type: 'function',
     inputs: [{ name: 'vault', internalType: 'address', type: 'address' }],

package/src/evm/abis/provisionerV2.ts

@@ -1,6 +1,13 @@
 // Compact ABI derived from aera-finance/aera-contracts-v3@f4e3433058c29c3a0b1348ffbd358cc036a1687f
 // source: src/core/interfaces/IProvisionerV2.sol
 export const provisionerV2Abi = [
+  {
+    type: 'function',
+    inputs: [],
+    name: 'SOLVING_GATE_ENABLED',
+    outputs: [{ name: '', internalType: 'bool', type: 'bool' }],
+    stateMutability: 'view',
+  },
   {
     type: 'function',
     inputs: [
@@ -53,6 +60,25 @@ export const provisionerV2Abi = [
     ],
     stateMutability: 'view',
   },
+  {
+    type: 'function',
+    inputs: [],
+    name: 'getSyncRedeemEpochState',
+    outputs: [
+      { name: 'epochTimestamp', internalType: 'uint256', type: 'uint256' },
+      { name: 'epochStartTvlNumeraire', internalType: 'uint256', type: 'uint256' },
+      { name: 'epochRedeemedNumeraire', internalType: 'uint256', type: 'uint256' },
+      { name: 'epochCapNumeraire', internalType: 'uint256', type: 'uint256' },
+    ],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    inputs: [{ name: 'user', internalType: 'address', type: 'address' }],
+    name: 'userUnitsRefundableUntil',
+    outputs: [{ name: 'unitsLockedUntil', internalType: 'uint256', type: 'uint256' }],
+    stateMutability: 'view',
+  },
   {
     type: 'function',
     inputs: [
@@ -63,6 +89,13 @@ export const provisionerV2Abi = [
     outputs: [],
     stateMutability: 'nonpayable',
   },
+  {
+    type: 'function',
+    inputs: [],
+    name: 'solvingGate',
+    outputs: [{ name: '', internalType: 'address', type: 'address' }],
+    stateMutability: 'view',
+  },
   {
     type: 'function',
     inputs: [{ name: 'token', internalType: 'contract IERC20', type: 'address' }],

package/src/evm/adapters/aera.ts

@@ -3,6 +3,7 @@ import {
   getMultiDepositorVault,
   applySlippageDown,
   applySlippageUp,
+  requireAeraSyncRedeemRuntime,
   resolveContractVersion,
   type AeraRuntimeContracts,
 } from '../aeraContracts';
@@ -12,6 +13,7 @@ import * as provisionerV2 from '../aeraContracts/v2';
 import {
   InvalidWithdrawParamsError,
   InvalidSolverTipError,
+  requireNonZeroSyncWithdrawBound,
   UnimplementedFeatureError,
   UnsupportedFeatureError,
 } from '../../errors';
@@ -223,6 +225,7 @@ export const aeraAdapter: EvmProtocolAdapter = {
       solverTip = DEFAULT_SOLVER_TIP,
       maxPriceAge = DEFAULT_MAX_PRICE_AGE,
       aeraRuntime,
+      minUnitsOut: requestedMinUnitsOut,
     } = params;
 
     const runtime = requireAeraRuntime(aeraRuntime);
@@ -236,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);
@@ -321,9 +326,7 @@ export const aeraAdapter: EvmProtocolAdapter = {
       throw new UnsupportedFeatureError('Aera: separate receiver address on V1');
     }
 
-    if (!isAsync && !isContractV2) {
-      throw new UnsupportedFeatureError('Aera: sync operations on V1');
-    }
+    if (!isAsync) requireAeraSyncRedeemRuntime(runtime);
 
     const isV2ExactTokenWithdraw =
       isContractV2 && !isAsync && 'amount' in params && params.amount != null;
@@ -332,40 +335,66 @@ export const aeraAdapter: EvmProtocolAdapter = {
     let shares: bigint | undefined;
 
     if (isContractV2 && !isAsync) {
+      const quote = params.syncWithdrawQuote;
       if ('entireAmount' in params && params.entireAmount) {
-        shares = await publicClient.readContract({
+        const balance = await publicClient.readContract({
           address: vault.vaultAddress,
           abi: multiDepositorVaultAbi,
           functionName: 'balanceOf',
           args: [account],
         });
+        if (quote !== undefined) {
+          if (quote.kind !== 'redeem' || quote.shares !== balance) {
+            throw new InvalidWithdrawParamsError();
+          }
+        }
+        shares = balance;
       } else if ('shares' in params && params.shares != null) {
+        if (quote !== undefined && (quote.kind !== 'redeem' || quote.shares !== params.shares)) {
+          throw new InvalidWithdrawParamsError();
+        }
         shares = params.shares;
       } else if (!('amount' in params && params.amount != null)) {
         throw new InvalidWithdrawParamsError();
       }
 
       if (isV2ExactTokenWithdraw) {
-        minTokenOut = applySlippageDown(params.amount, slippageBps);
-        maxUnitsIn = applySlippageUp(
-          await provisionerV2.getSyncWithdrawUnitsIn(
-            publicClient,
-            provisionerAddress,
-            runtime.feeCalculator.address,
-            runtime.feeCalculator.version,
-            vault.vaultAddress,
-            asset.address,
-            params.amount
-          ),
-          slippageBps
-        );
+        requireNonZeroSyncWithdrawBound(params.amount, 'tokensOut');
+        if (quote !== undefined) {
+          if (quote.kind !== 'withdraw' || quote.tokensOut !== params.amount) {
+            throw new InvalidWithdrawParamsError();
+          }
+          minTokenOut = quote.tokensOut;
+          maxUnitsIn = quote.maxUnitsIn;
+        } else {
+          minTokenOut = params.amount;
+          maxUnitsIn = applySlippageUp(
+            await provisionerV2.getSyncWithdrawUnitsIn(
+              publicClient,
+              provisionerAddress,
+              runtime.feeCalculator.address,
+              runtime.feeCalculator.version,
+              vault.vaultAddress,
+              asset.address,
+              params.amount
+            ),
+            slippageBps
+          );
+        }
+        requireNonZeroSyncWithdrawBound(maxUnitsIn, 'maxUnitsIn');
       } else {
         if (shares === undefined) {
           throw new InvalidWithdrawParamsError();
         }
 
-        minTokenOut = applySlippageDown(
-          await provisionerV2.getSyncRedeemTokenOut(
+        requireNonZeroSyncWithdrawBound(shares, 'unitsIn');
+        if (quote !== undefined) {
+          if (quote.kind !== 'redeem' || quote.shares !== shares) {
+            throw new InvalidWithdrawParamsError();
+          }
+          minTokenOut = quote.minTokensOut;
+        } else {
+          const tokensOut = await provisionerV2.getSyncRedeemTokenOut(
             publicClient,
             provisionerAddress,
             runtime.feeCalculator.address,
@@ -373,10 +402,11 @@ export const aeraAdapter: EvmProtocolAdapter = {
             vault.vaultAddress,
             asset.address,
             shares
-          ),
-          slippageBps
-        );
-        maxUnitsIn = applySlippageUp(shares, slippageBps);
+          );
+          minTokenOut = applySlippageDown(tokensOut, slippageBps);
+        }
+        requireNonZeroSyncWithdrawBound(minTokenOut, 'minTokensOut');
+        maxUnitsIn = shares;
       }
     } else {
       if ('entireAmount' in params && params.entireAmount) {

package/src/evm/adapters/types.ts

@@ -1,5 +1,6 @@
 import type { Abi, Address, Hex, PublicClient } from 'viem';
 import type { AeraRuntimeContracts } from '../aeraContracts';
+import type { SyncWithdrawQuoteBounds } from '../withdrawQuote';
 import type { TokenInfo, VaultDeployment } from '../types';
 
 export interface EvmTxStep<TAbi extends Abi = Abi, TFunctionName extends string = string> {
@@ -37,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 = {
@@ -53,6 +56,7 @@ export type AdapterWithdrawParams = {
   /** Maximum price age passed to async Aera provisioner requests. Defaults to 10 days. */
   maxPriceAge?: bigint;
   aeraRuntime?: AeraRuntimeContracts;
+  syncWithdrawQuote?: SyncWithdrawQuoteBounds;
 } & (
   | { shares: bigint; amount?: never; entireAmount?: never }
   | { amount: bigint; shares?: never; entireAmount?: never }

package/src/evm/aeraContracts/priceAndFeeCalculator.ts

@@ -3,6 +3,7 @@ import { UnsupportedFeatureError } from '../../errors';
 import { priceAndFeeCalculatorAbi } from '../abis/priceAndFeeCalculator';
 import { priceAndFeeCalculatorV2Abi } from '../abis/priceAndFeeCalculatorV2';
 import { ContractVersion } from '../types';
+import { readAtBlock } from './readOptions';
 
 const ROUNDING_FLOOR = 0;
 const ROUNDING_CEIL = 1;
@@ -13,6 +14,10 @@ export interface NormalizedVaultPriceState {
   timestamp: number;
 }
 
+type AeraPriceReadOptions = {
+  blockNumber?: bigint;
+};
+
 function toNumber(value: bigint | number): number {
   return typeof value === 'bigint' ? Number(value) : value;
 }
@@ -54,7 +59,8 @@ export async function convertTokenToUnitsIfActive(
   vault: Address,
   token: Address,
   tokenAmount: bigint,
-  rounding: typeof ROUNDING_FLOOR | typeof ROUNDING_CEIL
+  rounding: typeof ROUNDING_FLOOR | typeof ROUNDING_CEIL,
+  options: AeraPriceReadOptions = {}
 ): Promise<bigint> {
   if (feeCalculatorVersion === ContractVersion.V2) {
     return client.readContract({
@@ -62,6 +68,7 @@ export async function convertTokenToUnitsIfActive(
       abi: priceAndFeeCalculatorV2Abi,
       functionName: 'convertTokenToUnitsIfActive',
       args: [vault, token, tokenAmount, rounding],
+      ...readAtBlock(options),
     });
   }
 
@@ -70,6 +77,7 @@ export async function convertTokenToUnitsIfActive(
     abi: priceAndFeeCalculatorAbi,
     functionName: 'convertTokenToUnitsIfActive',
     args: [vault, token, tokenAmount, rounding],
+    ...readAtBlock(options),
   });
 }
 
@@ -80,7 +88,8 @@ export async function convertUnitsToTokenIfActive(
   vault: Address,
   token: Address,
   unitsAmount: bigint,
-  rounding: typeof ROUNDING_FLOOR | typeof ROUNDING_CEIL
+  rounding: typeof ROUNDING_FLOOR | typeof ROUNDING_CEIL,
+  options: AeraPriceReadOptions = {}
 ): Promise<bigint> {
   if (feeCalculatorVersion === ContractVersion.V2) {
     return client.readContract({
@@ -88,6 +97,7 @@ export async function convertUnitsToTokenIfActive(
       abi: priceAndFeeCalculatorV2Abi,
       functionName: 'convertUnitsToTokenIfActive',
       args: [vault, token, unitsAmount, rounding],
+      ...readAtBlock(options),
     });
   }
 
@@ -96,6 +106,7 @@ export async function convertUnitsToTokenIfActive(
     abi: priceAndFeeCalculatorAbi,
     functionName: 'convertUnitsToTokenIfActive',
     args: [vault, token, unitsAmount, rounding],
+    ...readAtBlock(options),
   });
 }
 
@@ -105,7 +116,8 @@ export async function convertTokenToUnits(
   feeCalculatorVersion: ContractVersion,
   vault: Address,
   token: Address,
-  tokenAmount: bigint
+  tokenAmount: bigint,
+  options: AeraPriceReadOptions = {}
 ): Promise<bigint> {
   if (feeCalculatorVersion === ContractVersion.V2) {
     return client.readContract({
@@ -113,6 +125,7 @@ export async function convertTokenToUnits(
       abi: priceAndFeeCalculatorV2Abi,
       functionName: 'convertTokenToUnits',
       args: [vault, token, tokenAmount],
+      ...readAtBlock(options),
     });
   }
 
@@ -121,6 +134,7 @@ export async function convertTokenToUnits(
     abi: priceAndFeeCalculatorAbi,
     functionName: 'convertTokenToUnits',
     args: [vault, token, tokenAmount],
+    ...readAtBlock(options),
   });
 }
 
@@ -130,7 +144,8 @@ export async function convertUnitsToToken(
   feeCalculatorVersion: ContractVersion,
   vault: Address,
   token: Address,
-  unitsAmount: bigint
+  unitsAmount: bigint,
+  options: AeraPriceReadOptions = {}
 ): Promise<bigint> {
   if (feeCalculatorVersion === ContractVersion.V2) {
     return client.readContract({
@@ -138,6 +153,7 @@ export async function convertUnitsToToken(
       abi: priceAndFeeCalculatorV2Abi,
       functionName: 'convertUnitsToToken',
       args: [vault, token, unitsAmount],
+      ...readAtBlock(options),
     });
   }
 
@@ -146,6 +162,55 @@ export async function convertUnitsToToken(
     abi: priceAndFeeCalculatorAbi,
     functionName: 'convertUnitsToToken',
     args: [vault, token, unitsAmount],
+    ...readAtBlock(options),
+  });
+}
+
+export async function convertTokenToNumeraire(
+  client: PublicClient,
+  feeCalculator: Address,
+  feeCalculatorVersion: ContractVersion,
+  vault: Address,
+  token: Address,
+  tokenAmount: bigint,
+  options: AeraPriceReadOptions = {}
+): Promise<bigint> {
+  if (feeCalculatorVersion !== ContractVersion.V2) {
+    throw new UnsupportedFeatureError(
+      'Aera: numeraire conversion requires V2 price and fee calculator'
+    );
+  }
+
+  return client.readContract({
+    address: feeCalculator,
+    abi: priceAndFeeCalculatorV2Abi,
+    functionName: 'convertTokenToNumeraire',
+    args: [vault, token, tokenAmount],
+    ...readAtBlock(options),
+  });
+}
+
+export async function convertNumeraireToToken(
+  client: PublicClient,
+  feeCalculator: Address,
+  feeCalculatorVersion: ContractVersion,
+  vault: Address,
+  token: Address,
+  numeraireAmount: bigint,
+  options: AeraPriceReadOptions = {}
+): Promise<bigint> {
+  if (feeCalculatorVersion !== ContractVersion.V2) {
+    throw new UnsupportedFeatureError(
+      'Aera: numeraire conversion requires V2 price and fee calculator'
+    );
+  }
+
+  return client.readContract({
+    address: feeCalculator,
+    abi: priceAndFeeCalculatorV2Abi,
+    functionName: 'convertNumeraireToToken',
+    args: [vault, token, numeraireAmount],
+    ...readAtBlock(options),
   });
 }
 
@@ -153,7 +218,8 @@ export async function getAnchorTimestamp(
   client: PublicClient,
   feeCalculator: Address,
   feeCalculatorVersion: ContractVersion,
-  vault: Address
+  vault: Address,
+  options: AeraPriceReadOptions = {}
 ): Promise<number> {
   if (feeCalculatorVersion !== ContractVersion.V2) {
     throw new UnsupportedFeatureError('Aera: sync redeem requires V2 price and fee calculator');
@@ -164,6 +230,7 @@ export async function getAnchorTimestamp(
     abi: priceAndFeeCalculatorV2Abi,
     functionName: 'getAnchorTimestamp',
     args: [vault],
+    ...readAtBlock(options),
   });
 }
 

package/src/evm/aeraContracts/readOptions.ts

@@ -0,0 +1,3 @@
+export function readAtBlock(options: { blockNumber?: bigint } = {}) {
+  return options.blockNumber === undefined ? {} : { blockNumber: options.blockNumber };
+}