@gauntlet-xyz/sdk 2.0.0 → 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/evm/abis/provisionerV2.ts

@@ -199,4 +199,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/index.ts

@@ -2,6 +2,8 @@ export { GauntletClient, AttributionMode } from './client';
 export type { GauntletClientConfig } from './client';
 export { ContractVersion } from './evm/types';
 
+export * from './api';
+
 export type {
   VaultInfo,
   VaultDeployment,

package/src/privy/index.ts

@@ -0,0 +1,95 @@
+import {
+  createPublicClient,
+  createWalletClient,
+  custom,
+  http,
+  type Address,
+  type Chain,
+  type EIP1193Provider,
+  type PublicClient,
+  type Transport,
+  type WalletClient,
+} from 'viem';
+import { AttributionMode, GauntletClient, type ChainId } from '../client';
+
+/**
+ * Structural view of a Privy embedded or connected wallet — matches
+ * `ConnectedWallet` from `@privy-io/react-auth` (via `useWallets()`) and
+ * `PrivyClient`-side wallets without importing Privy types, so the SDK has no
+ * dependency on any `@privy-io` package.
+ */
+export interface PrivyEthereumWallet {
+  /** The wallet's EVM address. */
+  address: string;
+  /** Privy's EIP-1193 provider factory for this wallet. */
+  getEthereumProvider(): Promise<EIP1193Provider>;
+}
+
+/**
+ * Wraps a Privy wallet in a viem `WalletClient` bound to `chain`, ready to
+ * sign SDK transaction steps.
+ *
+ * ```ts
+ * const { wallets } = useWallets();
+ * const wallet = await walletClientFromPrivy(wallets[0], base);
+ * ```
+ */
+export async function walletClientFromPrivy(
+  wallet: PrivyEthereumWallet,
+  chain: Chain
+): Promise<WalletClient> {
+  const provider = await wallet.getEthereumProvider();
+  return createWalletClient({
+    account: wallet.address as Address,
+    chain,
+    transport: custom(provider),
+  });
+}
+
+export interface PrivyGauntletClientConfig {
+  /** The Privy wallet to sign with (e.g. `useWallets().wallets[0]`). */
+  wallet: PrivyEthereumWallet;
+  /** Chains the client should be able to read from; the first is the wallet's signing chain. */
+  chains: [Chain, ...Chain[]];
+  /** Per-chain transport override; defaults to each chain's public RPC via `http()`. */
+  transports?: Record<ChainId, Transport>;
+  apiKey?: string;
+  apiUrl?: string;
+  attributionMode?: AttributionMode;
+  builderCode?: string;
+}
+
+/**
+ * Opinionated one-call setup for Privy apps: builds public clients for each
+ * chain and a signing wallet from the Privy provider, returning a fully
+ * configured `GauntletClient`.
+ *
+ * ```ts
+ * const client = await createGauntletClientFromPrivy({
+ *   wallet: wallets[0],
+ *   chains: [base],
+ *   builderCode: 'my-app',
+ * });
+ * const steps = await getDepositTx(client, { vaultId, amount });
+ * ```
+ */
+export async function createGauntletClientFromPrivy(
+  config: PrivyGauntletClientConfig
+): Promise<GauntletClient> {
+  const evmClients: Record<ChainId, PublicClient> = {};
+  for (const chain of config.chains) {
+    evmClients[chain.id] = createPublicClient({
+      chain,
+      transport: config.transports?.[chain.id] ?? http(),
+    });
+  }
+
+  return new GauntletClient({
+    evmClients,
+    wallet: await walletClientFromPrivy(config.wallet, config.chains[0]),
+    apiKey: config.apiKey,
+    apiUrl: config.apiUrl,
+    attributionMode: config.attributionMode,
+    builderCode: config.builderCode,
+  });
+}