@gauntlet-xyz/sdk 0.0.1

package/src/evm/adapters/aera.ts

@@ -0,0 +1,254 @@
+import { erc20Abi } from '../abis/erc20';
+import {
+  requestDepositTxRequest,
+  requestRedeemTxRequest,
+  getMultiDepositorVault,
+  getPriceAndFeeCalculator,
+} from '../aeraContracts';
+import {
+  InvalidWithdrawParamsError,
+  UnimplementedFeatureError,
+  UnitConversionError,
+  UnsupportedFeatureError,
+} from '../../errors';
+import type {
+  EvmProtocolAdapter,
+  EvmTxStep,
+  AdapterDepositParams,
+  AdapterWithdrawParams,
+  AllowanceParams,
+  ApprovalParams,
+} from './types';
+import { PublicClient, type Address } from 'viem';
+import { multiDepositorVaultAbi } from '../abis/multiDepositorVault';
+
+const SECOND = 1;
+const MINUTE = SECOND * 60;
+const HOUR = MINUTE * 60;
+const DAY = HOUR * 24;
+
+export const getAeraV3VaultUnits = async (
+  publicClient: PublicClient,
+  tokenUnits: bigint,
+  vaultAddress: Address,
+  tokenAddress: Address
+) => {
+  const vaultContract = getMultiDepositorVault(publicClient, vaultAddress);
+
+  if (vaultContract === undefined) return;
+
+  const calculatorAddress = await vaultContract.read.feeCalculator();
+
+  if (!calculatorAddress) return;
+
+  const calculatorContract = getPriceAndFeeCalculator(publicClient, calculatorAddress);
+
+  const vaultUnits = await calculatorContract.read.convertTokenToUnits([
+    vaultAddress,
+    tokenAddress,
+    tokenUnits,
+  ]);
+
+  return vaultUnits;
+};
+
+export const getAeraV3TokenUnits = async (
+  publicClient: PublicClient,
+  vaultUnits: bigint,
+  vaultAddress: Address,
+  tokenAddress: Address
+) => {
+  const vaultContract = getMultiDepositorVault(publicClient, vaultAddress);
+  if (vaultContract === undefined) return;
+
+  const calculatorAddress = await vaultContract.read.feeCalculator();
+  if (!calculatorAddress) return;
+
+  const calculatorContract = getPriceAndFeeCalculator(publicClient, calculatorAddress);
+
+  return calculatorContract.read.convertUnitsToToken([vaultAddress, tokenAddress, vaultUnits]);
+};
+
+export const aeraAdapter: EvmProtocolAdapter = {
+  async buildDeposit(params: AdapterDepositParams): Promise<EvmTxStep[]> {
+    const { vault, receiver, amount, account, publicClient, asset, async: isAsync, slippageBps = 100 } = params;
+
+    if (receiver !== account) {
+      throw new UnsupportedFeatureError('Aera: separate receiver address');
+    }
+
+    if (!vault.provisionerAddress) {
+      // Not implemented because untested and clients won't need in V1
+      throw new UnimplementedFeatureError('Aera: single depositor vaults');
+      // single-depositor vault
+      /*return [
+        {
+          type: 'deposit',
+          // SDK only supports single asset deposit
+          ...depositTxRequest(vault.vaultAddress, [{ asset: asset.address, amount }], account),
+        },
+      ];*/
+    }
+
+    if (isAsync) {
+      const vaultUnits = await getAeraV3VaultUnits(
+        publicClient,
+        amount,
+        vault.vaultAddress,
+        asset.address
+      );
+
+      if (vaultUnits === undefined) {
+        throw new UnitConversionError(vault.vaultAddress);
+      }
+
+      const deadline = BigInt(Math.ceil(new Date().getTime() / 1000) + DAY * 3);
+      // Request deposit
+      return [
+        {
+          type: 'requestDeposit',
+          ...requestDepositTxRequest(
+            vault.provisionerAddress,
+            asset.address,
+            amount,
+            (vaultUnits * BigInt(10000 - slippageBps)) / 10000n, // minUnitsOut
+            0n, // solvertip
+            deadline,
+            BigInt(DAY * 10),
+            false,
+            account
+          ),
+        },
+      ];
+    }
+
+    throw new UnimplementedFeatureError('Aera Sync Operations');
+  },
+
+  async buildWithdraw(params: AdapterWithdrawParams): Promise<EvmTxStep[]> {
+    const { vault, receiver, account, asset, publicClient, async: isAsync, slippageBps = 100 } = params;
+
+    if (receiver !== account) {
+      throw new UnsupportedFeatureError('Aera: separate receiver address');
+    }
+
+    let shares: bigint;
+    let amount: bigint | undefined;
+
+    if ('entireAmount' in params && params.entireAmount) {
+      shares = await publicClient.readContract({
+        address: vault.vaultAddress,
+        abi: multiDepositorVaultAbi,
+        functionName: 'balanceOf',
+        args: [account],
+      });
+      amount = await getAeraV3TokenUnits(publicClient, shares, vault.vaultAddress, asset.address);
+    } else if ('amount' in params && params.amount != null) {
+      const tempShares = await getAeraV3VaultUnits(
+        publicClient,
+        params.amount,
+        vault.vaultAddress,
+        asset.address
+      );
+      amount = params.amount;
+      if (tempShares === undefined) {
+        throw new UnitConversionError(vault.vaultAddress);
+      }
+      shares = tempShares;
+    } else if ('shares' in params && params.shares != null) {
+      shares = params.shares;
+      amount = await getAeraV3TokenUnits(publicClient, shares, vault.vaultAddress, asset.address);
+    } else {
+      throw new InvalidWithdrawParamsError();
+    }
+
+    if (!vault.provisionerAddress) {
+      // Not implemented because untested and clients won't need in V1
+      throw new UnimplementedFeatureError('Aera: single depositor vaults');
+      //single-depositer vault
+      // TODO shares or amount ??
+      /*return [
+        {
+          type: 'withdraw',
+          // SDK only supports single asset deposit
+          ...withdrawTxRequest(
+            vault.vaultAddress,
+            [{ asset: asset.address, amount: shares }],
+            account
+          ),
+        },
+      ];*/
+    }
+
+    const { sufficient } = await this.checkAllowance({
+      publicClient,
+      token: vault.vaultAddress,
+      owner: account,
+      spender: vault.provisionerAddress,
+      amount: shares,
+    });
+
+    const steps: EvmTxStep[] = [];
+
+    if (!sufficient) {
+      steps.push(
+        this.buildApproval({
+          token: vault.vaultAddress,
+          spender: vault.provisionerAddress,
+          amount: shares,
+          account,
+        })
+      );
+    }
+
+    if (isAsync) {
+      // Request redeem
+      const deadline = BigInt(Math.ceil(new Date().getTime() / 1000) + DAY * 3);
+      if (amount === undefined) {
+        throw new UnitConversionError(vault.vaultAddress);
+      }
+      return [
+        ...steps,
+        {
+          type: 'requestRedeem',
+          ...requestRedeemTxRequest(
+            vault.provisionerAddress,
+            asset.address,
+            shares,
+            (amount * BigInt(10000 - slippageBps)) / 10000n, // minUnitsOut
+            0n, // solvertip
+            deadline,
+            BigInt(DAY * 10),
+            false,
+            account
+          ),
+        },
+      ];
+    }
+
+    throw new UnimplementedFeatureError('Aera Sync Operations');
+  },
+
+  async checkAllowance(params: AllowanceParams) {
+    const { publicClient, token, owner, spender, amount } = params;
+    const current = await publicClient.readContract({
+      address: token,
+      abi: erc20Abi,
+      functionName: 'allowance',
+      args: [owner, spender],
+    });
+
+    return { sufficient: current >= amount, current };
+  },
+
+  buildApproval(params: ApprovalParams): EvmTxStep {
+    return {
+      type: 'approve',
+      address: params.token,
+      abi: erc20Abi,
+      functionName: 'approve',
+      args: [params.spender, params.amount],
+      account: params.account,
+    };
+  },
+};

