@gauntlet-xyz/sdk 2.3.0 → 2.5.0

package/src/evm/aeraContracts/v2.ts

@@ -13,8 +13,9 @@ import {
   convertUnitsToTokenIfActive,
 } from './priceAndFeeCalculator';
 import { MAX_BPS } from '../../constants';
-import { StalePriceError } from '../../errors';
+import { StalePriceError, UnsupportedFeatureError } from '../../errors';
 import type { ContractVersion } from '../types';
+import { readAtBlock } from './readOptions';
 
 export type PriceAndFeeCalculatorContract<T extends Client> = GetContractReturnType<
   typeof priceAndFeeCalculatorV2Abi,
@@ -33,16 +34,44 @@ export function getPriceAndFeeCalculator<T extends Client>(
   });
 }
 
-function getProvisioner<T extends Client>(client: T, address: Address) {
-  return getContract({
-    address,
-    abi: provisionerV2Abi,
-    client,
-  });
+type SyncRedeemReadOptions = {
+  blockNumber?: bigint;
+  blockTimestamp?: bigint;
+};
+
+async function resolveReadContext(
+  client: PublicClient,
+  options: SyncRedeemReadOptions = {}
+): Promise<Required<SyncRedeemReadOptions>> {
+  if (options.blockNumber !== undefined && options.blockTimestamp !== undefined) {
+    return { blockNumber: options.blockNumber, blockTimestamp: options.blockTimestamp };
+  }
+
+  const block =
+    options.blockNumber === undefined ? await client.getBlock() : await client.getBlock(options);
+  if (block.number === null) {
+    throw new UnsupportedFeatureError('Aera: sync redeem reads require a numbered block');
+  }
+
+  return {
+    blockNumber: options.blockNumber ?? block.number,
+    blockTimestamp: options.blockTimestamp ?? BigInt(block.timestamp),
+  };
 }
 
-async function getTokenDetails(client: PublicClient, provisioner: Address, token: Address) {
-  return getProvisioner(client, provisioner).read.tokensDetails([token]);
+async function getTokenDetails(
+  client: PublicClient,
+  provisioner: Address,
+  token: Address,
+  options: SyncRedeemReadOptions = {}
+) {
+  return client.readContract({
+    address: provisioner,
+    abi: provisionerV2Abi,
+    functionName: 'tokensDetails',
+    args: [token],
+    ...readAtBlock(options),
+  });
 }
 
 async function getDepositUnitsOut({
@@ -54,6 +83,7 @@ async function getDepositUnitsOut({
   token,
   tokensIn,
   multiplierIndex,
+  options,
 }: {
   client: PublicClient;
   provisioner: Address;
@@ -63,8 +93,9 @@ async function getDepositUnitsOut({
   token: Address;
   tokensIn: bigint;
   multiplierIndex: 4 | 6;
+  options?: SyncRedeemReadOptions;
 }): Promise<bigint> {
-  const tokenDetails = await getTokenDetails(client, provisioner, token);
+  const tokenDetails = await getTokenDetails(client, provisioner, token, options);
   const multiplier = BigInt(tokenDetails[multiplierIndex]);
   const adjustedTokensIn = (tokensIn * multiplier) / MAX_BPS;
 
@@ -75,7 +106,8 @@ async function getDepositUnitsOut({
     vault,
     token,
     adjustedTokensIn,
-    Rounding.Floor
+    Rounding.Floor,
+    options
   );
 }
 
@@ -88,6 +120,7 @@ async function getRedeemTokenOut({
   token,
   unitsIn,
   multiplierIndex,
+  options,
 }: {
   client: PublicClient;
   provisioner: Address;
@@ -97,9 +130,10 @@ async function getRedeemTokenOut({
   token: Address;
   unitsIn: bigint;
   multiplierIndex: 5 | 7;
+  options?: SyncRedeemReadOptions;
 }): Promise<bigint> {
   const [tokenDetails, tokensOut] = await Promise.all([
-    getTokenDetails(client, provisioner, token),
+    getTokenDetails(client, provisioner, token, options),
     convertUnitsToTokenIfActive(
       client,
       feeCalculator,
@@ -107,7 +141,8 @@ async function getRedeemTokenOut({
       vault,
       token,
       unitsIn,
-      Rounding.Floor
+      Rounding.Floor,
+      options
     ),
   ]);
   const multiplier = BigInt(tokenDetails[multiplierIndex]);
@@ -124,6 +159,7 @@ async function getWithdrawUnitsIn({
   token,
   tokensOut,
   multiplierIndex,
+  options,
 }: {
   client: PublicClient;
   provisioner: Address;
@@ -133,8 +169,9 @@ async function getWithdrawUnitsIn({
   token: Address;
   tokensOut: bigint;
   multiplierIndex: 5 | 7;
+  options?: SyncRedeemReadOptions;
 }): Promise<bigint> {
-  const tokenDetails = await getTokenDetails(client, provisioner, token);
+  const tokenDetails = await getTokenDetails(client, provisioner, token, options);
   const multiplier = BigInt(tokenDetails[multiplierIndex]);
   const preMultiplierTokens = (tokensOut * MAX_BPS + multiplier - 1n) / multiplier;
 
@@ -145,17 +182,37 @@ async function getWithdrawUnitsIn({
     vault,
     token,
     preMultiplierTokens,
-    Rounding.Ceil
+    Rounding.Ceil,
+    options
   );
 }
 
-async function getSyncRedeemMultiplier(
+/** Breakdown of the effective sync redeem multiplier, in basis points. */
+export interface SyncRedeemRate {
+  /** Base sync redeem multiplier (tokensDetails.syncRedeemMultiplier). */
+  baseMultiplierBps: bigint;
+  /** Dynamic premium charged for the current oracle price age. */
+  dynamicPremiumBps: bigint;
+  /** Multiplier actually applied to size the redemption (base - dynamic premium). */
+  effectiveMultiplierBps: bigint;
+}
+
+/**
+ * Reads the live sync redeem rate, replicating the provisioner's effective-multiplier
+ * derivation (base multiplier minus a price-age-proportional dynamic premium).
+ *
+ * @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(
   client: PublicClient,
   provisioner: Address,
   vault: Address,
   token: Address,
-  feeCalculator: Address
-): Promise<bigint> {
+  feeCalculator: Address,
+  options: SyncRedeemReadOptions = {}
+): Promise<SyncRedeemRate> {
+  const readContext = await resolveReadContext(client, options);
   const [tokenDetails, syncRedeemDetails, anchorTimestamp] = await client.multicall({
     contracts: [
       {
@@ -177,12 +234,12 @@ async function getSyncRedeemMultiplier(
       },
     ],
     allowFailure: false,
+    blockNumber: readContext.blockNumber,
   });
-  const block = await client.getBlock();
-  const syncRedeemMultiplier = BigInt(tokenDetails[7]);
+  const baseMultiplierBps = BigInt(tokenDetails[7]);
   const maxPriceAge = BigInt(syncRedeemDetails[0]);
   const maxDynamicPremiumBps = BigInt(syncRedeemDetails[2]);
-  const blockTimestamp = BigInt(block.timestamp);
+  const blockTimestamp = readContext.blockTimestamp;
   const priceTimestamp = BigInt(anchorTimestamp);
 
   if (priceTimestamp + maxPriceAge < blockTimestamp) {
@@ -198,7 +255,23 @@ async function getSyncRedeemMultiplier(
       ? 0n
       : ((blockTimestamp - priceTimestamp) * maxDynamicPremiumBps + maxPriceAge - 1n) / maxPriceAge;
 
-  return syncRedeemMultiplier - dynamicPremiumBps;
+  return {
+    baseMultiplierBps,
+    dynamicPremiumBps,
+    effectiveMultiplierBps: baseMultiplierBps - dynamicPremiumBps,
+  };
+}
+
+async function getSyncRedeemMultiplier(
+  client: PublicClient,
+  provisioner: Address,
+  vault: Address,
+  token: Address,
+  feeCalculator: Address,
+  options: SyncRedeemReadOptions = {}
+): Promise<bigint> {
+  return (await getSyncRedeemRate(client, provisioner, vault, token, feeCalculator, options))
+    .effectiveMultiplierBps;
 }
 
 export async function getSyncRedeemTokenOut(
@@ -208,8 +281,12 @@ export async function getSyncRedeemTokenOut(
   feeCalculatorVersion: ContractVersion,
   vault: Address,
   token: Address,
-  unitsIn: bigint
+  unitsIn: bigint,
+  effectiveMultiplierBps?: bigint,
+  options: SyncRedeemReadOptions = {}
 ): Promise<bigint> {
+  const readContext =
+    effectiveMultiplierBps === undefined ? await resolveReadContext(client, options) : options;
   const [tokenAmount, multiplier] = await Promise.all([
     convertUnitsToTokenIfActive(
       client,
@@ -218,9 +295,12 @@ export async function getSyncRedeemTokenOut(
       vault,
       token,
       unitsIn,
-      Rounding.Floor
+      Rounding.Floor,
+      readContext
     ),
-    getSyncRedeemMultiplier(client, provisioner, vault, token, feeCalculator),
+    effectiveMultiplierBps !== undefined
+      ? Promise.resolve(effectiveMultiplierBps)
+      : getSyncRedeemMultiplier(client, provisioner, vault, token, feeCalculator, readContext),
   ]);
 
   return (tokenAmount * multiplier) / MAX_BPS;
@@ -317,15 +397,15 @@ export async function getSyncWithdrawUnitsIn(
   feeCalculatorVersion: ContractVersion,
   vault: Address,
   token: Address,
-  tokensOut: bigint
+  tokensOut: bigint,
+  effectiveMultiplierBps?: bigint,
+  options: SyncRedeemReadOptions = {}
 ): Promise<bigint> {
-  const multiplier = await getSyncRedeemMultiplier(
-    client,
-    provisioner,
-    vault,
-    token,
-    feeCalculator
-  );
+  const readContext =
+    effectiveMultiplierBps === undefined ? await resolveReadContext(client, options) : options;
+  const multiplier =
+    effectiveMultiplierBps ??
+    (await getSyncRedeemMultiplier(client, provisioner, vault, token, feeCalculator, readContext));
   const prePremiumTokens = (tokensOut * MAX_BPS + multiplier - 1n) / multiplier;
 
   return convertTokenToUnitsIfActive(
@@ -335,10 +415,54 @@ export async function getSyncWithdrawUnitsIn(
     vault,
     token,
     prePremiumTokens,
-    Rounding.Ceil
+    Rounding.Ceil,
+    readContext
   );
 }
 
+/** Current sync redeem epoch accounting, in numeraire (all values uint256). */
+export interface SyncRedeemEpochState {
+  epochTimestamp: bigint;
+  epochStartTvlNumeraire: bigint;
+  epochRedeemedNumeraire: bigint;
+  epochCapNumeraire: bigint;
+}
+
+export async function getSyncRedeemEpochState(
+  client: PublicClient,
+  provisioner: Address,
+  options: SyncRedeemReadOptions = {}
+): Promise<SyncRedeemEpochState> {
+  const [epochTimestamp, epochStartTvlNumeraire, epochRedeemedNumeraire, epochCapNumeraire] =
+    await client.readContract({
+      address: provisioner,
+      abi: provisionerV2Abi,
+      functionName: 'getSyncRedeemEpochState',
+      ...readAtBlock(options),
+    });
+
+  return { epochTimestamp, epochStartTvlNumeraire, epochRedeemedNumeraire, epochCapNumeraire };
+}
+
+/**
+ * Raw expiry timestamp for the user's latest sync-deposit lock (0 if none was recorded).
+ * The user is locked while this value is greater than or equal to the relevant block timestamp.
+ */
+export async function getUserUnitsRefundableUntil(
+  client: PublicClient,
+  provisioner: Address,
+  user: Address,
+  options: SyncRedeemReadOptions = {}
+): Promise<bigint> {
+  return client.readContract({
+    address: provisioner,
+    abi: provisionerV2Abi,
+    functionName: 'userUnitsRefundableUntil',
+    args: [user],
+    ...readAtBlock(options),
+  });
+}
+
 export function depositTxRequest(
   provisioner: Address,
   token: Address,

package/src/evm/aeraContracts.ts

@@ -15,6 +15,7 @@ import { provisionerAbi } from './abis/provisioner';
 import { provisionerV2Abi } from './abis/provisionerV2';
 import { MAX_BPS } from '../constants';
 import { ContractVersion, type EvmVaultDeployment } from './types';
+import { readAtBlock } from './aeraContracts/readOptions';
 
 const contractVersionCache = new Map<string, ContractVersion>();
 
@@ -28,6 +29,19 @@ const contractVersionAbi = [
   },
 ] as const;
 
+const solvingGateAbi = [
+  {
+    type: 'function',
+    inputs: [
+      { name: 'provisioner', internalType: 'address', type: 'address' },
+      { name: 'token', internalType: 'address', type: 'address' },
+    ],
+    name: 'paused',
+    outputs: [{ name: '', internalType: 'bool', type: 'bool' }],
+    stateMutability: 'view',
+  },
+] as const;
+
 export interface AeraRuntimeContracts {
   provisioner: {
     address: Address;
@@ -46,6 +60,19 @@ export interface AeraTokenModeSupport {
   syncRedeem: boolean;
 }
 
+export function requireAeraSyncRedeemRuntime(runtime: AeraRuntimeContracts): void {
+  if (runtime.provisioner.version !== ContractVersion.V2) {
+    throw new UnsupportedFeatureError('Aera: sync redeem requires a V2 provisioner');
+  }
+  if (runtime.feeCalculator.version !== ContractVersion.V2) {
+    throw new UnsupportedFeatureError('Aera: sync redeem requires a V2 price and fee calculator');
+  }
+}
+
+export type AeraReadOptions = {
+  blockNumber?: bigint;
+};
+
 export function applySlippageDown(amount: bigint, slippageBps: number): bigint {
   return (amount * (MAX_BPS - BigInt(slippageBps))) / MAX_BPS;
 }
@@ -97,7 +124,8 @@ export function getMultiDepositorVault<T extends Client>(
 
 export async function resolveContractVersion(
   client: PublicClient,
-  address: Address
+  address: Address,
+  options: AeraReadOptions = {}
 ): Promise<ContractVersion> {
   const cacheKey = contractVersionCacheKey(client, address);
   const cached = contractVersionCache.get(cacheKey);
@@ -108,6 +136,7 @@ export async function resolveContractVersion(
       address,
       abi: contractVersionAbi,
       functionName: 'version',
+      ...readAtBlock(options),
     });
     const version = versionString.startsWith('2.') ? ContractVersion.V2 : ContractVersion.V1;
     contractVersionCache.set(cacheKey, version);
@@ -123,7 +152,8 @@ export async function resolveContractVersion(
 
 export async function resolveAeraRuntimeContracts(
   client: PublicClient,
-  vault: EvmVaultDeployment
+  vault: EvmVaultDeployment,
+  options: AeraReadOptions = {}
 ): Promise<AeraRuntimeContracts> {
   if (vault.vaultType !== 'multi-depositor') {
     throw new UnimplementedFeatureError('Aera: single depositor vaults');
@@ -134,11 +164,13 @@ export async function resolveAeraRuntimeContracts(
       address: vault.vaultAddress,
       abi: multiDepositorVaultAbi,
       functionName: 'provisioner',
+      ...readAtBlock(options),
     }),
     client.readContract({
       address: vault.vaultAddress,
       abi: multiDepositorVaultAbi,
       functionName: 'feeCalculator',
+      ...readAtBlock(options),
     }),
   ]);
 
@@ -150,8 +182,8 @@ export async function resolveAeraRuntimeContracts(
   }
 
   const [provisionerVersion, feeCalculatorVersion] = await Promise.all([
-    resolveContractVersion(client, provisionerAddress),
-    resolveContractVersion(client, feeCalculatorAddress),
+    resolveContractVersion(client, provisionerAddress, options),
+    resolveContractVersion(client, feeCalculatorAddress, options),
   ]);
 
   return {
@@ -169,21 +201,61 @@ export async function resolveAeraRuntimeContracts(
 export async function resolveAeraTokenModeSupport(
   client: PublicClient,
   runtime: AeraRuntimeContracts,
-  token: Address
+  token: Address,
+  options: AeraReadOptions & { includeSyncModes?: boolean } = {}
 ): Promise<AeraTokenModeSupport> {
   if (runtime.provisioner.version === ContractVersion.V2) {
-    const tokenDetails = await client.readContract({
+    const tokenDetailsPromise = client.readContract({
       address: runtime.provisioner.address,
       abi: provisionerV2Abi,
       functionName: 'tokensDetails',
       args: [token],
+      ...readAtBlock(options),
     });
+    if (options.includeSyncModes === false) {
+      const tokenDetails = await tokenDetailsPromise;
+      return {
+        asyncDeposit: Boolean(tokenDetails[0]),
+        asyncRedeem: Boolean(tokenDetails[1]),
+        syncDeposit: false,
+        syncRedeem: false,
+      };
+    }
+
+    const [tokenDetails, solvingGateEnabled, solvingGate] = await Promise.all([
+      tokenDetailsPromise,
+      client.readContract({
+        address: runtime.provisioner.address,
+        abi: provisionerV2Abi,
+        functionName: 'SOLVING_GATE_ENABLED',
+        ...readAtBlock(options),
+      }),
+      client.readContract({
+        address: runtime.provisioner.address,
+        abi: provisionerV2Abi,
+        functionName: 'solvingGate',
+        ...readAtBlock(options),
+      }),
+    ]);
+    const solvingPaused =
+      solvingGateEnabled && solvingGate !== zeroAddress
+        ? await client.readContract({
+            address: solvingGate,
+            abi: solvingGateAbi,
+            functionName: 'paused',
+            args: [runtime.provisioner.address, token],
+            ...readAtBlock(options),
+          })
+        : false;
 
     return {
       asyncDeposit: Boolean(tokenDetails[0]),
       asyncRedeem: Boolean(tokenDetails[1]),
-      syncDeposit: Boolean(tokenDetails[2]),
-      syncRedeem: Boolean(tokenDetails[3]),
+      syncDeposit: Boolean(tokenDetails[2]) && !solvingPaused,
+      syncRedeem:
+        Boolean(tokenDetails[3]) &&
+        !solvingPaused &&
+        runtime.feeCalculator.version === ContractVersion.V2,
     };
   }
 
@@ -192,6 +264,7 @@ export async function resolveAeraTokenModeSupport(
     abi: provisionerAbi,
     functionName: 'tokensDetails',
     args: [token],
+    ...readAtBlock(options),
   });
 
   return {

package/src/evm/deposit.ts

@@ -113,7 +113,8 @@ export async function getDepositTx(
     const tokenModeSupport = await resolveAeraTokenModeSupport(
       publicClient,
       aeraRuntime,
-      token.address
+      token.address,
+      { includeSyncModes: requestedDepositMode !== 'async' }
     );
     modifiedDepositMode = resolveOperationMode(params.vaultId, requestedDepositMode, {
       async: tokenModeSupport.asyncDeposit,

package/src/evm/index.ts

@@ -1,10 +1,30 @@
 export { getDepositTx } from './deposit';
 export { getDepositReceiverApprovalTx } from './depositReceiverApproval';
 export { getWithdrawTx } from './withdraw';
+export { getSyncWithdrawQuote } from './withdrawQuote';
+export { getAeraTokenModeSupport } from './tokenModes';
 export { getUserCurrentBalance } from './userCurrentBalance';
 export { getVaults, VaultId } from './vaults';
 export { ContractVersion } from './types';
 export { resolveAeraRuntimeContracts, resolveContractVersion } from './aeraContracts';
+export {
+  GauntletSDKError,
+  AccountRequiredError,
+  AccountMismatchError,
+  ChainMismatchError,
+  InvalidSlippageBPSError,
+  InvalidSolverTipError,
+  InvalidSyncWithdrawBoundError,
+  InvalidWithdrawParamsError,
+  RpcNotConfiguredError,
+  StalePriceError,
+  UnsupportedAssetError,
+  UnsupportedDepositModeError,
+  UnsupportedFeatureError,
+  UnsupportedProtocolError,
+  UnimplementedFeatureError,
+  VaultNotFoundError,
+} from '../errors';
 export {
   Rounding,
   convertTokenToUnits,
@@ -19,7 +39,18 @@ export {
 export type { EvmDepositParams } from './deposit';
 export type { EvmDepositReceiverApprovalParams } from './depositReceiverApproval';
 export type { EvmWithdrawParams } from './withdraw';
+export type {
+  SyncWithdrawQuote,
+  SyncWithdrawQuoteParams,
+  SyncWithdrawCapacity,
+  SyncWithdrawQuoteContext,
+  SyncWithdrawQuoteRequest,
+  SyncWithdrawQuoteBounds,
+} from './withdrawQuote';
+export type { AeraTokenModeSupportParams } from './tokenModes';
+export type { SyncRedeemRate } from './aeraContracts/v2';
 export type { EvmTxStep } from './adapters/types';
+export type { PreparedTx } from '../attribution';
 export type {
   VaultInfo,
   VaultDeployment,
@@ -31,3 +62,4 @@ export type { VaultFilter } from './vaults';
 export type { UserCurrentBalanceParams, UserCurrentBalance } from './userCurrentBalance';
 export type { AeraRuntimeContracts, AeraTokenModeSupport } from './aeraContracts';
 export type { NormalizedVaultPriceState } from './aeraContracts/priceAndFeeCalculator';
+export type { SyncWithdrawBound } from '../errors';

package/src/evm/tokenModes.ts

@@ -0,0 +1,54 @@
+import type { GauntletClient } from '../client';
+import { UnsupportedAssetError, UnsupportedFeatureError, VaultNotFoundError } from '../errors';
+import { resolveVault } from './vaults';
+import {
+  resolveAeraRuntimeContracts,
+  resolveAeraTokenModeSupport,
+  type AeraTokenModeSupport,
+} from './aeraContracts';
+
+export interface AeraTokenModeSupportParams {
+  vaultId: string;
+  /** EVM chain ID. Defaults to the vault's primary chain (Base for current multichain vaults). */
+  chainId?: number;
+  /** Required for multiasset vaults. */
+  assetSymbol?: string;
+}
+
+/**
+ * Reads which deposit/redeem modes (sync vs async) are currently enabled on-chain for a vault token.
+ *
+ * Use this to decide which entry points to offer a user (e.g. whether an instant withdraw is
+ * available) before any amount is entered. Mode availability includes the provisioner's token
+ * settings and live runtime gates. A paused V2 solving gate disables both sync modes.
+ *
+ * @throws {VaultNotFoundError} If the vault ID is not found.
+ * @throws {UnsupportedFeatureError} If the vault is not an Aera deployment.
+ * @throws {UnsupportedAssetError} If the asset symbol is not accepted by the vault.
+ */
+export async function getAeraTokenModeSupport(
+  client: GauntletClient,
+  params: AeraTokenModeSupportParams
+): Promise<AeraTokenModeSupport> {
+  const resolved = await resolveVault(client, params.vaultId, params.chainId);
+  if (!resolved) throw new VaultNotFoundError(params.vaultId);
+
+  const { vault, protocol } = resolved;
+  if (protocol !== 'aera') {
+    throw new UnsupportedFeatureError('Token mode support is only available for Aera vaults');
+  }
+
+  const chainId = params.chainId ?? vault.chainId;
+  const publicClient = client.getPublicClient(chainId);
+
+  const token =
+    vault.supplyToken.length > 1
+      ? vault.supplyToken.find((tInfo) => tInfo.symbol === params.assetSymbol)
+      : vault.supplyToken[0];
+  if (token === undefined) {
+    throw new UnsupportedAssetError(params.assetSymbol ?? 'unknown', params.vaultId);
+  }
+
+  const runtime = await resolveAeraRuntimeContracts(publicClient, vault);
+  return resolveAeraTokenModeSupport(publicClient, runtime, token.address);
+}