@gauntlet-xyz/sdk 0.0.1

package/src/evm/userCurrentBalance.ts

@@ -0,0 +1,265 @@
+import { parseAbi, type Address } from 'viem';
+import type { GauntletClient } from '../client';
+import type { EvmVaultDeployment } from './types';
+import { ChainMismatchError, UnsupportedProtocolError, VaultNotFoundError } from '../errors';
+import { getMultiDepositorVault, getPriceAndFeeCalculator } from './aeraContracts';
+
+// Inline as-const ABI items give viem full type inference for args and return types.
+const DEPOSIT_REQUESTED_ABI = [
+  {
+    type: 'event',
+    name: 'DepositRequested',
+    inputs: [
+      { type: 'address', name: 'user', indexed: true },
+      { type: 'address', name: 'token', indexed: true },
+      { type: 'uint256', name: 'tokensIn', indexed: false },
+      { type: 'uint256', name: 'minUnitsOut', indexed: false },
+      { type: 'uint256', name: 'solverTip', indexed: false },
+      { type: 'uint256', name: 'deadline', indexed: false },
+      { type: 'uint256', name: 'maxPriceAge', indexed: false },
+      { type: 'bool', name: 'isFixedPrice', indexed: false },
+      { type: 'bytes32', name: 'depositRequestHash', indexed: false },
+    ],
+  },
+] as const;
+
+const REDEEM_REQUESTED_ABI = [
+  {
+    type: 'event',
+    name: 'RedeemRequested',
+    inputs: [
+      { type: 'address', name: 'user', indexed: true },
+      { type: 'address', name: 'token', indexed: true },
+      { type: 'uint256', name: 'minTokensOut', indexed: false },
+      { type: 'uint256', name: 'unitsIn', indexed: false },
+      { type: 'uint256', name: 'solverTip', indexed: false },
+      { type: 'uint256', name: 'deadline', indexed: false },
+      { type: 'uint256', name: 'maxPriceAge', indexed: false },
+      { type: 'bool', name: 'isFixedPrice', indexed: false },
+      { type: 'bytes32', name: 'redeemRequestHash', indexed: false },
+    ],
+  },
+] as const;
+
+// ABI for provisioner state queries
+const provisionerStateAbi = parseAbi([
+  'function asyncDepositHashes(bytes32 asyncDepositHash) view returns (bool exists)',
+  'function asyncRedeemHashes(bytes32 asyncRedeemHash) view returns (bool exists)',
+]);
+
+export interface UserCurrentBalanceParams {
+  vaultId: string;
+  address: Address;
+  chainId?: number;
+}
+
+export interface UserCurrentBalance {
+  /** Chain identifier, e.g. "base" */
+  chain: string;
+  token: Address;
+  decimals: number;
+  /** Assets queued via async deposit, not yet earning */
+  pendingDeposit: bigint;
+  /** Assets actively earning in the vault */
+  balance: bigint;
+  /** Assets queued via async withdraw, not yet claimable */
+  pendingWithdraw: bigint;
+}
+
+const CHAIN_NAMES: Record<number, string> = {
+  1: 'ethereum',
+  8453: 'base',
+  42161: 'arbitrum',
+  10: 'optimism',
+};
+
+// Approximate 3-day block lookback per chain based on avg block time
+const BLOCKS_3_DAYS: Record<number, bigint> = {
+  1: 21_600n,
+  8453: 129_600n,
+  42161: 1_036_800n,
+  10: 129_600n,
+};
+const DEFAULT_BLOCKS_3_DAYS = 129_600n;
+
+// Many RPC providers cap eth_getLogs to 10,000 blocks per request.
+const LOG_PAGE_SIZE = 9_999n;
+
+async function queryDeploymentBalance(
+  client: GauntletClient,
+  deployment: EvmVaultDeployment,
+  address: Address
+): Promise<UserCurrentBalance> {
+  const publicClient = client.getPublicClient(deployment.chainId);
+  const token = deployment.supplyToken[0];
+  const provisionerAddress = deployment.provisionerAddress!;
+
+  const vaultContract = getMultiDepositorVault(publicClient, deployment.vaultAddress);
+  const [units, feeCalculatorAddress] = await Promise.all([
+    vaultContract.read.balanceOf([address]),
+    vaultContract.read.feeCalculator(),
+  ]);
+
+  const feeCalc = getPriceAndFeeCalculator(publicClient, feeCalculatorAddress);
+  const balance = await feeCalc.read.convertUnitsToToken([
+    deployment.vaultAddress,
+    token.address,
+    units,
+  ]);
+
+  // Look back ~3 days for pending async requests
+  const currentBlock = await publicClient.getBlockNumber();
+  const lookback = BLOCKS_3_DAYS[deployment.chainId] ?? DEFAULT_BLOCKS_3_DAYS;
+  const fromBlock = currentBlock > lookback ? currentBlock - lookback : 0n;
+
+  // Compute block-range chunks to stay within the 10,000-block RPC limit, then fetch in parallel
+  const chunks: [bigint, bigint][] = [];
+  for (let cursor = fromBlock; cursor <= currentBlock; cursor += LOG_PAGE_SIZE + 1n) {
+    const end = cursor + LOG_PAGE_SIZE <= currentBlock ? cursor + LOG_PAGE_SIZE : currentBlock;
+    chunks.push([cursor, end]);
+  }
+
+  const [depositPages, redeemPages] = await Promise.all([
+    Promise.all(
+      chunks.map(([from, to]) =>
+        publicClient.getContractEvents({
+          address: provisionerAddress,
+          abi: DEPOSIT_REQUESTED_ABI,
+          eventName: 'DepositRequested',
+          args: { user: address },
+          fromBlock: from,
+          toBlock: to,
+        })
+      )
+    ),
+    Promise.all(
+      chunks.map(([from, to]) =>
+        publicClient.getContractEvents({
+          address: provisionerAddress,
+          abi: REDEEM_REQUESTED_ABI,
+          eventName: 'RedeemRequested',
+          args: { user: address },
+          fromBlock: from,
+          toBlock: to,
+        })
+      )
+    ),
+  ]);
+
+  const depositLogs = depositPages.flat().filter((log) => log.args.depositRequestHash != null);
+  const redeemLogs = redeemPages.flat().filter((log) => log.args.redeemRequestHash != null);
+
+  // Check which requests are still pending on-chain via a single multicall
+  const pendingChecks = await publicClient.multicall({
+    contracts: [
+      ...depositLogs.map((log) => ({
+        address: provisionerAddress,
+        abi: provisionerStateAbi,
+        functionName: 'asyncDepositHashes' as const,
+        args: [log.args.depositRequestHash!] as const,
+      })),
+      ...redeemLogs.map((log) => ({
+        address: provisionerAddress,
+        abi: provisionerStateAbi,
+        functionName: 'asyncRedeemHashes' as const,
+        args: [log.args.redeemRequestHash!] as const,
+      })),
+    ],
+    allowFailure: false,
+  });
+
+  const depositChecks = pendingChecks.slice(0, depositLogs.length);
+  const redeemChecks = pendingChecks.slice(depositLogs.length);
+
+  let pendingDeposit = 0n;
+  for (let i = 0; i < depositLogs.length; i++) {
+    if (depositChecks[i]) {
+      pendingDeposit += depositLogs[i].args.tokensIn ?? 0n;
+    }
+  }
+
+  let pendingWithdrawUnits = 0n;
+  for (let i = 0; i < redeemLogs.length; i++) {
+    if (redeemChecks[i]) {
+      pendingWithdrawUnits += redeemLogs[i].args.unitsIn ?? 0n;
+    }
+  }
+
+  const pendingWithdraw =
+    pendingWithdrawUnits > 0n
+      ? await feeCalc.read.convertUnitsToToken([
+          deployment.vaultAddress,
+          token.address,
+          pendingWithdrawUnits,
+        ])
+      : 0n;
+
+  return {
+    chain: CHAIN_NAMES[deployment.chainId] ?? `chain-${deployment.chainId}`,
+    token: token.address,
+    decimals: token.decimals,
+    pendingDeposit,
+    balance,
+    pendingWithdraw,
+  };
+}
+
+/**
+ * Returns the current balance breakdown for a user across all EVM deployments of a vault.
+ *
+ * Queries the vault's on-chain state to split the user's position into three buckets:
+ * - `balance` — assets actively earning inside the vault (converted from vault units to tokens).
+ * - `pendingDeposit` — tokens submitted via async deposit but not yet processed by a solver.
+ * - `pendingWithdraw` — vault units locked in a pending async redeem request (converted to tokens).
+ *
+ * Only supported for Aera multi-depositor vaults. Pending amounts are detected by scanning
+ * the last ~3 days of provisioner events and cross-checking hash existence on-chain.
+ *
+ * @param client - A configured `GauntletClient` instance with an EVM public client for each
+ *   chain the vault is deployed on.
+ * @param params - Query parameters including `vaultId`, the user `address`, and an optional
+ *   `chainId` to limit the query to a single deployment.
+ * @returns One `UserCurrentBalance` entry per chain queried.
+ *
+ * @throws {VaultNotFoundError} If the vault ID is not found in the manifest.
+ * @throws {UnsupportedProtocolError} If the vault is not an Aera multi-depositor vault.
+ * @throws {ChainMismatchError} If `chainId` is specified but no deployment exists for that chain.
+ *
+ * @example
+ * ```ts
+ * const balances = await getUserCurrentBalance(client, {
+ *   vaultId: 'baseUsdcPrime',
+ *   address: '0xYourWalletAddress',
+ * });
+ * // [{ chain: 'base', token: '0x...', decimals: 6, balance: 100_000_000n, pendingDeposit: 0n, pendingWithdraw: 0n }]
+ * ```
+ */
+export async function getUserCurrentBalance(
+  client: GauntletClient,
+  params: UserCurrentBalanceParams
+): Promise<UserCurrentBalance[]> {
+  const manifest = await client.manifest;
+  const vaultInfo = manifest.vaults.find((v) => v.vaultId === params.vaultId);
+  if (!vaultInfo) throw new VaultNotFoundError(params.vaultId);
+
+  const evmDeployments = vaultInfo.deployments.filter(
+    (d): d is EvmVaultDeployment => d.chain === 'evm' && d.provisionerAddress !== undefined
+  );
+
+  if (vaultInfo.protocol !== 'aera' || evmDeployments.length === 0) {
+    throw new UnsupportedProtocolError(vaultInfo.protocol);
+  }
+
+  if (params.chainId !== undefined) {
+    const deployment = evmDeployments.find((d) => d.chainId === params.chainId);
+    if (!deployment) {
+      throw new ChainMismatchError(
+        `${params.chainId}`,
+        evmDeployments.map((d) => `${d.chainId}`).join(', ')
+      );
+    }
+    return [await queryDeploymentBalance(client, deployment, params.address)];
+  }
+
+  return Promise.all(evmDeployments.map((d) => queryDeploymentBalance(client, d, params.address)));
+}