package/src/evm/adapters/index.ts

@@ -0,0 +1,15 @@
+import { aeraAdapter } from './aera';
+import { morphoAdapter } from './morpho';
+import { UnsupportedProtocolError } from '../../errors';
+import type { EvmProtocolAdapter } from './types';
+
+export function getAdapter(protocol: string): EvmProtocolAdapter {
+  switch (protocol) {
+    case 'aera':
+      return aeraAdapter;
+    case 'morpho':
+      return morphoAdapter;
+    default:
+      throw new UnsupportedProtocolError(protocol);
+  }
+}

package/src/evm/adapters/morpho.ts

@@ -0,0 +1,92 @@
+import type {
+  EvmProtocolAdapter,
+  EvmTxStep,
+  AdapterDepositParams,
+  AdapterWithdrawParams,
+  AllowanceParams,
+  ApprovalParams,
+} from './types';
+import { erc20Abi } from '../abis/erc20';
+import { erc4626Abi } from '../abis/erc4626';
+import { InvalidWithdrawParamsError } from '../../errors';
+
+export const morphoAdapter: EvmProtocolAdapter = {
+  async buildDeposit(params: AdapterDepositParams): Promise<EvmTxStep[]> {
+    const { vault, amount, receiver, account } = params;
+
+    return [
+      {
+        type: 'deposit',
+        address: vault.vaultAddress,
+        abi: erc4626Abi,
+        functionName: 'deposit',
+        args: [amount, receiver],
+        account,
+      },
+    ];
+  },
+
+  async buildWithdraw(params: AdapterWithdrawParams): Promise<EvmTxStep[]> {
+    const { vault, receiver, account, publicClient } = params;
+
+    let shares: bigint;
+
+    if ('entireAmount' in params && params.entireAmount) {
+      shares = await publicClient.readContract({
+        address: vault.vaultAddress,
+        abi: erc4626Abi,
+        functionName: 'balanceOf',
+        args: [account],
+      });
+    } else if ('amount' in params && params.amount != null) {
+      return [
+        {
+          type: 'withdraw',
+          address: vault.vaultAddress,
+          abi: erc4626Abi,
+          functionName: 'withdraw',
+          args: [params.amount, receiver, account],
+          account,
+        },
+      ];
+    } else if ('shares' in params && params.shares != null) {
+      shares = params.shares;
+    } else {
+      throw new InvalidWithdrawParamsError();
+    }
+
+    return [
+      {
+        type: 'redeem',
+        address: vault.vaultAddress,
+        abi: erc4626Abi,
+        functionName: 'redeem',
+        args: [shares, receiver, account],
+        account,
+      },
+    ];
+  },
+
+  async checkAllowance(params: AllowanceParams) {
+    const { publicClient, token, owner, spender, amount } = params;
+    const current = await publicClient.readContract({
+      address: token,
+      abi: erc20Abi,
+      functionName: 'allowance',
+      args: [owner, spender],
+    });
+
+    return { sufficient: current >= amount, current };
+  },
+
+  buildApproval(params: ApprovalParams): EvmTxStep {
+    return {
+      type: 'approve',
+      address: params.token,
+      abi: erc20Abi,
+      functionName: 'approve',
+      args: [params.spender, params.amount],
+      account: params.account,
+    };
+  },
+};

