@gauntlet-xyz/sdk 2.0.0 → 2.5.0

package/src/api/http.ts

@@ -0,0 +1,62 @@
+import { GauntletApiError } from './errors';
+
+export const DEFAULT_API_URL = 'https://api.gauntlet.xyz';
+
+export interface GauntletApiConfig {
+  /** Kong consumer key sent as `x-api-key`. Anonymous access is rate-limited. */
+  apiKey?: string;
+  /**
+   * Override the API origin. Defaults to `https://api.gauntlet.xyz`. In a
+   * browser this may be a relative path (e.g. a Next.js rewrite like
+   * `/gauntlet-api`), which resolves against the page origin.
+   */
+  apiUrl?: string;
+  /** Custom fetch implementation (testing, instrumentation). Defaults to global fetch. */
+  fetch?: typeof fetch;
+}
+
+export type QueryParams = Record<string, string | number | boolean | undefined>;
+
+export async function apiGet<T>(
+  config: GauntletApiConfig,
+  path: string,
+  query?: QueryParams
+): Promise<T> {
+  // Concatenate instead of `new URL(path, base)`: the paths are absolute, so
+  // URL resolution would silently drop any path prefix on a proxy apiUrl.
+  const base = (config.apiUrl ?? DEFAULT_API_URL).replace(/\/+$/, '');
+  // Relative bases resolve against the browser origin.
+  const origin = (globalThis as { location?: { origin: string } }).location?.origin;
+  if (origin === undefined && !/^[a-z][a-z0-9+.-]*:\/\//i.test(base)) {
+    throw new Error(
+      `relative apiUrl "${base}" requires a browser origin; pass an absolute apiUrl outside the browser`
+    );
+  }
+  const url = new URL(base + path, origin);
+  for (const [key, value] of Object.entries(query ?? {})) {
+    if (value !== undefined) url.searchParams.set(key, String(value));
+  }
+
+  const fetchImpl = config.fetch ?? fetch;
+  const response = await fetchImpl(url, {
+    headers: {
+      accept: 'application/json',
+      ...(config.apiKey ? { 'x-api-key': config.apiKey } : {}),
+    },
+  });
+
+  if (!response.ok) {
+    let message = response.statusText || 'request failed';
+    let code: string | undefined;
+    try {
+      const body = (await response.json()) as { error?: { code?: string; message?: string } };
+      message = body.error?.message ?? message;
+      code = body.error?.code;
+    } catch {
+      // non-JSON error body — keep the status text
+    }
+    throw new GauntletApiError({ status: response.status, path, message, code });
+  }
+
+  return (await response.json()) as T;
+}

package/src/api/index.ts

@@ -0,0 +1,70 @@
+export { GauntletApi } from './client';
+export type {
+  ActivityOptions,
+  AmountPair,
+  ChainSyncStatus,
+  FeaturedVault,
+  FeaturedVaultsResponse,
+  HealthResponse,
+  LatestPriceOptions,
+  LatestPriceResponse,
+  PageOptions,
+  PartialResponseError,
+  PositionsOptions,
+  PositionTimeseriesPoint,
+  PriceTimeseriesOptions,
+  PriceTimeseriesResponse,
+  StrategyCard,
+  StrategyListResponse,
+  TimeseriesMeta,
+  TimeWindowOptions,
+  TokenRef,
+  TvlResponse,
+  UserActivity,
+  UserActivityResponse,
+  UserAllPositionsResponse,
+  UserPosition,
+  UserPositionLatestResponse,
+  UserPositionsTimeseriesResponse,
+  VaultDetail,
+  VaultDetailResponse,
+  VaultMetrics,
+  VaultTimeseriesPoint,
+  VaultTimeseriesResponse,
+} from './client';
+
+export { DEFAULT_API_URL } from './http';
+export type { GauntletApiConfig } from './http';
+
+export { bigIntToDecimal, decimalToBigInt, SHARE_DECIMALS, sharesToBigInt } from './decimal';
+
+export {
+  apiVaultIdFromVaultId,
+  formatApiVaultId,
+  parseApiVaultId,
+  vaultIdFromApiVaultId,
+} from './caip';
+export type { ApiVaultId } from './caip';
+
+export { getActivityFlows, stitchActivityFlows, waitForRequestSettlement } from './activity';
+export type {
+  ActivityFlow,
+  ActivityFlowKind,
+  ActivityFlowsOptions,
+  ActivityFlowStatus,
+  AssetAmount,
+  WaitForSettlementOptions,
+} from './activity';
+
+export { buildPositionHistory, getPositionHistory } from './positionHistory';
+export type { PositionHistory, PositionHistoryPoint } from './positionHistory';
+
+export {
+  DecimalPrecisionError,
+  GauntletApiError,
+  InvalidCaipIdError,
+  InvalidDecimalError,
+  SettlementTimeoutError,
+} from './errors';
+
+export type { components as GaiaApiComponents, paths as GaiaApiPaths } from './generated';

