@gauntlet-xyz/sdk 2.0.0 → 2.5.0

package/dist/privy/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/privy/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,KAAK,EACV,KAAK,eAAe,EAEpB,KAAK,SAAS,EACd,KAAK,YAAY,EAClB,MAAM,MAAM,CAAC;AACd,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1E;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,mBAAmB,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;CACjD;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,mBAAmB,EAC3B,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,YAAY,CAAC,CAOvB;AAED,MAAM,WAAW,yBAAyB;IACxC,sEAAsE;IACtE,MAAM,EAAE,mBAAmB,CAAC;IAC5B,8FAA8F;IAC9F,MAAM,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;IAC5B,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,6BAA6B,CACjD,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,cAAc,CAAC,CAiBzB"}

package/dist/privy/index.js

@@ -0,0 +1,51 @@
+import { createPublicClient, createWalletClient, custom, http, } from 'viem';
+import { GauntletClient } from '../client';
+/**
+ * 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, chain) {
+    const provider = await wallet.getEthereumProvider();
+    return createWalletClient({
+        account: wallet.address,
+        chain,
+        transport: custom(provider),
+    });
+}
+/**
+ * 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) {
+    const evmClients = {};
+    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,
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/privy/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/privy/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,MAAM,EACN,IAAI,GAOL,MAAM,MAAM,CAAC;AACd,OAAO,EAAmB,cAAc,EAAgB,MAAM,WAAW,CAAC;AAe1E;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAA2B,EAC3B,KAAY;IAEZ,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,mBAAmB,EAAE,CAAC;IACpD,OAAO,kBAAkB,CAAC;QACxB,OAAO,EAAE,MAAM,CAAC,OAAkB;QAClC,KAAK;QACL,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC;KAC5B,CAAC,CAAC;AACL,CAAC;AAeD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,MAAiC;IAEjC,MAAM,UAAU,GAAkC,EAAE,CAAC;IACrD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,kBAAkB,CAAC;YACxC,KAAK;YACL,SAAS,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,IAAI,EAAE;SACnD,CAAC,CAAC;IACL,CAAC;IAED,OAAO,IAAI,cAAc,CAAC;QACxB,UAAU;QACV,MAAM,EAAE,MAAM,qBAAqB,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACpE,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,WAAW,EAAE,MAAM,CAAC,WAAW;KAChC,CAAC,CAAC;AACL,CAAC"}

package/manifest/vaults.json

@@ -1,5 +1,5 @@
 {
-  "version": "2026-05-15",
+  "version": "2026-08-05",
   "vaults": [
     {
       "vaultId": "baseUsdcPrime",
@@ -1746,7 +1746,7 @@
           "chainId": 1,
           "vaultAddress": "0x00000000d8f3d6c5DFeB2D2b5ED2276095f3aF44",
           "vaultType": "multi-depositor",
-          "expirationDays": 64,
+          "expirationDays": 90,
           "supplyToken": [
             {
               "address": "0xc26a6fa2c37b38e549a4a1807543801db684f99c",
@@ -1773,7 +1773,7 @@
           "chainId": 1,
           "vaultAddress": "0x953Ca96b057D5397CE7791C5AE9b5a19b1352341",
           "vaultType": "multi-depositor",
-          "expirationDays": 64,
+          "expirationDays": 90,
           "supplyToken": [
             {
               "address": "0x99e05cdbeac5d91150935c59ff8e9ba9945d6884",
@@ -2074,6 +2074,258 @@
           ]
         }
       ]
+    },
+    {
+      "vaultId": "exausd",
+      "name": "exaUSD",
+      "protocol": "aera",
+      "strategy": "Institutional USD Yield Vault",
+      "deployments": [
+        {
+          "chain": "evm",
+          "chainId": 8453,
+          "vaultAddress": "0xDDDFf4bE1a90CD6F05CE1e977c674ff3aa556C97",
+          "vaultType": "multi-depositor",
+          "supplyToken": [
+            {
+              "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+              "symbol": "USDC",
+              "decimals": 6
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "vaultId": "exaeth",
+      "name": "exaETH",
+      "protocol": "aera",
+      "strategy": "Institutional ETH Yield Vault",
+      "deployments": [
+        {
+          "chain": "evm",
+          "chainId": 1,
+          "vaultAddress": "0x2B02DA0A074b690075f0b8E6921e2526B0Ff7896",
+          "vaultType": "multi-depositor",
+          "supplyToken": [
+            {
+              "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+              "symbol": "WETH",
+              "decimals": 18
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "vaultId": "prime",
+      "name": "Gauntlet Levered PRIME",
+      "protocol": "aera",
+      "strategy": "Levered PRIME Looping",
+      "deployments": [
+        {
+          "chain": "evm",
+          "chainId": 1,
+          "vaultAddress": "0xc4C7Ea9af473046559F0492bbBa186A2E043fe94",
+          "vaultType": "multi-depositor",
+          "supplyToken": [
+            {
+              "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+              "symbol": "USDC",
+              "decimals": 6
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "vaultId": "stgprime",
+      "name": "Gauntlet Levered PRIME Staging",
+      "protocol": "aera",
+      "strategy": "Levered PRIME Looping",
+      "deployments": [
+        {
+          "chain": "evm",
+          "chainId": 1,
+          "vaultAddress": "0x8F2d98522B977C33a1EFDD4e25b0B045777B2193",
+          "vaultType": "multi-depositor",
+          "supplyToken": [
+            {
+              "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+              "symbol": "USDC",
+              "decimals": 6
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "vaultId": "devprime",
+      "name": "Gauntlet Levered PRIME Dev",
+      "protocol": "aera",
+      "strategy": "Levered PRIME Looping",
+      "deployments": [
+        {
+          "chain": "evm",
+          "chainId": 1,
+          "vaultAddress": "0x9E96A8A209D423F422293FCD5534a6b36cc376dA",
+          "vaultType": "multi-depositor",
+          "supplyToken": [
+            {
+              "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+              "symbol": "USDC",
+              "decimals": 6
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "vaultId": "gtlpraen",
+      "name": "gtLPRAEN",
+      "protocol": "aera",
+      "strategy": "Gauntlet x Raenest Base LP Vault",
+      "deployments": [
+        {
+          "chain": "evm",
+          "chainId": 8453,
+          "vaultAddress": "0x970173b2666736ebe040e2C3bef6c62664D9b0B9",
+          "vaultType": "multi-depositor",
+          "supplyToken": [
+            {
+              "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+              "symbol": "USDC",
+              "decimals": 6
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "vaultId": "devusdhy",
+      "name": "devUSDhy",
+      "protocol": "aera",
+      "strategy": "Gauntlet High Yield Dev",
+      "deployments": [
+        {
+          "chain": "evm",
+          "chainId": 1,
+          "vaultAddress": "0xeAf1f4C98635b56021a3EAabC08Fca3b24214084",
+          "vaultType": "single-depositor",
+          "supplyToken": [
+            {
+              "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+              "symbol": "USDC",
+              "decimals": 6
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "vaultId": "stgusdhy",
+      "name": "stgUSDhy",
+      "protocol": "aera",
+      "strategy": "Gauntlet High Yield Staging",
+      "deployments": [
+        {
+          "chain": "evm",
+          "chainId": 1,
+          "vaultAddress": "0x12081d6D2fC9AFe58390FF7B8909c8A31d4F4Ff2",
+          "vaultType": "multi-depositor",
+          "supplyToken": [
+            {
+              "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+              "symbol": "USDC",
+              "decimals": 6
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "vaultId": "gtusdhy",
+      "name": "gtUSDhy",
+      "protocol": "aera",
+      "strategy": "Gauntlet High Yield Prod",
+      "deployments": [
+        {
+          "chain": "evm",
+          "chainId": 1,
+          "vaultAddress": "0x15218Fbb0Efc0A3D5D731a242d853fa625532C3D",
+          "vaultType": "multi-depositor",
+          "supplyToken": [
+            {
+              "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+              "symbol": "USDC",
+              "decimals": 6
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "vaultId": "gtlooper",
+      "name": "sUSDS Looping Dev",
+      "protocol": "aera",
+      "strategy": "sUSDS Looping",
+      "deployments": [
+        {
+          "chain": "evm",
+          "chainId": 1,
+          "vaultAddress": "0x65bC393D16381b292221A664a783812A89f11DE6",
+          "vaultType": "multi-depositor",
+          "supplyToken": [
+            {
+              "address": "0xdC035D45d973E3EC169d2276DDab16f1e407384F",
+              "symbol": "USDS",
+              "decimals": 18
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "vaultId": "stgskylev",
+      "name": "sUSDS Looping Staging",
+      "protocol": "aera",
+      "strategy": "sUSDS Looping",
+      "deployments": [
+        {
+          "chain": "evm",
+          "chainId": 1,
+          "vaultAddress": "0x8BE13F43F1693F98343bD0C3DB6bE705D57221A3",
+          "vaultType": "multi-depositor",
+          "supplyToken": [
+            {
+              "address": "0xdC035D45d973E3EC169d2276DDab16f1e407384F",
+              "symbol": "USDS",
+              "decimals": 18
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "vaultId": "gtskylooping",
+      "name": "Gauntlet sUSDS Looping",
+      "protocol": "aera",
+      "strategy": "sUSDS Looping",
+      "deployments": [
+        {
+          "chain": "evm",
+          "chainId": 1,
+          "vaultAddress": "0xeA40De595f099cA04695b0Ca105499E50AF77f92",
+          "vaultType": "multi-depositor",
+          "supplyToken": [
+            {
+              "address": "0xdC035D45d973E3EC169d2276DDab16f1e407384F",
+              "symbol": "USDS",
+              "decimals": 18
+            }
+          ]
+        }
+      ]
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gauntlet-xyz/sdk",
-  "version": "2.0.0",
+  "version": "2.5.0",
   "description": "Official Gauntlet SDK for vault deposits, withdrawals, and attribution",
   "license": "MIT",
   "keywords": [
@@ -60,7 +60,7 @@
     "@viem/anvil": "^0.0.10",
     "echo-cli": "^2.0.0",
     "eslint": "^8.57.0",
-    "typescript": "~5.5.4",
+    "typescript": "~5.6.3",
     "viem": "2.30.1",
     "vitest": "^4.1.2"
   },

package/src/api/activity.ts

@@ -0,0 +1,219 @@
+import { GauntletSDKError } from '../errors';
+import type { ActivityOptions, GauntletApi, TokenRef, UserActivity } from './client';
+import { decimalToBigInt, sharesToBigInt } from './decimal';
+import { SettlementTimeoutError } from './errors';
+
+export type ActivityFlowKind = 'deposit' | 'withdraw' | 'transfer_in' | 'transfer_out';
+export type ActivityFlowStatus = 'settled' | 'pending' | 'refunded';
+
+/** A signed token amount as reported by the API, with base-unit conversion when possible. */
+export interface AssetAmount {
+  /** Human-unit decimal string exactly as the API emits it, e.g. `"1250.5"`. */
+  decimal: string;
+  /** Base-unit integer (`decimal × 10^token.decimals`); null when the token's decimals are unknown. */
+  raw: bigint | null;
+  token: TokenRef | null;
+}
+
+/**
+ * One user action against a vault, stitched from the activity log's immutable
+ * rows. Sync flows (Morpho, secondary-market transfers) come from a single
+ * row; Aera async flows pair a `*_pending` request row with its terminal
+ * settle/refund row via `request_hash`.
+ */
+export interface ActivityFlow {
+  kind: ActivityFlowKind;
+  status: ActivityFlowStatus;
+  /** CAIP-10 vault id (`"{chainId}:{address}"`). */
+  vaultId: string;
+  /** Aera async correlation hash; null for sync flows and transfers. */
+  requestHash: string | null;
+  /** When the request row landed. Null when the flow's pending row is outside the fetched window. */
+  requestedAt: Date | null;
+  /** When the terminal (settle/refund) row landed. Null while pending. */
+  settledAt: Date | null;
+  /** Magnitude of the flow's asset movement (requested amount for refunded flows). */
+  assets: AssetAmount;
+  /** Magnitude of the flow's share movement in 18-decimal base units. */
+  shares: bigint;
+  /** Transaction hashes in row order (request first, then settlement, when both are known). */
+  txHashes: string[];
+}
+
+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 (rowType === 'transfer_in' || rowType === 'transfer_out') return rowType;
+  throw new GauntletSDKError(`Unknown activity row type "${rowType}"`);
+}
+
+function abs(value: bigint): bigint {
+  return value < 0n ? -value : value;
+}
+
+/**
+ * Comparison 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.
+ */
+const ASSET_SCALE = 18;
+
+function toAssetAmount(rows: UserActivity[]): AssetAmount {
+  // Per the API contract, at most one row of an async lifecycle carries the
+  // asset movement (the other legs are "0"), so the max magnitude is the
+  // flow's amount. For refunded flows this surfaces the requested amount
+  // instead of the useless net of zero.
+  let best = rows[0];
+  let bestMagnitude = abs(decimalToBigInt(best.assets_delta.native, ASSET_SCALE));
+  for (const row of rows.slice(1)) {
+    const magnitude = abs(decimalToBigInt(row.assets_delta.native, ASSET_SCALE));
+    if (magnitude > bestMagnitude) {
+      best = row;
+      bestMagnitude = magnitude;
+    }
+  }
+  const token =
+    best.assets_delta.token ?? rows.find((r) => r.assets_delta.token)?.assets_delta.token ?? null;
+  const decimal = best.assets_delta.native.replace(/^-/, '');
+  const raw = token?.decimals != null ? decimalToBigInt(decimal, token.decimals) : null;
+  return { decimal, raw, token };
+}
+
+/**
+ * Pure stitcher: folds raw activity rows into `ActivityFlow`s. Rows may be in
+ * any order and may span multiple vaults; async lifecycles are paired by
+ * `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 flows: ActivityFlow[] = [];
+  for (const group of groups.values()) {
+    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;
+    const isAsync = group.some((r) => r.request_hash != null);
+
+    let status: ActivityFlowStatus;
+    if (!terminalRow) status = 'pending';
+    else if (REFUNDED_TYPES.has(terminalRow.type)) status = 'refunded';
+    else status = 'settled';
+
+    let sharesMagnitude = 0n;
+    for (const row of group) {
+      const shares = abs(sharesToBigInt(row.shares_delta));
+      if (shares > sharesMagnitude) sharesMagnitude = shares;
+    }
+
+    flows.push({
+      kind: flowKind((terminalRow ?? pendingRow ?? group[0]).type),
+      status,
+      vaultId: group[0].vault_id,
+      requestHash: group[0].request_hash ?? null,
+      requestedAt: pendingRow
+        ? new Date(pendingRow.block_timestamp * 1000)
+        : isAsync
+          ? null
+          : new Date(group[0].block_timestamp * 1000),
+      settledAt: terminalRow ? new Date(terminalRow.block_timestamp * 1000) : null,
+      assets: toAssetAmount(group),
+      shares: sharesMagnitude,
+      txHashes: [...new Set(group.map((r) => r.tx_hash))],
+    });
+  }
+
+  return flows.sort((a, b) => {
+    const aAt = (a.settledAt ?? a.requestedAt)?.getTime() ?? 0;
+    const bAt = (b.settledAt ?? b.requestedAt)?.getTime() ?? 0;
+    return bAt - aAt;
+  });
+}
+
+export interface ActivityFlowsOptions extends Pick<ActivityOptions, 'vaultId' | 'limit'> {
+  /** Stop paginating once this many rows have been fetched. Defaults to 1000. */
+  maxRows?: number;
+}
+
+/**
+ * Fetches the wallet's activity log and stitches it into lifecycle-aware
+ * flows — the replacement for scanning vault event logs over RPC.
+ *
+ * ```ts
+ * const flows = await getActivityFlows(client.api, wallet);
+ * const open = flows.filter((f) => f.status === 'pending');
+ * ```
+ */
+export async function getActivityFlows(
+  api: GauntletApi,
+  walletAddress: string,
+  options: ActivityFlowsOptions = {}
+): Promise<ActivityFlow[]> {
+  const maxRows = options.maxRows ?? 1000;
+  const rows: UserActivity[] = [];
+  for await (const row of api.activityRows(walletAddress, {
+    vaultId: options.vaultId,
+    // The API caps page size at 1000; request maxRows per page so the common
+    // case is a single round trip instead of ten default-100 pages.
+    limit: options.limit ?? Math.min(maxRows, 1000),
+    order: 'desc',
+  })) {
+    rows.push(row);
+    if (rows.length >= maxRows) break;
+  }
+  const flows = stitchActivityFlows(rows);
+  if (rows.length >= maxRows) {
+    // The window cut may have split an async lifecycle, keeping a terminal
+    // row whose request leg (the one carrying the amount) fell outside the
+    // window. Drop those flows rather than reporting zeroed amounts.
+    return flows.filter((f) => f.requestHash === null || f.requestedAt !== null);
+  }
+  return flows;
+}
+
+export interface WaitForSettlementOptions {
+  /** CAIP-10 vault id — narrows polling to one vault's activity. */
+  vaultId?: string;
+  /** Polling interval. Defaults to 5s. */
+  pollIntervalMs?: number;
+  /** Overall deadline. Defaults to 10 minutes. Throws `SettlementTimeoutError` on expiry. */
+  timeoutMs?: number;
+}
+
+/**
+ * Polls the activity log until the Aera async request identified by
+ * `requestHash` reaches a terminal state, and returns the settled or refunded
+ * flow. Use after submitting a `requestDeposit` / `requestRedeem` transaction.
+ */
+export async function waitForRequestSettlement(
+  api: GauntletApi,
+  walletAddress: string,
+  requestHash: string,
+  options: WaitForSettlementOptions = {}
+): Promise<ActivityFlow> {
+  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);
+    if (flow && flow.status !== 'pending') return flow;
+
+    if (Date.now() + pollIntervalMs > deadline) {
+      throw new SettlementTimeoutError(requestHash, timeoutMs);
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+  }
+}