package/src/evm/adapters/types.ts

@@ -0,0 +1,64 @@
+import type { Abi, Address, Hex, PublicClient } from 'viem';
+import type { TokenInfo, VaultDeployment } from '../types';
+
+export interface EvmTxStep<TAbi extends Abi = Abi, TFunctionName extends string = string> {
+  type: 'approve' | 'deposit' | 'requestDeposit' | 'redeem' | 'requestRedeem' | 'withdraw';
+  address: Address;
+  abi: TAbi;
+  functionName: TFunctionName;
+  args: readonly unknown[];
+  account: Address;
+  attribution?: Hex;
+}
+
+export type TxStep = EvmTxStep; // | SolanaTxStep
+
+export interface AdapterDepositParams {
+  vault: VaultDeployment;
+  amount: bigint;
+  receiver: Address;
+  account: Address;
+  async: boolean;
+  /** Attribution bytes (GTLT + optional ERC-8021). Passed to adapter for future calldata embedding. */
+  asset: TokenInfo;
+  publicClient: PublicClient;
+  /** Slippage tolerance in basis points (e.g. 100 = 1%). Defaults to 100. */
+  slippageBps?: number;
+}
+
+export type AdapterWithdrawParams = {
+  vault: VaultDeployment;
+  receiver: Address;
+  account: Address;
+  async: boolean | undefined;
+  asset: TokenInfo;
+  publicClient: PublicClient;
+  /** Slippage tolerance in basis points (e.g. 100 = 1%). Defaults to 100. */
+  slippageBps?: number;
+} & (
+  | { shares: bigint; amount?: never; entireAmount?: never }
+  | { amount: bigint; shares?: never; entireAmount?: never }
+  | { entireAmount: true; shares?: never; amount?: never }
+);
+
+export interface AllowanceParams {
+  publicClient: PublicClient;
+  token: Address;
+  owner: Address;
+  spender: Address;
+  amount: bigint;
+}
+
+export interface ApprovalParams {
+  token: Address;
+  spender: Address;
+  amount: bigint;
+  account: Address;
+}
+
+export interface EvmProtocolAdapter {
+  buildDeposit(params: AdapterDepositParams): Promise<EvmTxStep[]>;
+  buildWithdraw(params: AdapterWithdrawParams): Promise<EvmTxStep[]>;
+  checkAllowance(params: AllowanceParams): Promise<{ sufficient: boolean; current: bigint }>;
+  buildApproval(params: ApprovalParams): EvmTxStep;
+}

