@gauntlet-xyz/sdk 0.0.1

package/manifest/vaults.json

@@ -0,0 +1,139 @@
+{
+  "version": "2026-03-24",
+  "vaults": [
+    {
+      "vaultId": "baseUsdcPrime",
+      "name": "Gauntlet USDC Prime",
+      "protocol": "morpho",
+      "strategy": "Prime Lending",
+      "deployments": [
+        {
+          "chain": "evm",
+          "chainId": 8453,
+          "vaultAddress": "0xeE8F4eC5672F09119b96Ab6fB59C27E1b7e44b61",
+          "vaultType": "single-depositor",
+          "depositMode": "sync",
+          "supplyToken": [
+            {
+              "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+              "symbol": "USDC",
+              "decimals": 6
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "vaultId": "ethUsdcPrime",
+      "name": "Gauntlet USDC Prime",
+      "protocol": "morpho",
+      "strategy": "Prime Lending",
+      "deployments": [
+        {
+          "chain": "evm",
+          "chainId": 1,
+          "vaultAddress": "0xdd0f28e19C1780eb6396170735D45153D261490d",
+          "vaultType": "single-depositor",
+          "depositMode": "sync",
+          "supplyToken": [
+            {
+              "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+              "symbol": "USDC",
+              "decimals": 6
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "vaultId": "gtusda",
+      "name": "Gauntlet USD Alpha",
+      "protocol": "aera",
+      "strategy": "Multi-strategy Stablecoin Yield",
+      "deployments": [
+        {
+          "chain": "evm",
+          "chainId": 8453,
+          "vaultAddress": "0x000000000001CdB57E58Fa75Fe420a0f4D6640D5",
+          "provisionerAddress": "0x18CF8d963E1a727F9bbF3AEffa0Bd04FB4dBdA07",
+          "vaultType": "multi-depositor",
+          "depositMode": "async",
+          "supplyToken": [
+            {
+              "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+              "symbol": "USDC",
+              "decimals": 6
+            }
+          ]
+        },
+        {
+          "chain": "evm",
+          "chainId": 1,
+          "vaultAddress": "0x3bd9248048df95db4fbd748c6cd99c1baa40bad0",
+          "provisionerAddress": "0x74C4A66CE4F4779B11E7c63D42e51EEef3A80D11",
+          "vaultType": "multi-depositor",
+          "depositMode": "async",
+          "supplyToken": [
+            {
+              "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+              "symbol": "USDC",
+              "decimals": 6
+            }
+          ]
+        },
+        {
+          "chain": "evm",
+          "chainId": 42161,
+          "vaultAddress": "0x000000001DC8bd45d7E7829fb1c969cbe4D0D1eC",
+          "provisionerAddress": "0xDd4a42603E6d8E515C3468789375A98c376821b3",
+          "vaultType": "multi-depositor",
+          "depositMode": "async",
+          "supplyToken": [
+            {
+              "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+              "symbol": "USDC",
+              "decimals": 6
+            }
+          ]
+        },
+        {
+          "chain": "evm",
+          "chainId": 10,
+          "vaultAddress": "0x000000001DC8bd45d7E7829fb1c969cbe4D0D1eC",
+          "provisionerAddress": "0xCC923371F0d3A9cA75d98E767Df9dE1cdf5799Ef",
+          "vaultType": "multi-depositor",
+          "depositMode": "async",
+          "supplyToken": [
+            {
+              "address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
+              "symbol": "USDC",
+              "decimals": 6
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "vaultId": "ethUsdcPrimeV2",
+      "name": "Gauntlet USDC Prime v2",
+      "protocol": "morpho",
+      "strategy": "Prime Lending v2",
+      "deployments": [
+        {
+          "chain": "evm",
+          "chainId": 1,
+          "vaultAddress": "0x8c106EEDAd96553e64287A5A6839c3Cc78afA3D0",
+          "vaultType": "single-depositor",
+          "depositMode": "sync",
+          "supplyToken": [
+            {
+              "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+              "symbol": "USDC",
+              "decimals": 6
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@gauntlet-xyz/sdk",
+  "version": "0.0.1",
+  "description": "Official Gauntlet SDK for vault deposits, withdrawals, and attribution",
+  "license": "MIT",
+  "keywords": [
+    "gauntlet",
+    "defi",
+    "vault",
+    "aera",
+    "evm",
+    "viem",
+    "deposit",
+    "withdraw",
+    "sdk"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./evm": {
+      "types": "./dist/evm/index.d.ts",
+      "import": "./dist/evm/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "manifest"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "dev": "tsc --project tsconfig.json --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"
+  },
+  "peerDependencies": {
+    "viem": ">=2.0.0"
+  },
+  "devDependencies": {
+    "@next/eslint-plugin-next": "13.1.1",
+    "@types/node": "^18.15.11",
+    "@viem/anvil": "^0.0.10",
+    "echo-cli": "^2.0.0",
+    "eslint": "^8.57.0",
+    "typescript": "^5.5.4",
+    "viem": "2.30.1",
+    "vitest": "^4.1.2"
+  },
+  "packageManager": "yarn@4.3.1"
+}

package/src/attribution/erc8021.ts

@@ -0,0 +1,14 @@
+import { toHex, type Hex } from 'viem';
+
+const ERC8021_PREFIX = '8021' as const;
+
+/**
+ * Encode an ERC-8021 builder code as a calldata suffix.
+ * Format: "8021" marker + utf8-encoded builder code
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-8021
+ */
+export function encodeBuilderCode(builderCode: string): Hex {
+  const codeHex = toHex(builderCode).slice(2); // remove 0x prefix
+  return `0x${ERC8021_PREFIX}${codeHex}` as Hex;
+}

package/src/attribution/index.ts

@@ -0,0 +1,62 @@
+import { Address, encodeFunctionData, type Hex } from 'viem';
+import { encodeBuilderCode } from './erc8021';
+import { AttributionMode, GauntletClient } from '../client';
+import { UnimplementedFeatureError } from '../errors';
+import { TxStep } from '../evm/adapters/types';
+export { encodeBuilderCode } from './erc8021';
+
+export type PreparedPayloadWithAttribution = {
+  type: string;
+  to: Address;
+  data: Hex;
+  account?: Address;
+};
+
+export type PreparedTx = {
+  payload: PreparedPayloadWithAttribution;
+  tx: TxStep;
+};
+
+/**
+ * Build the full attribution suffix to append to transaction calldata.
+ *
+ * PUBLIC:  ERC-8021 builder code only — `0x8021{builderCode utf8}`, or `0x` if no builderCode.
+ * ENCODED: Requests a sourceId from the Gauntlet API with builder code as an arg and encodes that.
+ * PRIVATE: Generates a random salt and posts it to the Gauntlet API.
+ *
+ */
+export async function buildAttribution(client: GauntletClient): Promise<Hex> {
+  switch (client.attributionMode) {
+    case AttributionMode.PUBLIC:
+      return client.builderCode ? encodeBuilderCode(client.builderCode) : '0x';
+    case AttributionMode.ENCODED:
+      throw new UnimplementedFeatureError('AttributionMode.ENCODED');
+    case AttributionMode.PRIVATE:
+      throw new UnimplementedFeatureError('AttributionMode.PRIVATE');
+  }
+}
+
+export async function encodeTransactionWithAttribution(
+  client: GauntletClient,
+  transaction: TxStep
+): Promise<PreparedTx> {
+  const customAttribution = await buildAttribution(client);
+  const encodedTx = encodeFunctionData({
+    abi: transaction.abi,
+    functionName: transaction.functionName,
+    args: transaction.args,
+  });
+  const encodedTxWithAttribution = `${encodedTx}${customAttribution.replace('0x', '')}` as Hex;
+  return {
+    payload: {
+      type: transaction.type,
+      account: transaction.account,
+      to: transaction.address,
+      data: encodedTxWithAttribution,
+    },
+    tx: {
+      ...transaction,
+      attribution: customAttribution,
+    },
+  };
+}

package/src/client.ts

@@ -0,0 +1,95 @@
+import { type PublicClient, type WalletClient } from 'viem';
+import bundledManifest from '../manifest/vaults.json';
+import { RpcNotConfiguredError, UnimplementedFeatureError } from './errors';
+import type { VaultManifest } from './evm/types';
+import { base } from 'viem/chains';
+
+/**
+ * Controls how builder attribution is appended to transactions.
+ *
+ * - `PUBLIC` – attribution is sent as plain calldata (default).
+ * - `ENCODED` – attribution is encoded using ERC-8021 with a builder code fetched from the API.
+ * - `PRIVATE` – no attribution data is appended.
+ */
+export enum AttributionMode {
+  PUBLIC = 'public',
+  ENCODED = 'encoded',
+  PRIVATE = 'private',
+}
+
+export type ChainId = string | number;
+
+export interface GauntletClientConfig {
+  apiKey?: string;
+  /** Map of chainId → PublicClient, e.g. { [base.id]: createPublicClient(...) } */
+  evmClients?: Record<ChainId, PublicClient>;
+  attributionMode?: AttributionMode;
+  builderCode?: string;
+  /** Viem WalletClient for signing transactions. */
+  wallet?: WalletClient;
+}
+
+/**
+ * Main entry point for the Gauntlet SDK.
+ *
+ * Holds configuration (RPC clients, wallet, attribution mode) and exposes helpers
+ * for reading the vault manifest. Pass an instance of this class to every SDK
+ * function (e.g. `getDepositTx`, `getWithdrawTx`, `getVaults`).
+ *
+ * @example
+ * ```ts
+ * import { createPublicClient, createWalletClient, http } from 'viem';
+ * import { base } from 'viem/chains';
+ * import { GauntletClient, AttributionMode } from '@gauntlet-xyz/sdk';
+ *
+ * const wallet = createWalletClient({
+ *  account: privateKeyToAccount('0x...'), // or other account source
+ *  chain: base,
+ *  transport: http()
+ * })
+ *
+ * const client = new GauntletClient({
+ *   evmClients: { [base.id]: createPublicClient({ chain: base, transport: http() }) },
+ *   wallet,
+ *   attributionMode: AttributionMode.PUBLIC,
+ * });
+ * ```
+ */
+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;
+
+  private _manifest: VaultManifest = bundledManifest as VaultManifest;
+
+  constructor(config: GauntletClientConfig) {
+    this.apiKey = config.apiKey;
+    this.evmClients = config.evmClients ?? {};
+    this.attributionMode = config.attributionMode ?? AttributionMode.PUBLIC;
+    this.builderCode = config.builderCode;
+    this.wallet = config.wallet;
+  }
+
+  get manifest(): Promise<VaultManifest> {
+    return Promise.resolve(this._manifest);
+  }
+
+  setManifest(manifest: VaultManifest): void {
+    this._manifest = manifest;
+  }
+
+  getPublicClient(chainId: ChainId = base.id): PublicClient {
+    const client = this.evmClients[chainId];
+    if (!client) throw new RpcNotConfiguredError(chainId);
+    return client;
+  }
+
+  // Will be used for encoded attribution
+  // Will use apiKey to get a builder ID from core api
+  async getSourceId(): Promise<string> {
+    throw new UnimplementedFeatureError('getSourceId');
+  }
+}

package/src/errors.ts

@@ -0,0 +1,135 @@
+import { ChainId } from './client';
+
+export class GauntletSDKError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'GauntletSDKError';
+  }
+}
+
+export class VaultNotFoundError extends GauntletSDKError {
+  readonly vaultId: string;
+  readonly chainId?: ChainId;
+
+  constructor(vaultId: string, chainId?: ChainId) {
+    const msg = chainId
+      ? `Vault "${vaultId}" not found on chainId "${chainId}"`
+      : `Vault "${vaultId}" not found`;
+    super(msg);
+    this.name = 'VaultNotFoundError';
+    this.vaultId = vaultId;
+    this.chainId = chainId;
+  }
+}
+
+export class UnsupportedAssetError extends GauntletSDKError {
+  readonly asset: string;
+  readonly vaultId: string;
+
+  constructor(asset: string, vaultId: string) {
+    super(`Asset "${asset}" is not supported by vault "${vaultId}"`);
+    this.name = 'UnsupportedAssetError';
+    this.asset = asset;
+    this.vaultId = vaultId;
+  }
+}
+
+export class ChainMismatchError extends GauntletSDKError {
+  readonly expected: string;
+  readonly received: string;
+
+  constructor(expected: string, received: string) {
+    super(`Chain mismatch: expected "${expected}", received "${received}"`);
+    this.name = 'ChainMismatchError';
+    this.expected = expected;
+    this.received = received;
+  }
+}
+
+export class UnsupportedDepositModeError extends GauntletSDKError {
+  readonly vaultId: string;
+  readonly requested: 'sync' | 'async';
+  readonly available: string;
+
+  constructor(vaultId: string, requested: 'sync' | 'async', available: string) {
+    super(`Vault "${vaultId}" does not support ${requested} deposits (available: ${available})`);
+    this.name = 'UnsupportedDepositModeError';
+    this.vaultId = vaultId;
+    this.requested = requested;
+    this.available = available;
+  }
+}
+
+export class RpcNotConfiguredError extends GauntletSDKError {
+  readonly chainId: ChainId;
+
+  constructor(chainId: ChainId) {
+    super(`No client configured for chainId "${chainId}"`);
+    this.name = 'RpcNotConfiguredError';
+    this.chainId = chainId;
+  }
+}
+
+export class AccountRequiredError extends GauntletSDKError {
+  constructor() {
+    super('No account specified. Provide a wallet in the client config.');
+    this.name = 'AccountRequiredError';
+  }
+}
+
+export class UnsupportedProtocolError extends GauntletSDKError {
+  readonly protocol: string;
+
+  constructor(protocol: string) {
+    super(`Unsupported protocol: "${protocol}"`);
+    this.name = 'UnsupportedProtocolError';
+    this.protocol = protocol;
+  }
+}
+
+export class InvalidWithdrawParamsError extends GauntletSDKError {
+  constructor() {
+    super('Withdraw requires exactly one of: shares, amount, or all');
+    this.name = 'InvalidWithdrawParamsError';
+  }
+}
+
+export class UnimplementedFeatureError extends GauntletSDKError {
+  readonly feature: string;
+
+  constructor(feature: string) {
+    super(`Feature not yet implemented: "${feature}"`);
+    this.name = 'UnimplementedFeatureError';
+    this.feature = feature;
+  }
+}
+
+export class UnsupportedFeatureError extends GauntletSDKError {
+  readonly feature: string;
+
+  constructor(feature: string) {
+    super(`Feature not supported: "${feature}"`);
+    this.name = 'UnimplementedFeatureError';
+    this.feature = feature;
+  }
+}
+
+export class UnitConversionError extends GauntletSDKError {
+  readonly vaultAddress: string;
+
+  constructor(vaultAddress: string) {
+    super(`Failed to convert token units for vault "${vaultAddress}": fee calculator unavailable`);
+    this.name = 'UnitConversionError';
+    this.vaultAddress = vaultAddress;
+  }
+}
+
+export class InvalidSlippageBPSError extends GauntletSDKError {
+  readonly slippage: number;
+
+  constructor(slippage: number) {
+    super(`Slippage not in range of 10000-0; argumet passed: ${slippage}`);
+    this.name = 'IncorrectArgument';
+    this.slippage = slippage;
+  }
+}

package/src/evm/abis/erc20.ts

@@ -0,0 +1,29 @@
+export const erc20Abi = [
+  {
+    type: 'function',
+    name: 'approve',
+    inputs: [
+      { name: 'spender', type: 'address' },
+      { name: 'amount', type: 'uint256' },
+    ],
+    outputs: [{ type: 'bool' }],
+    stateMutability: 'nonpayable',
+  },
+  {
+    type: 'function',
+    name: 'allowance',
+    inputs: [
+      { name: 'owner', type: 'address' },
+      { name: 'spender', type: 'address' },
+    ],
+    outputs: [{ type: 'uint256' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'balanceOf',
+    inputs: [{ name: 'account', type: 'address' }],
+    outputs: [{ type: 'uint256' }],
+    stateMutability: 'view',
+  },
+] as const;

package/src/evm/abis/erc4626.ts

@@ -0,0 +1,69 @@
+export const erc4626Abi = [
+  {
+    type: 'function',
+    name: 'deposit',
+    inputs: [
+      { name: 'assets', type: 'uint256' },
+      { name: 'receiver', type: 'address' },
+    ],
+    outputs: [{ type: 'uint256' }],
+    stateMutability: 'nonpayable',
+  },
+  {
+    type: 'function',
+    name: 'redeem',
+    inputs: [
+      { name: 'shares', type: 'uint256' },
+      { name: 'receiver', type: 'address' },
+      { name: 'owner', type: 'address' },
+    ],
+    outputs: [{ type: 'uint256' }],
+    stateMutability: 'nonpayable',
+  },
+  {
+    type: 'function',
+    name: 'convertToShares',
+    inputs: [{ name: 'assets', type: 'uint256' }],
+    outputs: [{ type: 'uint256' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'convertToAssets',
+    inputs: [{ name: 'shares', type: 'uint256' }],
+    outputs: [{ type: 'uint256' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'balanceOf',
+    inputs: [{ name: 'account', type: 'address' }],
+    outputs: [{ type: 'uint256' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'maxDeposit',
+    inputs: [{ name: 'receiver', type: 'address' }],
+    outputs: [{ type: 'uint256' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'maxRedeem',
+    inputs: [{ name: 'owner', type: 'address' }],
+    outputs: [{ type: 'uint256' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'withdraw',
+    inputs: [
+      { name: 'assets', type: 'uint256' },
+      { name: 'receiver', type: 'address' },
+      { name: 'owner', type: 'address' },
+    ],
+    outputs: [{ type: 'uint256' }],
+    stateMutability: 'nonpayable',
+  },
+] as const;