@eth-optimism/actions-sdk 0.4.0 → 0.6.0

package/src/core/error/errors.ts

@@ -1,27 +1,287 @@
-import type { TransactionReceipt } from 'viem'
+import { BaseError } from 'viem'
 
 /**
- * Error for a transaction that was included on-chain but reverted
- * @description Thrown when a transaction makes it into a block (i.e. has a
- * confirmed receipt) yet the EVM execution failed. The full
- * {@link TransactionReceipt | transaction receipt} is attached for
- * post-mortem analysis (status, logs, gas usage, etc.).
+ * Abstract base class for all Actions SDK errors.
+ * Extends viem's BaseError so callers can use instanceof narrowing
+ * and structured metaMessages alongside the shortMessage.
  */
-export class TransactionConfirmedButRevertedError extends Error {
-  /** Full receipt returned by the node for the reverted transaction */
-  receipt: TransactionReceipt
-
-  /**
-   * Create an instance of TransactionConfirmedButRevertedError
-   * @param message - Human-readable description of the failure
-   * @param receipt - Confirmed transaction receipt indicating a revert
-   */
-  constructor(message: string, receipt: TransactionReceipt) {
-    if (!message || typeof message !== 'string') {
-      throw new Error('"message" must be a nonempty string.')
-    }
-
-    super(message)
-    this.receipt = receipt
+export abstract class ActionsError extends BaseError {}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Chain / Network
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class ChainNotSupportedError extends ActionsError {
+  override name = 'ChainNotSupportedError' as const
+  chainId: number
+  supportedChainIds: readonly number[]
+
+  constructor(params: {
+    chainId: number
+    supportedChainIds?: readonly number[]
+  }) {
+    super(`Chain ${params.chainId} is not supported`, {
+      metaMessages: params.supportedChainIds?.length
+        ? [`Supported chains: ${params.supportedChainIds.join(', ')}`]
+        : undefined,
+    })
+    this.chainId = params.chainId
+    this.supportedChainIds = params.supportedChainIds ?? []
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Market / Provider
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class MarketNotAllowedError extends ActionsError {
+  override name = 'MarketNotAllowedError' as const
+  chainId: number
+  assetInSymbol?: string
+  assetOutSymbol?: string
+  address?: string
+
+  constructor(params: {
+    chainId: number
+    assetInSymbol?: string
+    assetOutSymbol?: string
+    address?: string
+    reason?: string
+  }) {
+    const pair =
+      params.assetInSymbol && params.assetOutSymbol
+        ? `${params.assetInSymbol}/${params.assetOutSymbol}`
+        : (params.address ?? 'unknown')
+    super(`Market ${pair} not allowed on chain ${params.chainId}`, {
+      metaMessages: params.reason ? [params.reason] : undefined,
+    })
+    this.chainId = params.chainId
+    this.assetInSymbol = params.assetInSymbol
+    this.assetOutSymbol = params.assetOutSymbol
+    this.address = params.address
+  }
+}
+
+export class MarketNotFoundError extends ActionsError {
+  override name = 'MarketNotFoundError' as const
+  chainId: number
+  poolId?: string
+
+  constructor(params: { chainId: number; poolId?: string; reason?: string }) {
+    super(
+      params.poolId
+        ? `Market with poolId ${params.poolId} not found on chain ${params.chainId}`
+        : `Market not found on chain ${params.chainId}`,
+      { metaMessages: params.reason ? [params.reason] : undefined },
+    )
+    this.chainId = params.chainId
+    this.poolId = params.poolId
+  }
+}
+
+export class ProviderNotConfiguredError extends ActionsError {
+  override name = 'ProviderNotConfiguredError' as const
+  provider: string
+
+  constructor(params: { provider: string; details?: string }) {
+    super(`A '${params.provider}' provider is not configured`, {
+      metaMessages: params.details ? [params.details] : undefined,
+    })
+    this.provider = params.provider
+  }
+}
+
+export class MarketIdRequiredError extends ActionsError {
+  override name = 'MarketIdRequiredError' as const
+
+  constructor(details?: string) {
+    super('marketId is required', {
+      metaMessages: details ? [details] : undefined,
+    })
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Amount / Swap Parameters
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class AmountRequiredError extends ActionsError {
+  override name = 'AmountRequiredError' as const
+
+  constructor() {
+    super('Either amountIn or amountOut must be provided')
+  }
+}
+
+export class InvalidAmountError extends ActionsError {
+  override name = 'InvalidAmountError' as const
+  amount: number
+
+  constructor(amount: number) {
+    super('Amount must be positive', {
+      metaMessages: [`Received: ${amount}`],
+    })
+    this.amount = amount
+  }
+}
+
+export class ConflictingAmountsError extends ActionsError {
+  override name = 'ConflictingAmountsError' as const
+
+  constructor() {
+    super('Provide either amountIn or amountOut, not both')
+  }
+}
+
+export class SameAssetError extends ActionsError {
+  override name = 'SameAssetError' as const
+  symbol: string
+
+  constructor(symbol: string) {
+    super('Cannot swap an asset for itself', {
+      metaMessages: [`Asset: ${symbol}`],
+    })
+    this.symbol = symbol
+  }
+}
+
+export class QuoteExpiredError extends ActionsError {
+  override name = 'QuoteExpiredError' as const
+  expiresAt: number
+  currentTime: number
+
+  constructor(params: { expiresAt: number; currentTime: number }) {
+    super('Quote expired', {
+      metaMessages: [
+        `Expired at: ${params.expiresAt}`,
+        `Current time: ${params.currentTime}`,
+      ],
+    })
+    this.expiresAt = params.expiresAt
+    this.currentTime = params.currentTime
+  }
+}
+
+export class ExactOutputNotSupportedError extends ActionsError {
+  override name = 'ExactOutputNotSupportedError' as const
+  provider: string
+
+  constructor(provider: string) {
+    super(`${provider} does not support exact-output swaps`, {
+      metaMessages: ['Provide amountIn instead of amountOut'],
+    })
+    this.provider = provider
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Address
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class AddressRequiredError extends ActionsError {
+  override name = 'AddressRequiredError' as const
+  label: string
+
+  constructor(label: string) {
+    super(`${label} is required`)
+    this.label = label
+  }
+}
+
+export class ZeroAddressError extends ActionsError {
+  override name = 'ZeroAddressError' as const
+  label: string
+  address?: string
+
+  constructor(label: string, address?: string) {
+    super(`${label} cannot be the zero address`, {
+      metaMessages: address ? [`Address: ${address}`] : undefined,
+    })
+    this.label = label
+    this.address = address
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Slippage
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class SlippageOutOfRangeError extends ActionsError {
+  override name = 'SlippageOutOfRangeError' as const
+  slippage: number
+  maxSlippage: number
+
+  constructor(slippage: number, maxSlippage: number) {
+    super(`Slippage ${slippage} is out of range`, {
+      metaMessages: [`Allowed range: [0, ${maxSlippage * 100}%]`],
+    })
+    this.slippage = slippage
+    this.maxSlippage = maxSlippage
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Asset
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class AssetNotSupportedOnChainError extends ActionsError {
+  override name = 'AssetNotSupportedOnChainError' as const
+  symbol: string
+  chainId: number
+
+  constructor(symbol: string, chainId: number) {
+    super(`Asset ${symbol} is not supported on chain ${chainId}`)
+    this.symbol = symbol
+    this.chainId = chainId
+  }
+}
+
+export class NativeAssetAddressError extends ActionsError {
+  override name = 'NativeAssetAddressError' as const
+  symbol: string
+
+  constructor(symbol: string) {
+    super(`${symbol} is a native asset and has no contract address`)
+    this.symbol = symbol
+  }
+}
+
+export class AssetMetadataRequiredError extends ActionsError {
+  override name = 'AssetMetadataRequiredError' as const
+  context?: string
+
+  constructor(context?: string) {
+    super('Asset metadata is required', {
+      metaMessages: context ? [context] : undefined,
+    })
+    this.context = context
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Generic input validation
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Thrown when a caller-supplied parameter does not match the expected shape
+ * (wrong type, empty when non-empty is required, etc.). The `expected` string
+ * documents the type signature the caller should have produced.
+ */
+export class InvalidParamsError extends ActionsError {
+  override name = 'InvalidParamsError' as const
+  param: string
+  expected: string
+  received?: string
+
+  constructor(params: { param: string; expected: string; received?: string }) {
+    super(`Invalid params: ${params.param}`, {
+      metaMessages: [
+        `Expected: ${params.expected}`,
+        ...(params.received ? [`Received: ${params.received}`] : []),
+      ],
+    })
+    this.param = params.param
+    this.expected = params.expected
+    this.received = params.received
   }
 }

package/src/index.ts

@@ -1,4 +1,14 @@
 export type { Actions } from '@/actions.js'
+export { LendProvider, MorphoLendProvider } from '@/actions/lend/index.js'
+export {
+  SwapProvider,
+  type UniswapMarketConfig,
+  UniswapSwapProvider,
+  type UniswapSwapProviderConfig,
+  type VelodromeMarketConfig,
+  VelodromeSwapProvider,
+  type VelodromeSwapProviderConfig,
+} from '@/actions/swap/index.js'
 export {
   AAVE,
   ARB,
@@ -52,16 +62,19 @@ export {
   type SupportedChainId,
 } from '@/constants/supportedChains.js'
 export * from '@/core/error/errors.js'
-export { LendProvider, MorphoLendProvider } from '@/lend/index.js'
 export {
-  SwapProvider,
-  type UniswapMarketConfig,
-  UniswapSwapProvider,
-  type UniswapSwapProviderConfig,
-  type VelodromeMarketConfig,
-  VelodromeSwapProvider,
-  type VelodromeSwapProviderConfig,
-} from '@/swap/index.js'
+  type EnsInfo,
+  EnsNamespace,
+  EnsNotConfiguredError,
+  EnsResolutionError,
+  EnsRpcError,
+  type NameServiceProvider,
+} from '@/services/nameservices/ens/index.js'
+export {
+  type EnsName,
+  isEnsName,
+  resolveAddress,
+} from '@/services/nameservices/ens/utils.js'
 export type {
   ActionsConfig,
   ApyBreakdown,
@@ -74,7 +87,6 @@ export type {
   LendMarketMetadata,
   LendMarketPosition,
   LendMarketSupply,
-  LendOptions,
   LendProviderConfig,
   LendTransaction,
   LendTransactionReceipt,
@@ -95,10 +107,13 @@ export type {
   SwapTransaction,
   TokenBalance,
   TransactionData,
+  TransactionOptions,
   UserOperationTransactionReceipt,
   WalletConfig,
   WalletSwapParams,
 } from '@/types/index.js'
 export { getAssetAddress, isAssetSupportedOnChain } from '@/utils/assets.js'
+export { serializeBigInt } from '@/utils/serializers.js'
+export * from '@/wallet/core/error/errors.js'
 export { Wallet } from '@/wallet/core/wallets/abstract/Wallet.js'
 export { SmartWallet } from '@/wallet/core/wallets/smart/abstract/SmartWallet.js'

package/src/services/ChainManager.ts

@@ -13,6 +13,7 @@ import type { BundlerClient, SmartAccount } from 'viem/account-abstraction'
 import { createBundlerClient } from 'viem/account-abstraction'
 
 import type { SupportedChainId } from '@/constants/supportedChains.js'
+import { ChainNotSupportedError } from '@/core/error/errors.js'
 import type { ChainConfig } from '@/types/chain.js'
 
 /**
@@ -44,11 +45,24 @@ export class ChainManager {
   getPublicClient(chainId: SupportedChainId): PublicClient {
     const client = this.publicClients.get(chainId)
     if (!client) {
-      throw new Error(`No public client configured for chain ID: ${chainId}`)
+      throw new ChainNotSupportedError({
+        chainId,
+        supportedChainIds: this.getSupportedChains(),
+      })
     }
     return client
   }
 
+  /**
+   * Get public client for a specific chain, or undefined if not configured.
+   * Use this when the chain is optional (e.g. mainnet for ENS resolution).
+   * @param chainId - The chain ID to retrieve the public client for
+   * @returns PublicClient instance, or undefined if not configured
+   */
+  tryGetPublicClient(chainId: SupportedChainId): PublicClient | undefined {
+    return this.publicClients.get(chainId)
+  }
+
   /**
    * Get bundler client for a specific chain
    * @param chainId - The chain ID to retrieve the bundler client for
@@ -63,7 +77,10 @@ export class ChainManager {
     const chainConfig = this.getChainConfig(chainId)
     const bundlerConfig = chainConfig.bundler
     if (!bundlerConfig) {
-      throw new Error(`No bundler configured for chain ID: ${chainId}`)
+      throw new ChainNotSupportedError({
+        chainId,
+        supportedChainIds: this.getSupportedChains(),
+      })
     }
     if (bundlerConfig.type === 'pimlico') {
       return this.getPimlicoBundlerClient(
@@ -74,7 +91,10 @@ export class ChainManager {
     }
     const bundlerUrl = this.getBundlerUrl(chainId)
     if (!bundlerUrl) {
-      throw new Error(`No bundler URL configured for chain ID: ${chainId}`)
+      throw new ChainNotSupportedError({
+        chainId,
+        supportedChainIds: this.getSupportedChains(),
+      })
     }
     const client = createPublicClient({
       chain: this.getChain(chainId),
@@ -108,7 +128,10 @@ export class ChainManager {
   getBundlerUrl(chainId: SupportedChainId): string | undefined {
     const chainConfig = this.getChainConfig(chainId)
     if (!chainConfig.bundler) {
-      throw new Error(`No bundler configured for chain ID: ${chainId}`)
+      throw new ChainNotSupportedError({
+        chainId,
+        supportedChainIds: this.getSupportedChains(),
+      })
     }
     return chainConfig.bundler.url
   }
@@ -157,12 +180,13 @@ export class ChainManager {
     for (const chainConfig of chains) {
       const chain = chainById[chainConfig.chainId]
       if (!chain) {
-        throw new Error(`Chain not found for ID: ${chainConfig.chainId}`)
+        throw new ChainNotSupportedError({ chainId: chainConfig.chainId })
       }
       if (clients.has(chainConfig.chainId)) {
-        throw new Error(
-          `Public client already configured for chain ID: ${chainConfig.chainId}`,
-        )
+        throw new ChainNotSupportedError({
+          chainId: chainConfig.chainId,
+          supportedChainIds: Array.from(clients.keys()),
+        })
       }
       const client = createPublicClient({
         chain,
@@ -183,7 +207,10 @@ export class ChainManager {
   private getChainConfig(chainId: SupportedChainId): ChainConfig {
     const chainConfig = this.chainConfigs.find((c) => c.chainId === chainId)
     if (!chainConfig) {
-      throw new Error(`No chain config found for chain ID: ${chainId}`)
+      throw new ChainNotSupportedError({
+        chainId,
+        supportedChainIds: this.getSupportedChains(),
+      })
     }
     return chainConfig
   }

package/src/services/__mocks__/MockChainManager.ts

@@ -21,6 +21,9 @@ export class MockChainManager {
   public getPublicClient: MockedFunction<
     (chainId: SupportedChainId) => PublicClient
   >
+  public tryGetPublicClient: MockedFunction<
+    (chainId: SupportedChainId) => PublicClient | undefined
+  >
   public getBundlerClient: MockedFunction<
     (chainId: SupportedChainId, account: SmartAccount) => BundlerClient
   >
@@ -54,6 +57,11 @@ export class MockChainManager {
         }
         return client
       })
+    this.tryGetPublicClient = vi
+      .fn()
+      .mockImplementation((chainId: SupportedChainId) => {
+        return this.publicClients.get(chainId)
+      })
     this.getBundlerClient = vi
       .fn()
       .mockImplementation((chainId: SupportedChainId) => {

package/src/services/{ChainManager.spec.ts → __tests__/ChainManager.spec.ts}

@@ -90,7 +90,7 @@ describe('ChainManager', () => {
       ]
 
       expect(() => new ChainManager(invalidChainConfigs)).toThrow(
-        'Chain not found for ID: 99999',
+        'Chain 99999 is not supported',
       )
     })
 
@@ -100,7 +100,7 @@ describe('ChainManager', () => {
         { chainId: unichain.id, rpcUrls: ['https://another.rpc'] },
       ]
       expect(() => new ChainManager(multiChainConfigs)).toThrow(
-        `Public client already configured for chain ID: ${unichain.id}`,
+        `Chain ${unichain.id} is not supported`,
       )
     })
   })
@@ -117,7 +117,7 @@ describe('ChainManager', () => {
       const unsupportedChainId = 999 as unknown as SupportedChainId
 
       expect(() => chainManager.getPublicClient(unsupportedChainId)).toThrow(
-        'No public client configured for chain ID: 999',
+        'Chain 999 is not supported',
       )
     })
   })
@@ -183,7 +183,7 @@ describe('ChainManager', () => {
 
       expect(() =>
         chainManager.getTransportForChain(unsupportedChainId),
-      ).toThrow('No chain config found for chain ID: 999')
+      ).toThrow('Chain 999 is not supported')
     })
   })
 
@@ -306,7 +306,7 @@ describe('ChainManager', () => {
       const mgr = new ChainManager(configs)
 
       expect(() => mgr.getBundlerClient(unichain.id, mockAccount)).toThrow(
-        `No bundler configured for chain ID: ${unichain.id}`,
+        `Chain ${unichain.id} is not supported`,
       )
     })
 
@@ -325,7 +325,7 @@ describe('ChainManager', () => {
       const mgr = new ChainManager(configs)
 
       expect(() => mgr.getBundlerClient(unichain.id, mockAccount)).toThrow(
-        `No bundler URL configured for chain ID: ${unichain.id}`,
+        `Chain ${unichain.id} is not supported`,
       )
     })
   })

package/src/services/{tokenBalance.spec.ts → __tests__/tokenBalance.spec.ts}

@@ -1,5 +1,5 @@
 import type { Address } from 'viem'
-import { unichain } from 'viem/chains'
+import { base, optimism, unichain } from 'viem/chains'
 import { beforeEach, describe, expect, it } from 'vitest'
 
 import { MockUSDCAsset } from '@/__mocks__/MockAssets.js'
@@ -20,6 +20,12 @@ describe('TokenBalance', () => {
     }) as any
   })
 
+  const multiChainManager = (): ChainManager =>
+    new MockChainManager({
+      supportedChains: [optimism.id, base.id, unichain.id],
+      defaultBalance: 1000000n,
+    }) as unknown as ChainManager
+
   describe('fetchBalance', () => {
     it('should fetch token balance across supported chains', async () => {
       const balance = await fetchERC20Balance(
@@ -85,5 +91,54 @@ describe('TokenBalance', () => {
         },
       })
     })
+
+    it('queries only the requested chains when chainIds is provided', async () => {
+      const cm = multiChainManager()
+
+      const balance = await fetchETHBalance(cm, walletAddress, {
+        chainIds: [base.id],
+      })
+
+      expect(balance.chains).toEqual({
+        [base.id]: { balance: 0.000000000001, balanceRaw: 1000000n },
+      })
+      expect(balance.totalBalanceRaw).toBe(1000000n)
+      expect(cm.getPublicClient).toHaveBeenCalledTimes(1)
+      expect(cm.getPublicClient).toHaveBeenCalledWith(base.id)
+    })
+  })
+
+  describe('fetchERC20Balance with chainIds filter', () => {
+    it('queries only the requested chains', async () => {
+      const cm = multiChainManager()
+
+      const balance = await fetchERC20Balance(
+        cm,
+        walletAddress,
+        MockUSDCAsset,
+        { chainIds: [optimism.id, base.id] },
+      )
+
+      expect(Object.keys(balance.chains).map(Number).sort()).toEqual(
+        [optimism.id, base.id].sort(),
+      )
+      expect(balance.totalBalanceRaw).toBe(2000000n)
+    })
+
+    it('silently skips requested chains where the asset has no address', async () => {
+      const cm = multiChainManager()
+      const opOnly: Asset = {
+        ...MockUSDCAsset,
+        address: { [optimism.id]: MockUSDCAsset.address[optimism.id] } as any,
+      }
+
+      const balance = await fetchERC20Balance(cm, walletAddress, opOnly, {
+        chainIds: [optimism.id, base.id],
+      })
+
+      expect(balance.chains).toEqual({
+        [optimism.id]: { balance: 1, balanceRaw: 1000000n },
+      })
+    })
   })
 })