package/src/evm/vaults.ts

@@ -0,0 +1,88 @@
+import { base } from 'viem/chains';
+import type { GauntletClient } from '../client';
+import type { EvmVaultDeployment, VaultDeployment, VaultInfo } from './types';
+import { ChainMismatchError } from '../errors';
+
+export enum VaultId {
+  BaseUsdcPrime = 'baseUsdcPrime',
+  EthUsdcPrime = 'ethUsdcPrime',
+  AeraUsdAlpha = 'gtusda',
+  EthUsdcPrimeV2 = 'ethUsdcPrimeV2',
+}
+
+export interface VaultFilter {
+  /** Filter to vaults that have at least one EVM deployment on this chainId. */
+  chainId?: number;
+  protocol?: string;
+}
+
+/**
+ * Returns vaults from the bundled manifest, optionally filtered by chain and/or protocol.
+ * Does not make any network requests.
+ *
+ * @param client - A configured `GauntletClient` instance.
+ * @param filter - Optional filter criteria. `chainId` restricts results to vaults that have
+ *   at least one EVM deployment on that chain. `protocol` restricts results to a specific
+ *   protocol (e.g. `'aera'`, `'morpho'`).
+ * @returns Array of `VaultInfo` objects matching the filter, or all vaults if no filter is given.
+ *
+ * @example
+ * ```ts
+ * // All vaults on Base
+ * const vaults = await getVaults(client, { chainId: base.id });
+ *
+ * // All Aera vaults
+ * const aeraVaults = await getVaults(client, { protocol: 'aera' });
+ * ```
+ */
+export async function getVaults(
+  client: GauntletClient,
+  filter?: VaultFilter
+): Promise<VaultInfo[]> {
+  const manifest = await client.manifest;
+  let vaults = manifest.vaults;
+
+  if (filter?.chainId) {
+    vaults = vaults.filter((v) =>
+      v.deployments.some((d) => d.chain === 'evm' && d.chainId === filter.chainId)
+    );
+  }
+
+  if (filter?.protocol) {
+    vaults = vaults.filter((v) => v.protocol === filter.protocol);
+  }
+
+  return vaults;
+}
+
+export async function resolveVault(
+  client: GauntletClient,
+  vaultId: string,
+  chainId?: string | number
+): Promise<{ vault: VaultDeployment; protocol: string } | undefined> {
+  const manifest = await client.manifest;
+  const vaultInfo = manifest.vaults.find((v) => v.vaultId === vaultId);
+  if (!vaultInfo) return undefined;
+
+  const evmDeployments = vaultInfo.deployments.filter(
+    (d): d is EvmVaultDeployment => d.chain === 'evm'
+  );
+
+  if (evmDeployments.length === 1) {
+    // if user specifies a chain we need to make sure they get it
+    if (chainId !== undefined && evmDeployments[0].chainId !== chainId) {
+      throw new ChainMismatchError(`${chainId}`, `${evmDeployments[0].chainId}`);
+    }
+    // otherwise they're expected to know what chain
+    // the single chain vault they request is on
+    return { vault: evmDeployments[0], protocol: vaultInfo.protocol };
+  }
+
+  // now we default to base
+  const defaultChainId = chainId ?? base.id;
+
+  const deployment = evmDeployments.find((d) => d.chainId === defaultChainId);
+  if (!deployment) return undefined;
+
+  return { vault: deployment, protocol: vaultInfo.protocol };
+}