package/src/evm/aeraContracts.ts

@@ -0,0 +1,82 @@
+/**
+ *  CODE PULLED FROM AERA-V3-TS-SDK in gauntlet/apps/packages/aera-v3-ts-sdk
+ *  pulled in here with the goal to have this SDK replace the previous
+ */
+import { type Address, type Client, type GetContractReturnType, getContract } from 'viem';
+import { multiDepositorVaultAbi } from './abis/multiDepositorVault';
+import { priceAndFeeCalculatorAbi } from './abis/priceAndFeeCalculator';
+import { provisionerAbi } from './abis/provisioner';
+
+export type MultiDepositorVaultContract<T extends Client> = GetContractReturnType<
+  typeof multiDepositorVaultAbi,
+  T,
+  Address
+>;
+
+export function getMultiDepositorVault<T extends Client>(
+  client: T,
+  vaultAddress: Address
+): MultiDepositorVaultContract<T> {
+  return getContract({
+    address: vaultAddress,
+    abi: multiDepositorVaultAbi,
+    client,
+  });
+}
+
+export type PriceAndFeeCalculatorContract<T extends Client> = GetContractReturnType<
+  typeof priceAndFeeCalculatorAbi,
+  T,
+  Address
+>;
+
+export function getPriceAndFeeCalculator<T extends Client>(
+  client: T,
+  address: Address
+): PriceAndFeeCalculatorContract<T> {
+  return getContract({
+    address,
+    abi: priceAndFeeCalculatorAbi,
+    client,
+  });
+}
+
+export function requestDepositTxRequest(
+  provisioner: Address,
+  token: Address,
+  tokensIn: bigint,
+  minUnitsOut: bigint,
+  solverTip: bigint,
+  deadline: bigint,
+  maxPriceAge: bigint,
+  isFixedPrice: boolean,
+  account: Address
+) {
+  return {
+    address: provisioner,
+    abi: provisionerAbi,
+    functionName: 'requestDeposit' as const,
+    args: [token, tokensIn, minUnitsOut, solverTip, deadline, maxPriceAge, isFixedPrice] as const,
+    account,
+  };
+}
+
+export function requestRedeemTxRequest(
+  provisioner: Address,
+  token: Address,
+  unitsIn: bigint,
+  minTokenOut: bigint,
+  solverTip: bigint,
+  deadline: bigint,
+  maxPriceAge: bigint,
+  isFixedPrice: boolean,
+  account: Address
+) {
+  return {
+    address: provisioner,
+    abi: provisionerAbi,
+    functionName: 'requestRedeem' as const,
+    args: [token, unitsIn, minTokenOut, solverTip, deadline, maxPriceAge, isFixedPrice] as const,
+    account,
+  };
+}

