@gauntlet-xyz/sdk 1.0.6 → 2.3.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,65 @@
+export { GauntletApi } from './client';
+export type {
+  ActivityOptions,
+  AmountPair,
+  ChainSyncStatus,
+  HealthResponse,
+  LatestPriceOptions,
+  LatestPriceResponse,
+  PageOptions,
+  PartialResponseError,
+  PositionTimeseriesPoint,
+  PriceTimeseriesOptions,
+  PriceTimeseriesResponse,
+  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/constants.ts

@@ -0,0 +1,32 @@
+export const MAX_BPS = 10000n;
+export const DEFAULT_BPS = 100;
+
+export const SECOND = 1;
+export const MINUTE = SECOND * 60;
+export const HOUR = MINUTE * 60;
+export const DAY = HOUR * 24;
+
+export const REQUEST_DEADLINE_BUFFER_DAYS = 3;
+export const DEFAULT_MAX_PRICE_AGE_DAYS = 10;
+export const DEFAULT_SOLVER_TIP = 0n;
+export const DEFAULT_REQUEST_DEADLINE_BUFFER = DAY * REQUEST_DEADLINE_BUFFER_DAYS;
+export const DEFAULT_MAX_PRICE_AGE = BigInt(DAY * DEFAULT_MAX_PRICE_AGE_DAYS);
+
+export 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.
+export const BLOCKS_3_DAYS: Record<number, bigint> = {
+  1: 21_600n,
+  8453: 129_600n,
+  42161: 1_036_800n,
+  10: 129_600n,
+};
+export const DEFAULT_BLOCKS_3_DAYS = 129_600n;
+
+// Many RPC providers cap eth_getLogs to 10,000 blocks per request.
+export const LOG_PAGE_SIZE = 9_999n;

package/src/errors.ts

@@ -1,4 +1,5 @@
-import { ChainId } from './client';
+import type { ChainId } from './client';
+import { MAX_BPS } from './constants';
 
 export class GauntletSDKError extends Error {
   constructor(message: string) {
@@ -48,10 +49,10 @@ export class ChainMismatchError extends GauntletSDKError {
 
 export class UnsupportedDepositModeError extends GauntletSDKError {
   readonly vaultId: string;
-  readonly requested: 'sync' | 'async';
+  readonly requested: string;
   readonly available: string;
 
-  constructor(vaultId: string, requested: 'sync' | 'async', available: string) {
+  constructor(vaultId: string, requested: string, available: string) {
     super(`Vault "${vaultId}" does not support ${requested} deposits (available: ${available})`);
     this.name = 'UnsupportedDepositModeError';
     this.vaultId = vaultId;
@@ -109,7 +110,7 @@ export class UnsupportedFeatureError extends GauntletSDKError {
 
   constructor(feature: string) {
     super(`Feature not supported: "${feature}"`);
-    this.name = 'UnimplementedFeatureError';
+    this.name = 'UnsupportedFeatureError';
     this.feature = feature;
   }
 }
@@ -124,11 +125,49 @@ export class UnitConversionError extends GauntletSDKError {
   }
 }
 
+export class StalePriceError extends GauntletSDKError {
+  readonly blockTimestamp: bigint;
+  readonly maxPriceAge: bigint;
+  readonly priceTimestamp: bigint;
+
+  constructor({
+    blockTimestamp,
+    maxPriceAge,
+    priceTimestamp,
+  }: {
+    blockTimestamp: bigint;
+    maxPriceAge: bigint;
+    priceTimestamp: bigint;
+  }) {
+    super(
+      `Price is stale: timestamp "${priceTimestamp}" with max age "${maxPriceAge}" is older than block timestamp "${blockTimestamp}"`
+    );
+    this.name = 'StalePriceError';
+    this.blockTimestamp = blockTimestamp;
+    this.maxPriceAge = maxPriceAge;
+    this.priceTimestamp = priceTimestamp;
+  }
+}
+
+export class InvalidSolverTipError extends GauntletSDKError {
+  readonly solverTip: bigint;
+  readonly availableAmount: bigint;
+
+  constructor(solverTip: bigint, availableAmount: bigint) {
+    super(
+      `Solver tip "${solverTip}" must be less than available token amount "${availableAmount}"`
+    );
+    this.name = 'InvalidSolverTipError';
+    this.solverTip = solverTip;
+    this.availableAmount = availableAmount;
+  }
+}
+
 export class InvalidSlippageBPSError extends GauntletSDKError {
   readonly slippage: number;
 
   constructor(slippage: number) {
-    super(`Slippage not in range of 10000-0; argumet passed: ${slippage}`);
+    super(`Slippage not in range of 0-${Number(MAX_BPS)}; argument passed: ${slippage}`);
     this.name = 'IncorrectArgument';
     this.slippage = slippage;
   }

package/src/evm/abis/priceAndFeeCalculatorV2.ts

@@ -0,0 +1,118 @@
+// Compact ABI derived from aera-finance/aera-contracts-v3@f4e3433058c29c3a0b1348ffbd358cc036a1687f
+// source: src/core/interfaces/IPriceAndFeeCalculatorV2.sol
+export const priceAndFeeCalculatorV2Abi = [
+  {
+    type: 'function',
+    inputs: [
+      { name: 'vault', internalType: 'address', type: 'address' },
+      { name: 'token', internalType: 'contract IERC20', type: 'address' },
+      { name: 'tokenAmount', internalType: 'uint256', type: 'uint256' },
+    ],
+    name: 'convertTokenToUnits',
+    outputs: [{ name: 'unitsAmount', 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: 'rounding', internalType: 'enum Math.Rounding', type: 'uint8' },
+    ],
+    name: 'convertTokenToUnitsIfActive',
+    outputs: [{ name: 'unitsAmount', internalType: 'uint256', type: 'uint256' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    inputs: [
+      { name: 'vault', internalType: 'address', type: 'address' },
+      { name: 'token', internalType: 'contract IERC20', type: 'address' },
+      { name: 'unitsAmount', internalType: 'uint256', type: 'uint256' },
+    ],
+    name: 'convertUnitsToToken',
+    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: 'unitsAmount', internalType: 'uint256', type: 'uint256' },
+      { name: 'rounding', internalType: 'enum Math.Rounding', type: 'uint8' },
+    ],
+    name: 'convertUnitsToTokenIfActive',
+    outputs: [{ name: 'tokenAmount', internalType: 'uint256', type: 'uint256' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    inputs: [{ name: 'vault', internalType: 'address', type: 'address' }],
+    name: 'getAnchorTimestamp',
+    outputs: [{ name: 'timestamp', internalType: 'uint32', type: 'uint32' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    inputs: [{ name: 'vault', internalType: 'address', type: 'address' }],
+    name: 'getVaultState',
+    outputs: [
+      {
+        name: '',
+        internalType: 'struct VaultPriceStateV2',
+        type: 'tuple',
+        components: [
+          { name: 'paused', internalType: 'bool', type: 'bool' },
+          { name: 'pauseOnBadAnchorUpdate', internalType: 'bool', type: 'bool' },
+          { name: 'maxPriceAge', internalType: 'uint16', type: 'uint16' },
+          { name: 'minUpdateIntervalMinutes', internalType: 'uint16', type: 'uint16' },
+          { name: 'maxPriceToleranceRatio', internalType: 'uint16', type: 'uint16' },
+          { name: 'minPriceToleranceRatio', internalType: 'uint16', type: 'uint16' },
+          { name: 'maxUpdateDelayDays', internalType: 'uint8', type: 'uint8' },
+          { name: 'accrualLag', internalType: 'uint32', type: 'uint32' },
+          { name: 'anchorTimestamp', internalType: 'uint32', type: 'uint32' },
+          { name: 'driftTimestamp', internalType: 'uint32', type: 'uint32' },
+          { name: 'anchorPrice', internalType: 'uint128', type: 'uint128' },
+          { name: 'driftPrice', internalType: 'uint128', type: 'uint128' },
+          { name: 'highestPrice', internalType: 'uint128', type: 'uint128' },
+          { name: 'lastTotalSupply', internalType: 'uint128', type: 'uint128' },
+        ],
+      },
+      {
+        name: '',
+        internalType: 'struct VaultAccruals',
+        type: 'tuple',
+        components: [
+          {
+            name: 'fees',
+            internalType: 'struct Fee',
+            type: 'tuple',
+            components: [
+              { name: 'tvl', internalType: 'uint16', type: 'uint16' },
+              { name: 'performance', internalType: 'uint16', type: 'uint16' },
+            ],
+          },
+          { name: 'accruedFees', internalType: 'uint112', type: 'uint112' },
+          { name: 'accruedProtocolFees', internalType: 'uint112', type: 'uint112' },
+        ],
+      },
+    ],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    inputs: [{ name: 'vault', internalType: 'address', type: 'address' }],
+    name: 'isVaultPaused',
+    outputs: [{ name: '', internalType: 'bool', type: 'bool' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    inputs: [],
+    name: 'version',
+    outputs: [{ name: '', internalType: 'string', type: 'string' }],
+    stateMutability: 'pure',
+  },
+] as const;