@gauntlet-xyz/sdk 3.0.1 → 3.1.1

package/src/api/activityRows.ts

@@ -0,0 +1,143 @@
+import { GauntletSDKError } from '../errors';
+import type { UserActivity } from './client';
+import { decimalToBigInt, sharesToBigInt } from './decimal';
+
+export function isPending(row: UserActivity): boolean {
+  return row.type === 'deposit_pending' || row.type === 'withdraw_pending';
+}
+
+export function requireSameToken(leftRow: UserActivity, rightRow: UserActivity): void {
+  // The vault ID includes the chain ID; TokenRef has no chain field.
+  if (leftRow.vault_id.split(':')[0] !== rightRow.vault_id.split(':')[0]) {
+    throw new GauntletSDKError('Activity rows contain assets on different chains');
+  }
+  const left = leftRow.assets_delta.token;
+  const right = rightRow.assets_delta.token;
+  if (
+    left != null &&
+    right != null &&
+    (left.address.toLowerCase() !== right.address.toLowerCase() ||
+      (left.decimals ?? null) !== (right.decimals ?? null))
+  ) {
+    throw new GauntletSDKError('Activity rows contain different asset denominations');
+  }
+}
+
+export function validateActivityRow(row: UserActivity): void {
+  const shares = sharesToBigInt(row.shares_delta);
+  const assets = decimalToBigInt(row.assets_delta.native, 18);
+  if (
+    !Number.isSafeInteger(row.block_number) ||
+    row.block_number < 0 ||
+    !Number.isSafeInteger(row.block_timestamp) ||
+    row.block_timestamp < 0 ||
+    typeof row.vault_id !== 'string' ||
+    row.vault_id.length === 0 ||
+    typeof row.tx_hash !== 'string' ||
+    row.tx_hash.length === 0 ||
+    (row.request_hash != null &&
+      (typeof row.request_hash !== 'string' || row.request_hash.length === 0))
+  ) {
+    throw new GauntletSDKError('The activity row has invalid event identifiers');
+  }
+  const token = row.assets_delta.token;
+  if (token != null && token.decimals != null) {
+    if (!Number.isInteger(token.decimals) || token.decimals < 0 || token.decimals > 255) {
+      throw new GauntletSDKError('The activity token has invalid decimals');
+    }
+    decimalToBigInt(row.assets_delta.native, token.decimals);
+  }
+  let valid: boolean;
+  switch (row.type) {
+    case 'deposit':
+      valid = shares >= 0n && assets >= 0n && (row.request_hash == null || assets === 0n);
+      break;
+    case 'deposit_pending':
+      valid = shares === 0n && assets > 0n && row.request_hash != null;
+      break;
+    case 'deposit_refunded':
+      valid = shares === 0n && assets < 0n && row.request_hash != null;
+      break;
+    case 'withdraw':
+      valid = shares <= 0n && assets <= 0n && (row.request_hash == null || shares === 0n);
+      break;
+    case 'withdraw_pending':
+      valid = shares < 0n && assets === 0n && row.request_hash != null;
+      break;
+    case 'withdraw_refunded':
+      valid = shares > 0n && assets === 0n && row.request_hash != null;
+      break;
+    case 'transfer_in':
+      valid = shares >= 0n && assets >= 0n && row.request_hash == null;
+      break;
+    case 'transfer_out':
+      valid = shares <= 0n && assets <= 0n && row.request_hash == null;
+      break;
+    default:
+      valid = false;
+  }
+  if (!valid) throw new GauntletSDKError(`Invalid activity deltas for ${row.type}`);
+}
+
+export function orderActivityRows(rows: UserActivity[]): UserActivity[] {
+  rows.forEach(validateActivityRow);
+  return [...rows].sort(
+    (a, b) =>
+      a.block_number - b.block_number ||
+      a.block_timestamp - b.block_timestamp ||
+      Number(isPending(b)) - Number(isPending(a))
+  );
+}
+
+/**
+ * Split request hashes by vault and by each request occurrence.
+ * Takes the output of `orderActivityRows`.
+ */
+export function activityLifecycles(ordered: UserActivity[]): UserActivity[][] {
+  const groups: UserActivity[][] = [];
+  const latest = new Map<string, UserActivity[]>();
+  for (const row of ordered) {
+    if (row.request_hash == null) {
+      groups.push([row]);
+      continue;
+    }
+    const key = `${row.vault_id}:${row.request_hash}`;
+    const previous = latest.get(key);
+    if (previous === undefined || isPending(row)) {
+      if (previous !== undefined && previous.every(isPending)) {
+        throw new GauntletSDKError('An activity request has duplicate pending rows');
+      }
+      const group = [row];
+      latest.set(key, group);
+      groups.push(group);
+      continue;
+    }
+    if (previous.some((entry) => !isPending(entry))) {
+      throw new GauntletSDKError('An activity request has conflicting terminal rows');
+    }
+    const pending = previous[0];
+    requireSameToken(pending, row);
+    const expected =
+      pending.type === 'deposit_pending'
+        ? ['deposit', 'deposit_refunded']
+        : ['withdraw', 'withdraw_refunded'];
+    if (!expected.includes(row.type)) {
+      throw new GauntletSDKError('The activity terminal does not match its request');
+    }
+    if (
+      row.type === 'deposit_refunded' &&
+      decimalToBigInt(pending.assets_delta.native, 18) !==
+        -decimalToBigInt(row.assets_delta.native, 18)
+    ) {
+      throw new GauntletSDKError('The deposit refund does not match its request');
+    }
+    if (
+      row.type === 'withdraw_refunded' &&
+      sharesToBigInt(pending.shares_delta) !== -sharesToBigInt(row.shares_delta)
+    ) {
+      throw new GauntletSDKError('The withdrawal refund does not match its request');
+    }
+    previous.push(row);
+  }
+  return groups;
+}

