@gauntlet-xyz/sdk 2.5.0 → 3.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gauntlet-xyz/sdk",
-  "version": "2.5.0",
+  "version": "3.1.1",
   "description": "Official Gauntlet SDK for vault deposits, withdrawals, and attribution",
   "license": "MIT",
   "keywords": [
@@ -28,12 +28,44 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
     },
     "./evm": {
-      "types": "./dist/evm/index.d.ts",
-      "import": "./dist/evm/index.js"
+      "import": {
+        "types": "./dist/evm/index.d.ts",
+        "default": "./dist/evm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/evm/index.d.ts",
+        "default": "./dist/cjs/evm/index.js"
+      }
+    },
+    "./api": {
+      "import": {
+        "types": "./dist/api/index.d.ts",
+        "default": "./dist/api/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/api/index.d.ts",
+        "default": "./dist/cjs/api/index.js"
+      }
+    },
+    "./privy": {
+      "import": {
+        "types": "./dist/privy/index.d.ts",
+        "default": "./dist/privy/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/privy/index.d.ts",
+        "default": "./dist/cjs/privy/index.js"
+      }
     }
   },
   "files": [
@@ -42,14 +74,15 @@
     "manifest"
   ],
   "scripts": {
-    "build": "tsc --project tsconfig.json",
-    "dev": "tsc --project tsconfig.json --watch",
+    "build": "node scripts/build.mjs",
+    "dev": "node scripts/build.mjs --watch",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint --ext=tsx,ts,js src && echo-cli '✔ No ESLint warnings or errors'",
     "format": "eslint --fix --quiet --ext=tsx,ts,js src && echo-cli '✔ No ESLint warnings or errors'",
     "typecheck": "npx tsc --noEmit",
-    "clean": "rm -rf dist .turbo"
+    "clean": "rm -rf dist .turbo",
+    "test:node": "node --test tests/package.test.mjs"
   },
   "peerDependencies": {
     "viem": ">=2.0.0"
@@ -62,7 +95,8 @@
     "eslint": "^8.57.0",
     "typescript": "~5.6.3",
     "viem": "2.30.1",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.2",
+    "esbuild": "^0.25.0"
   },
   "engines": {
     "npm": ">=11.5.1",

package/src/api/activity.ts

@@ -1,3 +1,4 @@
+import { activityLifecycles, orderActivityRows } from './activityRows';
 import { GauntletSDKError } from '../errors';
 import type { ActivityOptions, GauntletApi, TokenRef, UserActivity } from './client';
 import { decimalToBigInt, sharesToBigInt } from './decimal';
@@ -44,8 +45,8 @@ const PENDING_TYPES = new Set(['deposit_pending', 'withdraw_pending']);
 const REFUNDED_TYPES = new Set(['deposit_refunded', 'withdraw_refunded']);
 
 function flowKind(rowType: string): ActivityFlowKind {
-  if (rowType.startsWith('deposit')) return 'deposit';
-  if (rowType.startsWith('withdraw')) return 'withdraw';
+  if (['deposit', 'deposit_pending', 'deposit_refunded'].includes(rowType)) return 'deposit';
+  if (['withdraw', 'withdraw_pending', 'withdraw_refunded'].includes(rowType)) return 'withdraw';
   if (rowType === 'transfer_in' || rowType === 'transfer_out') return rowType;
   throw new GauntletSDKError(`Unknown activity row type "${rowType}"`);
 }
@@ -88,19 +89,10 @@ function toAssetAmount(rows: UserActivity[]): AssetAmount {
  * `request_hash`. Flows are returned newest-first (by the flow's latest row).
  */
 export function stitchActivityFlows(rows: UserActivity[]): ActivityFlow[] {
-  const groups = new Map<string, UserActivity[]>();
-  for (const [index, row] of rows.entries()) {
-    // Rows without a request_hash are standalone sync flows: each one is its
-    // own group, so two same-type events in one transaction (e.g. a multicall
-    // doing two deposits) stay two flows.
-    const key = row.request_hash ?? `row:${index}`;
-    const group = groups.get(key);
-    if (group) group.push(row);
-    else groups.set(key, [row]);
-  }
+  const groups = activityLifecycles(orderActivityRows(rows));
 
   const flows: ActivityFlow[] = [];
-  for (const group of groups.values()) {
+  for (const group of groups) {
     group.sort((a, b) => a.block_timestamp - b.block_timestamp);
     const pendingRow = group.find((r) => PENDING_TYPES.has(r.type)) ?? null;
     const terminalRow = group.find((r) => !PENDING_TYPES.has(r.type)) ?? null;
@@ -183,6 +175,8 @@ export async function getActivityFlows(
 }
 
 export interface WaitForSettlementOptions {
+  /** Transaction hash of the submitted request. Prevents reuse of an earlier settlement. */
+  requestTxHash: string;
   /** CAIP-10 vault id — narrows polling to one vault's activity. */
   vaultId?: string;
   /** Polling interval. Defaults to 5s. */
@@ -200,15 +194,24 @@ export async function waitForRequestSettlement(
   api: GauntletApi,
   walletAddress: string,
   requestHash: string,
-  options: WaitForSettlementOptions = {}
+  options: WaitForSettlementOptions
 ): Promise<ActivityFlow> {
+  if (typeof options?.requestTxHash !== 'string' || options.requestTxHash.length === 0) {
+    throw new GauntletSDKError(
+      'Settlement polling requires the submitted request transaction hash'
+    );
+  }
   const pollIntervalMs = options.pollIntervalMs ?? 5_000;
   const timeoutMs = options.timeoutMs ?? 600_000;
   const deadline = Date.now() + timeoutMs;
 
   for (;;) {
     const flows = await getActivityFlows(api, walletAddress, { vaultId: options.vaultId });
-    const flow = flows.find((f) => f.requestHash === requestHash);
+    const flow = flows.find(
+      (f) =>
+        f.requestHash === requestHash &&
+        f.txHashes.some((hash) => hash.toLowerCase() === options.requestTxHash.toLowerCase())
+    );
     if (flow && flow.status !== 'pending') return flow;
 
     if (Date.now() + pollIntervalMs > deadline) {

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'];
@@ -12,7 +18,12 @@ export type UserPositionsTimeseriesResponse = Schemas['UserPositionsTimeseriesRe
 export type PositionTimeseriesPoint = Schemas['PositionTimeseriesPoint'];
 export type VaultDetail = Schemas['VaultDetail'];
 export type VaultDetailResponse = Schemas['VaultDetailResponse'];
+export type VaultListResponse = Schemas['VaultListResponse'];
+export type VaultAllocations = Schemas['VaultAllocations'];
+export type VaultAllocationsResponse = Schemas['VaultAllocationsResponse'];
 export type VaultTimeseriesResponse = Schemas['VaultTimeseriesResponse'];
+export type VaultGroupTimeseriesResponse = Schemas['VaultGroupTimeseriesResponse'];
+export type VaultGroupTimeseriesPoint = Schemas['VaultGroupTimeseriesPoint'];
 export type VaultTimeseriesPoint = Schemas['VaultTimeseriesPoint'];
 export type VaultMetrics = Schemas['VaultMetrics'];
 export type FeaturedVault = Schemas['FeaturedVault'];
@@ -20,6 +31,9 @@ export type FeaturedVaultsResponse = Schemas['FeaturedVaultsResponse'];
 export type StrategyCard = Schemas['StrategyCard'];
 export type StrategyListResponse = Schemas['StrategyListResponse'];
 export type TvlResponse = Schemas['TvlResponse'];
+export type TvlBreakdownMode = Schemas['TvlBreakdownMode'];
+export type TvlTimeseriesResponse = Schemas['TvlTimeseriesResponse'];
+export type TvlTimeseriesPoint = Schemas['TvlTimeseriesPoint'];
 export type LatestPriceResponse = Schemas['LatestPriceResponse'];
 export type PriceTimeseriesResponse = Schemas['TimeseriesResponse'];
 export type TokenRef = Schemas['TokenRef'];
@@ -62,6 +76,14 @@ export interface PositionsOptions extends PageOptions {
   includeHidden?: boolean;
 }
 
+export interface VaultsOptions extends PageOptions {
+  /**
+   * Include hidden (enabled but unlisted) vaults alongside visible ones.
+   * Disabled vaults are never listed.
+   */
+  includeHidden?: boolean;
+}
+
 export interface LatestPriceOptions {
   address: string;
   chainId: number;
@@ -117,8 +139,37 @@ export class GauntletApi {
   }
 
   /** GET /v1/vaults — all indexed vaults with live metrics (TVL, APY, unit price). */
-  vaults(options: PageOptions = {}): Promise<{ data: VaultDetail[]; meta: TimeseriesMeta }> {
-    return this.get('/v1/vaults', { next: options.next, limit: options.limit });
+  vaults(options: VaultsOptions = {}): Promise<{ data: VaultDetail[]; meta: TimeseriesMeta }> {
+    return this.get('/v1/vaults', {
+      next: options.next,
+      limit: options.limit,
+      include_hidden: options.includeHidden,
+    });
+  }
+
+  /** GET /v1/vaults/slug/{slug} — all enabled deployments for one exact vault slug. */
+  vaultsBySlug(slug: string): Promise<VaultListResponse> {
+    return this.get(`/v1/vaults/slug/${encodeURIComponent(slug)}`);
+  }
+
+  /** GET /v1/vaults/slug/{slug}/timeseries — aggregate USD TVL and supply, plus primary-deployment metrics.
+   * APY and unit price come from meta.resolved_vault_id; null marks missing data.
+   */
+  vaultTimeseriesBySlug(
+    slug: string,
+    options: TimeWindowOptions = {}
+  ): Promise<VaultGroupTimeseriesResponse> {
+    return this.get(`/v1/vaults/slug/${encodeURIComponent(slug)}/timeseries`, { ...options });
+  }
+
+  /** GET /v1/vaults/slug/{slug}/primary/timeseries — primary deployment history. */
+  primaryVaultTimeseriesBySlug(
+    slug: string,
+    options: TimeWindowOptions = {}
+  ): Promise<VaultTimeseriesResponse> {
+    return this.get(`/v1/vaults/slug/${encodeURIComponent(slug)}/primary/timeseries`, {
+      ...options,
+    });
   }
 
   /** GET /v1/vaults/featured — admin-curated featured vault cards. */
@@ -141,6 +192,11 @@ export class GauntletApi {
     return this.get(`/v1/vaults/${encodeURIComponent(vaultId)}/definition`);
   }
 
+  /** GET /v1/vaults/{vault_id}/allocations — current Aera allocations with source lineage. */
+  vaultAllocations(vaultId: string): Promise<VaultAllocationsResponse> {
+    return this.get(`/v1/vaults/${encodeURIComponent(vaultId)}/allocations`);
+  }
+
   /** GET /v1/vaults/{vault_id}/timeseries — TVL / unit-price / APY history. */
   vaultTimeseries(
     vaultId: string,
@@ -198,17 +254,60 @@ 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);
   }
 
-  /** GET /v1/tvl — aggregate Gauntlet TVL, optionally with per-source breakdown. */
-  tvl(options: { includeBreakdown?: boolean } = {}): Promise<TvlResponse> {
-    return this.get('/v1/tvl', { include_breakdown: options.includeBreakdown });
+  /**
+   * GET /v1/tvl — aggregate Gauntlet TVL. Pass `mode` for a `breakdown`:
+   * `chain` for one row per chain, `strategy` for one row per curated
+   * strategy. Omit it for the headline totals only.
+   */
+  tvl(options: { mode?: TvlBreakdownMode } = {}): Promise<TvlResponse> {
+    return this.get('/v1/tvl', { mode: options.mode });
+  }
+
+  /**
+   * GET /v1/tvl/timeseries — daily aggregate Gauntlet TVL over a fixed
+   * 3-month trailing window. `mode` partitions each point's `sources` the
+   * same way `tvl()` partitions its `breakdown`; a point's total never
+   * depends on it.
+   */
+  tvlTimeseries(options: { mode?: TvlBreakdownMode } = {}): Promise<TvlTimeseriesResponse> {
+    return this.get('/v1/tvl/timeseries', { mode: options.mode });
   }
 
   /** GET /v1/prices — latest USD price for a token. */

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);