package/src/api/positionHistory.ts

@@ -0,0 +1,167 @@
+import { GauntletSDKError } from '../errors';
+import type { GauntletApi, TokenRef, UserActivity } from './client';
+import { bigIntToDecimal, decimalToBigInt, sharesToBigInt } from './decimal';
+
+/**
+ * Internal accounting scale for asset amounts. The API emits human-unit
+ * decimal strings with at most `token.decimals` fractional digits, so 18
+ * digits is exact for every supported asset; a token with more than 18
+ * decimals would throw `DecimalPrecisionError` rather than lose precision.
+ */
+const ASSET_SCALE = 18;
+
+/** The wallet's reconstructed position state immediately after one activity row. */
+export interface PositionHistoryPoint {
+  timestamp: Date;
+  txHash: string;
+  type: UserActivity['type'];
+  /** Signed share movement of this row, 18-decimal base units. */
+  sharesDelta: bigint;
+  /** Signed asset movement of this row (deposit-ledger convention), human decimal string. */
+  assetsDelta: string;
+  /** Shares held by the wallet after this row (escrowed redeem shares excluded). */
+  sharesBalance: bigint;
+  /** Assets escrowed at the Provisioner awaiting share mint, human decimal string. */
+  pendingDepositAssets: string;
+  /** Shares escrowed at the Provisioner awaiting asset return, 18-decimal base units. */
+  pendingRedeemShares: bigint;
+  /** Cumulative settled deposits minus settled withdrawals, human decimal string. */
+  netAssetsIn: string;
+}
+
+export interface PositionHistory {
+  /** CAIP-10 vault id the history belongs to. */
+  vaultId: string;
+  /** The vault's asset token, when the indexer reports it on any row. */
+  token: TokenRef | null;
+  /** Chronological (oldest-first) position states, one per activity row. */
+  points: PositionHistoryPoint[];
+}
+
+/**
+ * Pure builder: replays a single vault's activity rows (any order) into a
+ * chronological position timeline — running share balance, escrowed pending
+ * amounts, and cumulative net asset flows.
+ *
+ * Async lifecycles are paired via `request_hash` so settled deposits count
+ * the requested asset amount and terminal rows release the matching escrow.
+ */
+export function buildPositionHistory(rows: UserActivity[]): PositionHistory {
+  if (rows.length === 0) {
+    throw new GauntletSDKError('Cannot build position history from zero activity rows');
+  }
+  const vaultIds = new Set(rows.map((r) => r.vault_id));
+  if (vaultIds.size > 1) {
+    throw new GauntletSDKError(
+      `Position history requires rows from a single vault; got ${[...vaultIds].join(', ')}`
+    );
+  }
+
+  const ordered = [...rows].sort((a, b) => a.block_timestamp - b.block_timestamp);
+  const token = ordered.find((r) => r.assets_delta.token)?.assets_delta.token ?? null;
+
+  let sharesBalance = 0n;
+  let pendingDepositAssets = 0n;
+  let pendingRedeemShares = 0n;
+  let netAssetsIn = 0n;
+  const pendingDepositByHash = new Map<string, bigint>();
+  const pendingRedeemByHash = new Map<string, bigint>();
+
+  const points: PositionHistoryPoint[] = [];
+  for (const row of ordered) {
+    const sharesDelta = sharesToBigInt(row.shares_delta);
+    const assetsDelta = decimalToBigInt(row.assets_delta.native, ASSET_SCALE);
+    sharesBalance += sharesDelta;
+
+    switch (row.type) {
+      case 'deposit':
+        if (row.request_hash != null) {
+          // Async terminal solve: assets moved at request time; release escrow.
+          const requested = pendingDepositByHash.get(row.request_hash);
+          if (requested === undefined) {
+            throw new GauntletSDKError(
+              `Deposit settlement ${row.tx_hash} references request_hash "${row.request_hash}" with no matching deposit_pending row`
+            );
+          }
+          pendingDepositByHash.delete(row.request_hash);
+          pendingDepositAssets -= requested;
+          netAssetsIn += requested;
+        } else {
+          netAssetsIn += assetsDelta;
+        }
+        break;
+      case 'deposit_pending':
+        pendingDepositAssets += assetsDelta;
+        if (row.request_hash != null) pendingDepositByHash.set(row.request_hash, assetsDelta);
+        break;
+      case 'deposit_refunded':
+        // Row carries the unwound request as a negative delta.
+        pendingDepositAssets += assetsDelta;
+        if (row.request_hash != null) pendingDepositByHash.delete(row.request_hash);
+        break;
+      case 'withdraw':
+        // Sync withdraws and async terminal solves both carry the asset
+        // payout as a negative delta on this row.
+        netAssetsIn += assetsDelta;
+        if (row.request_hash != null) {
+          const escrowed = pendingRedeemByHash.get(row.request_hash);
+          if (escrowed === undefined) {
+            throw new GauntletSDKError(
+              `Withdraw settlement ${row.tx_hash} references request_hash "${row.request_hash}" with no matching withdraw_pending row`
+            );
+          }
+          pendingRedeemByHash.delete(row.request_hash);
+          pendingRedeemShares -= escrowed;
+        }
+        break;
+      case 'withdraw_pending': {
+        const escrowed = -sharesDelta;
+        pendingRedeemShares += escrowed;
+        if (row.request_hash != null) pendingRedeemByHash.set(row.request_hash, escrowed);
+        break;
+      }
+      case 'withdraw_refunded':
+        pendingRedeemShares -= sharesDelta;
+        if (row.request_hash != null) pendingRedeemByHash.delete(row.request_hash);
+        break;
+      case 'transfer_in':
+      case 'transfer_out':
+        break;
+      default:
+        throw new GauntletSDKError(`Unknown activity row type "${row.type}"`);
+    }
+
+    points.push({
+      timestamp: new Date(row.block_timestamp * 1000),
+      txHash: row.tx_hash,
+      type: row.type,
+      sharesDelta,
+      assetsDelta: row.assets_delta.native,
+      sharesBalance,
+      pendingDepositAssets: bigIntToDecimal(pendingDepositAssets, ASSET_SCALE),
+      pendingRedeemShares,
+      netAssetsIn: bigIntToDecimal(netAssetsIn, ASSET_SCALE),
+    });
+  }
+
+  return { vaultId: ordered[0].vault_id, token, points };
+}
+
+/**
+ * Fetches a wallet's complete activity for one vault and replays it into a
+ * position timeline. `vaultId` is the CAIP-10 id; use `apiVaultIdFromVaultId`
+ * to convert a manifest vault id. A wallet that has never touched the vault
+ * gets an empty timeline, not an error.
+ */
+export async function getPositionHistory(
+  api: GauntletApi,
+  walletAddress: string,
+  vaultId: string
+): Promise<PositionHistory> {
+  const rows: UserActivity[] = [];
+  for await (const row of api.activityRows(walletAddress, { vaultId, order: 'asc', limit: 1000 })) {
+    rows.push(row);
+  }
+  if (rows.length === 0) return { vaultId, token: null, points: [] };
+  return buildPositionHistory(rows);
+}