package/src/evm/deposit.ts

@@ -0,0 +1,137 @@
+import type { Address } from 'viem';
+import type { GauntletClient } from '../client';
+import type { EvmTxStep } from './adapters/types';
+import { getAdapter } from './adapters';
+import { encodeTransactionWithAttribution, PreparedTx } from '../attribution';
+import {
+  AccountRequiredError,
+  VaultNotFoundError,
+  UnsupportedDepositModeError,
+  UnsupportedAssetError,
+  InvalidSlippageBPSError,
+} from '../errors';
+import { resolveVault } from './vaults';
+
+export interface EvmDepositParams {
+  vaultId: string;
+  amount: bigint;
+  // Required for multichain vaults, will default to base
+  chainId?: number;
+  // Required for multiasset vaults, not utilized yet
+  assetSymbol?: string;
+  /** Request async (queued) deposit. Only valid for vaults with depositMode 'async' or 'both'. */
+  depositMode?: string;
+  // So a developer is able to specify a separate receiver than the tx sender
+  receiver?: Address;
+  /** Slippage tolerance in basis points (e.g. 100 = 1%). Defaults to 100. */
+  slippageBps?: number;
+}
+
+/**
+ * Builds the ordered list of EVM transactions required to deposit into a Gauntlet vault.
+ *
+ * Returns one or two transactions: an ERC-20 approval (only if the current allowance is
+ * insufficient) followed by the deposit or async deposit request. Each transaction is
+ * returned as a `PreparedTx` object ready to be signed and sent.
+ *
+ * @param client - A configured `GauntletClient` instance with an EVM public client and wallet.
+ * @param params - Deposit parameters including the vault identifier, token amount, and optional
+ *   chain, asset symbol, deposit mode (`'sync'` | `'async'`), and receiver address.
+ * @returns Ordered array of prepared transactions to execute in sequence.
+ *
+ * @throws {VaultNotFoundError} If the vault ID is not found in the manifest.
+ * @throws {AccountRequiredError} If no wallet account is set on the client.
+ * @throws {UnsupportedDepositModeError} If the requested deposit mode is not supported by the vault.
+ * @throws {UnsupportedAssetError} If the specified asset symbol is not accepted by the vault.
+ *
+ * @example
+ * ```ts
+ * const txs = await getDepositTx(client, {
+ *   vaultId: 'baseUsdcPrime',
+ *   amount: 100_000_000n, // 100 USDC (6 decimals)
+ * });
+ * for (const tx of txs) {
+ *   await walletClient.sendTransaction(tx.tx);
+ * }
+ * ```
+ */
+export async function getDepositTx(
+  client: GauntletClient,
+  params: EvmDepositParams
+): Promise<PreparedTx[]> {
+  if (
+    params.slippageBps !== undefined &&
+    (!Number.isInteger(params.slippageBps) || params.slippageBps < 0 || params.slippageBps > 10000)
+  ) {
+    throw new InvalidSlippageBPSError(params.slippageBps);
+  }
+
+  const resolved = await resolveVault(client, params.vaultId, params.chainId);
+  if (!resolved) throw new VaultNotFoundError(params.vaultId);
+
+  const chainId = params.chainId ?? resolved.vault.chainId;
+
+  const account = client.wallet?.account?.address;
+  if (!account) throw new AccountRequiredError();
+
+  const { vault, protocol } = resolved;
+
+  if (params.depositMode === 'sync' && vault.depositMode === 'async') {
+    throw new UnsupportedDepositModeError(params.vaultId, 'sync', vault.depositMode);
+  }
+  if (params.depositMode === 'async' && vault.depositMode === 'sync') {
+    throw new UnsupportedDepositModeError(params.vaultId, 'async', vault.depositMode);
+  }
+  let modifiedDepositMode = params.depositMode;
+  if (params.depositMode === undefined) {
+    modifiedDepositMode = vault.depositMode === 'both' ? 'async' : vault.depositMode;
+  }
+
+  const spender = vault.provisionerAddress ?? vault.vaultAddress;
+  const adapter = getAdapter(protocol);
+  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);
+  }
+
+  // NOTE: this could be moved to the buildDeposit level
+  const { sufficient } = await adapter.checkAllowance({
+    publicClient,
+    token: token.address,
+    owner: account,
+    spender,
+    amount: params.amount,
+  });
+
+  const steps: EvmTxStep[] = [];
+
+  if (!sufficient) {
+    steps.push(
+      adapter.buildApproval({
+        token: token.address,
+        spender,
+        amount: params.amount,
+        account,
+      })
+    );
+  }
+
+  const depositSteps = await adapter.buildDeposit({
+    vault,
+    amount: params.amount,
+    receiver: params.receiver ?? account,
+    account,
+    async: modifiedDepositMode === 'async',
+    asset: token,
+    publicClient,
+    slippageBps: params.slippageBps,
+  });
+  steps.push(...depositSteps);
+
+  return await Promise.all(steps.map((step) => encodeTransactionWithAttribution(client, step)));
+}