package/src/evm/withdraw.ts

@@ -0,0 +1,127 @@
+import type { Address } from 'viem';
+import type { GauntletClient } from '../client';
+import type { AdapterWithdrawParams } from './adapters/types';
+import { getAdapter } from './adapters';
+import { encodeTransactionWithAttribution, PreparedTx } from '../attribution';
+import {
+  AccountRequiredError,
+  VaultNotFoundError,
+  UnsupportedAssetError,
+  UnsupportedDepositModeError,
+  InvalidSlippageBPSError,
+} from '../errors';
+import { resolveVault } from './vaults';
+
+export type EvmWithdrawParams = {
+  vaultId: string;
+  // Required for multichain vaults, will default to base
+  chainId?: number;
+  // Required for multiasset vaults, not utilized yet
+  assetSymbol?: string;
+  /** Request async (queued) withdraw. 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;
+} & (
+  | { shares: bigint; amount?: never; entireAmount?: never }
+  | { amount: bigint; shares?: never; entireAmount?: never }
+  | { entireAmount: true; shares?: never; amount?: never }
+);
+
+/**
+ * Builds the ordered list of EVM transactions required to withdraw from a Gauntlet vault.
+ *
+ * Specify the withdrawal amount as one of: `shares` (vault units), `amount` (underlying
+ * token amount), or `entireAmount: true` (full balance). Returns an ERC-20 approval
+ * (only when needed for async redeem) followed by the withdraw or async redeem request,
+ * each returned as a `PreparedTx` ready to be signed and sent.
+ *
+ * @param client - A configured `GauntletClient` instance with an EVM public client and wallet.
+ * @param params - Withdrawal parameters including the vault identifier and exactly one of
+ *   `shares`, `amount`, or `entireAmount`, plus optional chain, asset symbol, deposit mode,
+ *   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 withdrawal mode is not supported.
+ * @throws {UnsupportedAssetError} If the specified asset symbol is not accepted by the vault.
+ *
+ * @example
+ * ```ts
+ * // Withdraw by token amount
+ * const txs = await getWithdrawTx(client, {
+ *   vaultId: 'baseUsdcPrime',
+ *   amount: 50_000_000n, // 50 USDC (6 decimals)
+ * });
+ *
+ * // Withdraw entire balance
+ * const txs = await getWithdrawTx(client, {
+ *   vaultId: 'baseUsdcPrime',
+ *   entireAmount: true,
+ * });
+ * ```
+ */
+export async function getWithdrawTx(
+  client: GauntletClient,
+  params: EvmWithdrawParams
+): 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 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 adapter = getAdapter(protocol);
+  const publicClient = client.getPublicClient(chainId);
+
+  const withdrawParams = {
+    vault,
+    receiver: params.receiver ?? account,
+    account,
+    async: modifiedDepositMode === 'async',
+    asset: token,
+    publicClient,
+    slippageBps: params.slippageBps,
+    ...('shares' in params && params.shares != null ? { shares: params.shares } : {}),
+    ...('amount' in params && params.amount != null ? { amount: params.amount } : {}),
+    ...('entireAmount' in params && params.entireAmount ? { entireAmount: true as const } : {}),
+  };
+
+  const steps = await adapter.buildWithdraw(withdrawParams as AdapterWithdrawParams);
+
+  return await Promise.all(steps.map((step) => encodeTransactionWithAttribution(client, step)));
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+export { GauntletClient, AttributionMode } from './client';
+export type { GauntletClientConfig } from './client';
+
+export type {
+  VaultInfo,
+  VaultDeployment,
+  EvmVaultDeployment,
+  TokenInfo,
+  VaultManifest,
+} from './evm/types';
+export type { VaultFilter } from './evm/vaults';
+
+export { getUserCurrentBalance } from './evm/userCurrentBalance';
+export type { UserCurrentBalanceParams, UserCurrentBalance } from './evm/userCurrentBalance';
+
+export {
+  GauntletSDKError,
+  VaultNotFoundError,
+  UnsupportedAssetError,
+  ChainMismatchError,
+  UnsupportedDepositModeError,
+  RpcNotConfiguredError,
+  AccountRequiredError,
+  UnsupportedProtocolError,
+  InvalidWithdrawParamsError,
+  UnimplementedFeatureError,
+  UnitConversionError,
+} from './errors';