@gauntlet-xyz/sdk 2.3.0 → 3.0.1

package/src/evm/aeraContracts/v2.ts

@@ -4,17 +4,21 @@ 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';
 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,19 +37,71 @@ export function getPriceAndFeeCalculator<T extends Client>(
   });
 }
 
-function getProvisioner<T extends Client>(client: T, address: Address) {
-  return getContract({
-    address,
+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,
+  options: SyncRedeemReadOptions = {}
+) {
+  return client.readContract({
+    address: provisioner,
     abi: provisionerV2Abi,
-    client,
+    functionName: 'tokensDetails',
+    args: [token],
+    ...readAtBlock(options),
   });
 }
 
-async function getTokenDetails(client: PublicClient, provisioner: Address, token: Address) {
-  return getProvisioner(client, provisioner).read.tokensDetails([token]);
+/**
+ * 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 getDepositUnitsOut({
+async function getDepositQuote({
   client,
   provisioner,
   feeCalculator,
@@ -54,6 +110,7 @@ async function getDepositUnitsOut({
   token,
   tokensIn,
   multiplierIndex,
+  options,
 }: {
   client: PublicClient;
   provisioner: Address;
@@ -63,20 +120,24 @@ async function getDepositUnitsOut({
   token: Address;
   tokensIn: bigint;
   multiplierIndex: 4 | 6;
-}): Promise<bigint> {
-  const tokenDetails = await getTokenDetails(client, provisioner, token);
-  const multiplier = BigInt(tokenDetails[multiplierIndex]);
-  const adjustedTokensIn = (tokensIn * multiplier) / MAX_BPS;
+  options?: SyncRedeemReadOptions;
+}): Promise<{ unitsOut: bigint; multiplierBps: bigint }> {
+  const tokenDetails = await getTokenDetails(client, provisioner, token, options);
+  const multiplierBps = BigInt(tokenDetails[multiplierIndex]);
+  const adjustedTokensIn = (tokensIn * multiplierBps) / MAX_BPS;
 
-  return convertTokenToUnitsIfActive(
+  const unitsOut = await convertTokenToUnitsIfActive(
     client,
     feeCalculator,
     feeCalculatorVersion,
     vault,
     token,
     adjustedTokensIn,
-    Rounding.Floor
+    Rounding.Floor,
+    options
   );
+
+  return { unitsOut, multiplierBps };
 }
 
 async function getRedeemTokenOut({
@@ -88,6 +149,7 @@ async function getRedeemTokenOut({
   token,
   unitsIn,
   multiplierIndex,
+  options,
 }: {
   client: PublicClient;
   provisioner: Address;
@@ -97,9 +159,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 +170,8 @@ async function getRedeemTokenOut({
       vault,
       token,
       unitsIn,
-      Rounding.Floor
+      Rounding.Floor,
+      options
     ),
   ]);
   const multiplier = BigInt(tokenDetails[multiplierIndex]);
@@ -124,6 +188,7 @@ async function getWithdrawUnitsIn({
   token,
   tokensOut,
   multiplierIndex,
+  options,
 }: {
   client: PublicClient;
   provisioner: Address;
@@ -133,8 +198,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 +211,39 @@ 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 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 getSyncRedeemRateContext(
   client: PublicClient,
   provisioner: Address,
   vault: Address,
   token: Address,
-  feeCalculator: Address
-): Promise<bigint> {
+  feeCalculator: Address,
+  options: SyncRedeemReadOptions = {}
+): Promise<{ rate: SyncRedeemRate; hasPullFundsSubmitData: boolean }> {
+  const readContext = await resolveReadContext(client, options);
   const [tokenDetails, syncRedeemDetails, anchorTimestamp] = await client.multicall({
     contracts: [
       {
@@ -177,12 +265,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 +286,39 @@ async function getSyncRedeemMultiplier(
       ? 0n
       : ((blockTimestamp - priceTimestamp) * maxDynamicPremiumBps + maxPriceAge - 1n) / maxPriceAge;
 
-  return syncRedeemMultiplier - dynamicPremiumBps;
+  return {
+    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,
+  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 +328,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 +342,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;
@@ -235,7 +362,7 @@ export async function getAsyncDepositUnitsOut(
   token: Address,
   tokensIn: bigint
 ): Promise<bigint> {
-  return getDepositUnitsOut({
+  const quote = await getDepositQuote({
     client,
     provisioner,
     feeCalculator,
@@ -245,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,
@@ -255,8 +383,8 @@ export async function getSyncDepositUnitsOut(
   vault: Address,
   token: Address,
   tokensIn: bigint
-): Promise<bigint> {
-  return getDepositUnitsOut({
+) =>
+  getDepositQuote({
     client,
     provisioner,
     feeCalculator,
@@ -266,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(
@@ -317,15 +505,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 +523,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 {