package/src/client.ts

@@ -1,5 +1,6 @@
 import { type PublicClient, type WalletClient } from 'viem';
 import bundledManifest from '../manifest/vaults.json';
+import { GauntletApi } from './api/client';
 import { RpcNotConfiguredError, UnimplementedFeatureError } from './errors';
 import type { VaultManifest } from './evm/types';
 import { base } from 'viem/chains';
@@ -20,7 +21,10 @@ export enum AttributionMode {
 export type ChainId = string | number;
 
 export interface GauntletClientConfig {
+  /** Gaia API key, sent as `x-api-key` on `client.api` requests. Anonymous access is rate-limited. */
   apiKey?: string;
+  /** Override the Gaia API origin (e.g. a same-origin proxy route). Defaults to `https://api.gauntlet.xyz`. */
+  apiUrl?: string;
   /** Map of chainId → PublicClient, e.g. { [base.id]: createPublicClient(...) } */
   evmClients?: Record<ChainId, PublicClient>;
   attributionMode?: AttributionMode;
@@ -56,12 +60,13 @@ export interface GauntletClientConfig {
  * ```
  */
 export class GauntletClient {
-  // used for future core api and encoding attribution
   readonly apiKey?: string;
   readonly builderCode?: string;
   readonly attributionMode: AttributionMode;
   readonly evmClients: Record<ChainId, PublicClient>;
   readonly wallet?: WalletClient;
+  /** Typed client for the Gaia REST API (vaults, positions, activity, tvl, prices). */
+  readonly api: GauntletApi;
 
   private _manifest: VaultManifest = bundledManifest as VaultManifest;
 
@@ -71,6 +76,7 @@ export class GauntletClient {
     this.attributionMode = config.attributionMode ?? AttributionMode.PUBLIC;
     this.builderCode = config.builderCode;
     this.wallet = config.wallet;
+    this.api = new GauntletApi({ apiKey: config.apiKey, apiUrl: config.apiUrl });
   }
 
   get manifest(): Promise<VaultManifest> {

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;
 

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' }],
@@ -199,4 +232,63 @@ export const provisionerV2Abi = [
     name: 'Redeemed',
     anonymous: false,
   },
+  { type: 'error', inputs: [], name: 'Aera__AsyncDepositDisabled' },
+  { type: 'error', inputs: [], name: 'Aera__AsyncRedeemDisabled' },
+  { type: 'error', inputs: [], name: 'Aera__AutoPriceSolveNotAllowed' },
+  { type: 'error', inputs: [], name: 'Aera__CallerIsNotRequestUser' },
+  { type: 'error', inputs: [], name: 'Aera__CallerIsVault' },
+  { type: 'error', inputs: [], name: 'Aera__CancellationFeeExceedsRequestAmount' },
+  { type: 'error', inputs: [], name: 'Aera__DeadlineInFutureAndUnauthorized' },
+  { type: 'error', inputs: [], name: 'Aera__DeadlineInPast' },
+  { type: 'error', inputs: [], name: 'Aera__DeadlineTooFarInFuture' },
+  { type: 'error', inputs: [], name: 'Aera__DepositCancellationDetailsNotZero' },
+  { type: 'error', inputs: [], name: 'Aera__DepositCapExceeded' },
+  { type: 'error', inputs: [], name: 'Aera__DepositCapZero' },
+  { type: 'error', inputs: [], name: 'Aera__DepositHashNotFound' },
+  { type: 'error', inputs: [], name: 'Aera__DepositRequestCancellationDisabled' },
+  { type: 'error', inputs: [], name: 'Aera__FixedPriceSolverTipNotAllowed' },
+  { type: 'error', inputs: [], name: 'Aera__HashCollision' },
+  { type: 'error', inputs: [], name: 'Aera__HashNotFound' },
+  { type: 'error', inputs: [], name: 'Aera__InvalidToken' },
+  { type: 'error', inputs: [], name: 'Aera__MaxDepositRefundTimeoutExceeded' },
+  { type: 'error', inputs: [], name: 'Aera__MaxTokensInExceeded' },
+  { type: 'error', inputs: [], name: 'Aera__MaxUnitsInExceeded' },
+  { type: 'error', inputs: [], name: 'Aera__MinTokensOutNotMet' },
+  { type: 'error', inputs: [], name: 'Aera__MinUnitsOutNotMet' },
+  { type: 'error', inputs: [], name: 'Aera__MultiplierOutOfRange' },
+  { type: 'error', inputs: [], name: 'Aera__PriceAndFeeCalculatorVaultPaused' },
+  { type: 'error', inputs: [], name: 'Aera__PullFundsSubmitDataNotSet' },
+  { type: 'error', inputs: [], name: 'Aera__ReceiverNotApproved' },
+  { type: 'error', inputs: [], name: 'Aera__RedeemCancellationCapNumeraireZero' },
+  { type: 'error', inputs: [], name: 'Aera__RedeemCancellationDetailsNotZero' },
+  { type: 'error', inputs: [], name: 'Aera__RedeemRequestCancellationDisabled' },
+  { type: 'error', inputs: [], name: 'Aera__RefundPeriodExpired' },
+  { type: 'error', inputs: [], name: 'Aera__RequestAmountExceedsRefundCap' },
+  { type: 'error', inputs: [], name: 'Aera__SolvingGateDisabled' },
+  { type: 'error', inputs: [], name: 'Aera__SolvingPaused' },
+  { type: 'error', inputs: [], name: 'Aera__SyncDepositDisabled' },
+  { type: 'error', inputs: [], name: 'Aera__SyncRedeemAbsoluteCapNumeraireZero' },
+  { type: 'error', inputs: [], name: 'Aera__SyncRedeemDisabled' },
+  { type: 'error', inputs: [], name: 'Aera__SyncRedeemEpochCapExceeded' },
+  { type: 'error', inputs: [], name: 'Aera__SyncRedeemMaxDynamicPremiumBpsTooHigh' },
+  { type: 'error', inputs: [], name: 'Aera__SyncRedeemMaxPriceAgeExceeded' },
+  { type: 'error', inputs: [], name: 'Aera__SyncRedeemMaxPriceAgeZero' },
+  { type: 'error', inputs: [], name: 'Aera__SyncRedeemNotConfigured' },
+  { type: 'error', inputs: [], name: 'Aera__SyncRedeemRelativeCapBpsTooHigh' },
+  { type: 'error', inputs: [], name: 'Aera__SyncRedeemRelativeCapBpsZero' },
+  { type: 'error', inputs: [], name: 'Aera__TokenCantBePriced' },
+  { type: 'error', inputs: [], name: 'Aera__TokensZero' },
+  { type: 'error', inputs: [], name: 'Aera__Unauthorized' },
+  { type: 'error', inputs: [], name: 'Aera__UnitsLocked' },
+  { type: 'error', inputs: [], name: 'Aera__UnitsZero' },
+  { type: 'error', inputs: [], name: 'Aera__ZeroAddressAuthority' },
+  { type: 'error', inputs: [], name: 'Aera__ZeroAddressMultiDepositorVault' },
+  { type: 'error', inputs: [], name: 'Aera__ZeroAddressPriceAndFeeCalculator' },
+  { type: 'error', inputs: [], name: 'Aera__ZeroAddressReceiver' },
+  { type: 'error', inputs: [], name: 'ReentrancyGuardReentrantCall' },
+  {
+    type: 'error',
+    inputs: [{ name: 'token', internalType: 'address', type: 'address' }],
+    name: 'SafeERC20FailedOperation',
+  },
 ] as const;

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';
@@ -321,9 +323,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 +332,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 +399,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) {