package/src/api/caip.ts

@@ -16,7 +16,9 @@ export interface ApiVaultId {
 export function parseApiVaultId(id: string): ApiVaultId {
   const match = /^(?:eip155:)?(\d+):(0x[0-9a-fA-F]{40})$/.exec(id);
   if (!match) throw new InvalidCaipIdError(id);
-  return { chainId: Number(match[1]), address: match[2].toLowerCase() };
+  const chainId = Number(match[1]);
+  if (!Number.isSafeInteger(chainId) || chainId <= 0) throw new InvalidCaipIdError(id);
+  return { chainId, address: match[2].toLowerCase() };
 }
 
 export function formatApiVaultId(chainId: number, address: string): string {

package/src/api/client.ts

@@ -1,8 +1,14 @@
+import { parseApiVaultId } from './caip';
+import { GauntletApiError } from './errors';
 import type { components } from './generated';
 import { apiGet, type GauntletApiConfig, type QueryParams } from './http';
 
 type Schemas = components['schemas'];
 
+function activityError(message: string, code?: string): GauntletApiError {
+  return new GauntletApiError({ status: 200, path: '/v1/users/activity', message, code });
+}
+
 export type UserActivity = Schemas['UserActivity'];
 export type UserActivityResponse = Schemas['UserActivityResponse'];
 export type UserPosition = Schemas['UserPosition'];
@@ -248,11 +254,40 @@ export class GauntletApi {
     walletAddress: string,
     options: Omit<ActivityOptions, 'next'> = {}
   ): AsyncGenerator<UserActivity> {
+    const vault = options.vaultId === undefined ? undefined : parseApiVaultId(options.vaultId);
+    // Gaia pages on (timestamp, logIndex), which rows do not expose. Rows
+    // can repeat legitimately inside one transaction, so the boundary check
+    // is the timestamp order.
+    const descending = (options.order ?? 'desc') === 'desc';
+    let lastTimestamp: number | undefined;
     let next: string | undefined;
+    const cursors = new Set<string>();
     do {
       const page = await this.activity(walletAddress, { ...options, next });
-      yield* page.data;
+      if (page.meta.partial_errors?.length) {
+        throw activityError('The activity response is incomplete', 'INCOMPLETE_ACTIVITY');
+      }
+      for (const row of page.data) {
+        if (vault !== undefined) {
+          const rowVault = parseApiVaultId(row.vault_id);
+          if (rowVault.chainId !== vault.chainId || rowVault.address !== vault.address) {
+            throw activityError('The activity vault does not match the request');
+          }
+        }
+        if (
+          lastTimestamp !== undefined &&
+          (descending ? row.block_timestamp > lastTimestamp : row.block_timestamp < lastTimestamp)
+        ) {
+          throw activityError('The activity rows are out of order');
+        }
+        lastTimestamp = row.block_timestamp;
+        yield row;
+      }
       next = page.meta.next_cursor ?? undefined;
+      if (next !== undefined) {
+        if (cursors.has(next)) throw activityError('The activity cursor repeats');
+        cursors.add(next);
+      }
     } while (next);
   }
 

package/src/api/decimal.ts

@@ -17,6 +17,7 @@ export function decimalToBigInt(value: string, decimals: number): bigint {
   if (!Number.isInteger(decimals) || decimals < 0) {
     throw new InvalidDecimalError(`decimals=${decimals}`);
   }
+  if (typeof value !== 'string') throw new InvalidDecimalError(String(value));
   const match = DECIMAL_RE.exec(value);
   if (!match) throw new InvalidDecimalError(value);
 

package/src/api/http.ts

@@ -39,6 +39,7 @@ export async function apiGet<T>(
 
   const fetchImpl = config.fetch ?? fetch;
   const response = await fetchImpl(url, {
+    redirect: 'error',
     headers: {
       accept: 'application/json',
       ...(config.apiKey ? { 'x-api-key': config.apiKey } : {}),

package/src/api/positionHistory.ts

@@ -1,3 +1,4 @@
+import { activityLifecycles, orderActivityRows, requireSameToken } from './activityRows';
 import { GauntletSDKError } from '../errors';
 import type { GauntletApi, TokenRef, UserActivity } from './client';
 import { bigIntToDecimal, decimalToBigInt, sharesToBigInt } from './decimal';
@@ -57,8 +58,11 @@ export function buildPositionHistory(rows: UserActivity[]): PositionHistory {
     );
   }
 
-  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;
+  const ordered = orderActivityRows(rows);
+  activityLifecycles(ordered);
+  const tokenRow = ordered.find((r) => r.assets_delta.token) ?? ordered[0];
+  const token = tokenRow.assets_delta.token ?? null;
+  for (const row of ordered) requireSameToken(tokenRow, row);
 
   let sharesBalance = 0n;
   let pendingDepositAssets = 0n;
@@ -95,9 +99,14 @@ export function buildPositionHistory(rows: UserActivity[]): PositionHistory {
         if (row.request_hash != null) pendingDepositByHash.set(row.request_hash, assetsDelta);
         break;
       case 'deposit_refunded':
-        // Row carries the unwound request as a negative delta.
+        if (
+          row.request_hash == null ||
+          pendingDepositByHash.get(row.request_hash) !== -assetsDelta
+        ) {
+          throw new GauntletSDKError('The deposit refund does not match its escrow');
+        }
         pendingDepositAssets += assetsDelta;
-        if (row.request_hash != null) pendingDepositByHash.delete(row.request_hash);
+        pendingDepositByHash.delete(row.request_hash);
         break;
       case 'withdraw':
         // Sync withdraws and async terminal solves both carry the asset
@@ -121,8 +130,11 @@ export function buildPositionHistory(rows: UserActivity[]): PositionHistory {
         break;
       }
       case 'withdraw_refunded':
+        if (row.request_hash == null || pendingRedeemByHash.get(row.request_hash) !== sharesDelta) {
+          throw new GauntletSDKError('The withdrawal refund does not match its escrow');
+        }
         pendingRedeemShares -= sharesDelta;
-        if (row.request_hash != null) pendingRedeemByHash.delete(row.request_hash);
+        pendingRedeemByHash.delete(row.request_hash);
         break;
       case 'transfer_in':
       case 'transfer_out':
@@ -131,6 +143,9 @@ export function buildPositionHistory(rows: UserActivity[]): PositionHistory {
         throw new GauntletSDKError(`Unknown activity row type "${row.type}"`);
     }
 
+    if (sharesBalance < 0n || pendingDepositAssets < 0n || pendingRedeemShares < 0n) {
+      throw new GauntletSDKError('The activity history produces a negative position balance');
+    }
     points.push({
       timestamp: new Date(row.block_timestamp * 1000),
       txHash: row.tx_hash,

package/src/attribution/index.ts

@@ -8,13 +8,14 @@ export { encodeBuilderCode } from './erc8021';
 export type PreparedPayloadWithAttribution = {
   type: string;
   to: Address;
+  chainId: number;
   data: Hex;
   account?: Address;
 };
 
 export type PreparedTx = {
   payload: PreparedPayloadWithAttribution;
-  tx: TxStep;
+  tx: TxStep & { chainId: number };
 };
 
 /**
@@ -38,7 +39,8 @@ export async function buildAttribution(client: GauntletClient): Promise<Hex> {
 
 export async function encodeTransactionWithAttribution(
   client: GauntletClient,
-  transaction: TxStep
+  transaction: TxStep,
+  chainId: number
 ): Promise<PreparedTx> {
   const customAttribution = await buildAttribution(client);
   const encodedTx = encodeFunctionData({
@@ -52,10 +54,12 @@ export async function encodeTransactionWithAttribution(
       type: transaction.type,
       account: transaction.account,
       to: transaction.address,
+      chainId,
       data: encodedTxWithAttribution,
     },
     tx: {
       ...transaction,
+      chainId,
       attribution: customAttribution,
     },
   };

package/src/evm/adapters/aera.ts

@@ -430,17 +430,35 @@ export const aeraAdapter: EvmProtocolAdapter = {
         throw new InvalidWithdrawParamsError();
       }
 
-      const tokenOutBeforeTip = await getAsyncRedeemTokenOut(
-        publicClient,
-        runtime,
-        vault.vaultAddress,
-        asset.address,
-        shares
-      );
-      minTokenOut = applySlippageDown(subtractSolverTip(tokenOutBeforeTip, solverTip), slippageBps);
+      const tokensOut =
+        'amount' in params && params.amount != null
+          ? params.amount
+          : subtractSolverTip(
+              await getAsyncRedeemTokenOut(
+                publicClient,
+                runtime,
+                vault.vaultAddress,
+                asset.address,
+                shares
+              ),
+              solverTip
+            );
+      minTokenOut = applySlippageDown(tokensOut, slippageBps);
       maxUnitsIn = shares;
     }
 
+    if (params.maxShares !== undefined) {
+      if (
+        isAsync ||
+        typeof params.maxShares !== 'bigint' ||
+        params.maxShares <= 0n ||
+        (!isV2ExactTokenWithdraw && shares !== undefined && shares > params.maxShares)
+      ) {
+        throw new InvalidWithdrawParamsError();
+      }
+      if (maxUnitsIn > params.maxShares) maxUnitsIn = params.maxShares;
+    }
+
     const steps: EvmTxStep[] = [];
 
     if (isAsync) {

package/src/evm/adapters/types.ts

@@ -57,6 +57,7 @@ export type AdapterWithdrawParams = {
   maxPriceAge?: bigint;
   aeraRuntime?: AeraRuntimeContracts;
   syncWithdrawQuote?: SyncWithdrawQuoteBounds;
+  maxShares?: bigint;
 } & (
   | { shares: bigint; amount?: never; entireAmount?: never }
   | { amount: bigint; shares?: never; entireAmount?: never }

package/src/evm/aeraContracts.ts

@@ -17,8 +17,6 @@ import { MAX_BPS } from '../constants';
 import { ContractVersion, type EvmVaultDeployment } from './types';
 import { readAtBlock } from './aeraContracts/readOptions';
 
-const contractVersionCache = new Map<string, ContractVersion>();
-
 const contractVersionAbi = [
   {
     type: 'function',
@@ -81,10 +79,6 @@ export function applySlippageUp(amount: bigint, slippageBps: number): bigint {
   return (amount * (MAX_BPS + BigInt(slippageBps)) + MAX_BPS - 1n) / MAX_BPS;
 }
 
-function contractVersionCacheKey(client: PublicClient, address: Address): string {
-  return `${client.chain?.id ?? 'unknown'}:${address.toLowerCase()}`;
-}
-
 function isVersionUnavailableError(error: unknown): boolean {
   if (!(error instanceof ContractFunctionExecutionError) || error.functionName !== 'version') {
     return false;
@@ -122,15 +116,35 @@ export function getMultiDepositorVault<T extends Client>(
   });
 }
 
+// Latest-block versions per client. Historical reads and failed reads are not cached.
+const latestContractVersions = new WeakMap<PublicClient, Map<string, ContractVersion>>();
+
 export async function resolveContractVersion(
   client: PublicClient,
   address: Address,
   options: AeraReadOptions = {}
 ): Promise<ContractVersion> {
-  const cacheKey = contractVersionCacheKey(client, address);
-  const cached = contractVersionCache.get(cacheKey);
-  if (cached) return cached;
+  if (options.blockNumber !== undefined) return readContractVersion(client, address, options);
 
+  let versions = latestContractVersions.get(client);
+  if (versions === undefined) {
+    versions = new Map();
+    latestContractVersions.set(client, versions);
+  }
+  const key = address.toLowerCase();
+  const cached = versions.get(key);
+  if (cached !== undefined) return cached;
+
+  const version = await readContractVersion(client, address, options);
+  versions.set(key, version);
+  return version;
+}
+
+async function readContractVersion(
+  client: PublicClient,
+  address: Address,
+  options: AeraReadOptions
+): Promise<ContractVersion> {
   try {
     const versionString = await client.readContract({
       address,
@@ -138,14 +152,15 @@ export async function resolveContractVersion(
       functionName: 'version',
       ...readAtBlock(options),
     });
-    const version = versionString.startsWith('2.') ? ContractVersion.V2 : ContractVersion.V1;
-    contractVersionCache.set(cacheKey, version);
-
-    return version;
+    if (!/^[12]\./.test(versionString)) {
+      throw new UnsupportedFeatureError(`Aera: unsupported contract version ${versionString}`);
+    }
+    return versionString.startsWith('2.') ? ContractVersion.V2 : ContractVersion.V1;
   } catch (error) {
     if (!isVersionUnavailableError(error)) throw error;
 
-    contractVersionCache.set(cacheKey, ContractVersion.V1);
+    const code = await client.getCode({ address, ...readAtBlock(options) });
+    if (code === undefined || code === '0x') throw error;
     return ContractVersion.V1;
   }
 }

package/src/evm/deposit.ts

@@ -48,8 +48,9 @@ export interface EvmDepositParams {
 /**
  * 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
+ * Returns ordered transactions: ERC-20 approvals (if the allowance is insufficient),
+ * followed by the deposit or async deposit request. Some tokens require an approval
+ * of zero before a new nonzero approval. 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.
@@ -77,6 +78,7 @@ export async function getDepositTx(
   client: GauntletClient,
   params: EvmDepositParams
 ): Promise<PreparedTx[]> {
+  params = structuredClone(params);
   const slippageBps = params.slippageBps ?? DEFAULT_BPS;
   if (!Number.isInteger(slippageBps) || slippageBps < 0 || slippageBps > Number(MAX_BPS)) {
     throw new InvalidSlippageBPSError(slippageBps);
@@ -141,7 +143,7 @@ export async function getDepositTx(
       : vault.vaultAddress;
 
   // NOTE: this could be moved to the buildDeposit level
-  const { sufficient } = await adapter.checkAllowance({
+  const { sufficient, current } = await adapter.checkAllowance({
     publicClient,
     token: token.address,
     owner: account,
@@ -152,14 +154,43 @@ export async function getDepositTx(
   const steps: EvmTxStep[] = [];
 
   if (!sufficient) {
-    steps.push(
-      adapter.buildApproval({
-        token: token.address,
-        spender,
-        amount: params.amount,
-        account,
-      })
-    );
+    const approval = adapter.buildApproval({
+      token: token.address,
+      spender,
+      amount: params.amount,
+      account,
+    });
+    if (current > 0n && params.amount > 0n) {
+      try {
+        await publicClient.estimateContractGas({
+          address: approval.address,
+          abi: approval.abi,
+          functionName: 'approve',
+          args: approval.args,
+          account,
+        });
+      } catch (approvalError) {
+        const reset = adapter.buildApproval({
+          token: token.address,
+          spender,
+          amount: 0n,
+          account,
+        });
+        try {
+          await publicClient.estimateContractGas({
+            address: reset.address,
+            abi: reset.abi,
+            functionName: 'approve',
+            args: reset.args,
+            account,
+          });
+        } catch {
+          throw approvalError;
+        }
+        steps.push(reset);
+      }
+    }
+    steps.push(approval);
   }
 
   const depositSteps = await adapter.buildDeposit({
@@ -178,5 +209,5 @@ export async function getDepositTx(
   });
   steps.push(...depositSteps);
 
-  return Promise.all(steps.map((step) => encodeTransactionWithAttribution(client, step)));
+  return Promise.all(steps.map((step) => encodeTransactionWithAttribution(client, step, chainId)));
 }

package/src/evm/depositQuote.ts

@@ -95,6 +95,7 @@ export async function getSyncDepositQuote(
   client: GauntletClient,
   params: SyncDepositQuoteParams
 ): Promise<SyncDepositQuote> {
+  params = structuredClone(params);
   const slippageBps = params.slippageBps ?? DEFAULT_BPS;
   if (!Number.isInteger(slippageBps) || slippageBps < 0 || slippageBps > Number(MAX_BPS)) {
     throw new InvalidSlippageBPSError(slippageBps);

package/src/evm/depositReceiverApproval.ts

@@ -25,6 +25,7 @@ export async function getDepositReceiverApprovalTx(
   client: GauntletClient,
   params: EvmDepositReceiverApprovalParams
 ): Promise<PreparedTx> {
+  params = { ...params };
   const resolved = await resolveVault(client, params.vaultId, params.chainId);
   if (!resolved) throw new VaultNotFoundError(params.vaultId);
 
@@ -39,13 +40,17 @@ export async function getDepositReceiverApprovalTx(
     throw new UnsupportedFeatureError('Aera: deposit receiver approval on V1');
   }
 
-  return encodeTransactionWithAttribution(client, {
-    type: 'setDepositReceiverApproval',
-    ...provisionerV2.setDepositReceiverApprovalTxRequest(
-      runtime.provisioner.address,
-      params.depositor,
-      params.approved ?? true,
-      receiver
-    ),
-  });
+  return encodeTransactionWithAttribution(
+    client,
+    {
+      type: 'setDepositReceiverApproval',
+      ...provisionerV2.setDepositReceiverApprovalTxRequest(
+        runtime.provisioner.address,
+        params.depositor,
+        params.approved ?? true,
+        receiver
+      ),
+    },
+    chainId
+  );
 }