package/src/evm/index.ts

@@ -0,0 +1,11 @@
+export { getDepositTx } from './deposit';
+export { getWithdrawTx } from './withdraw';
+export { getUserCurrentBalance } from './userCurrentBalance';
+export { getVaults, VaultId } from './vaults';
+
+export type { EvmDepositParams } from './deposit';
+export type { EvmWithdrawParams } from './withdraw';
+export type { EvmTxStep } from './adapters/types';
+export type { VaultInfo, VaultDeployment, TokenInfo, VaultManifest } from './types';
+export type { VaultFilter } from './vaults';
+export type { UserCurrentBalanceParams, UserCurrentBalance } from './userCurrentBalance';

package/src/evm/types.ts

@@ -0,0 +1,34 @@
+import type { Address } from 'viem';
+
+export interface TokenInfo {
+  symbol: string;
+  address: Address;
+  decimals: number;
+}
+
+export interface EvmVaultDeployment {
+  chain: 'evm';
+  chainId: number;
+  vaultAddress: Address;
+  /** Present for Aera multi-depositor vaults; absent for single-depositor and Morpho */
+  provisionerAddress?: Address;
+  vaultType: 'single-depositor' | 'multi-depositor';
+  depositMode: 'sync' | 'async' | 'both';
+  supplyToken: TokenInfo[];
+}
+
+/** Union of all supported chain deployment types. Narrow on `chain` to access chain-specific fields. */
+export type VaultDeployment = EvmVaultDeployment;
+
+export interface VaultInfo {
+  vaultId: string;
+  name: string;
+  protocol: 'aera' | 'morpho';
+  strategy: string;
+  deployments: VaultDeployment[];
+}
+
+export interface VaultManifest {
+  version: string;
+  vaults: VaultInfo[];
+}