package/src/api/caip.ts

@@ -0,0 +1,61 @@
+import type { GauntletClient } from '../client';
+import { VaultNotFoundError } from '../errors';
+import { resolveVault } from '../evm/vaults';
+import { InvalidCaipIdError } from './errors';
+
+/**
+ * The Gaia API identifies vaults as `"{chainId}:{address}"` with a lowercase
+ * address (a CAIP-10-style account id without the `eip155` namespace prefix).
+ */
+export interface ApiVaultId {
+  chainId: number;
+  /** Lowercase EVM address. */
+  address: string;
+}
+
+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() };
+}
+
+export function formatApiVaultId(chainId: number, address: string): string {
+  return `${chainId}:${address.toLowerCase()}`;
+}
+
+/**
+ * Resolves a manifest vault id (e.g. `VaultId.AeraUsdAlpha` / `'gtusda'`) to
+ * the Gaia API's CAIP-10 id for the vault's deployment on `chainId`.
+ *
+ * Deployment resolution is `resolveVault` — the same rules tx-building uses:
+ * single-deployment vaults resolve directly (a mismatched explicit `chainId`
+ * throws `ChainMismatchError`), multi-chain vaults default to Base when
+ * `chainId` is omitted.
+ */
+export async function apiVaultIdFromVaultId(
+  client: GauntletClient,
+  vaultId: string,
+  chainId?: number
+): Promise<string> {
+  const resolved = await resolveVault(client, vaultId, chainId);
+  if (!resolved) throw new VaultNotFoundError(vaultId, chainId);
+  return formatApiVaultId(resolved.vault.chainId, resolved.vault.vaultAddress);
+}
+
+/**
+ * Resolves a Gaia API CAIP-10 vault id back to the manifest vault id, or
+ * `undefined` when the vault is not in the bundled manifest (the API indexes
+ * more vaults than the manifest lists).
+ */
+export async function vaultIdFromApiVaultId(
+  client: GauntletClient,
+  apiVaultId: string
+): Promise<string | undefined> {
+  const { chainId, address } = parseApiVaultId(apiVaultId);
+  const manifest = await client.manifest;
+  return manifest.vaults.find((v) =>
+    v.deployments.some(
+      (d) => d.chain === 'evm' && d.chainId === chainId && d.vaultAddress.toLowerCase() === address
+    )
+  )?.vaultId;
+}