@eth-optimism/actions-sdk 0.5.0 → 0.7.0

package/src/core/error/__tests__/errors.test.ts

@@ -0,0 +1,236 @@
+import { BaseError } from 'viem'
+import { describe, expect, it } from 'vitest'
+
+import {
+  ActionsError,
+  AddressRequiredError,
+  AmountRequiredError,
+  AssetMetadataRequiredError,
+  AssetNotSupportedOnChainError,
+  ChainNotSupportedError,
+  ConflictingAmountsError,
+  ExactOutputNotSupportedError,
+  InvalidAmountError,
+  InvalidParamsError,
+  MarketIdRequiredError,
+  MarketNotAllowedError,
+  MarketNotFoundError,
+  NativeAssetAddressError,
+  ProviderNotConfiguredError,
+  QuoteExpiredError,
+  SameAssetError,
+  SlippageOutOfRangeError,
+  ZeroAddressError,
+} from '@/core/error/errors.js'
+
+describe('ActionsError hierarchy', () => {
+  it('ChainNotSupportedError', () => {
+    const err = new ChainNotSupportedError({
+      chainId: 999,
+      supportedChainIds: [10, 8453],
+    })
+    expect(err.name).toBe('ChainNotSupportedError')
+    expect(err.chainId).toBe(999)
+    expect(err.supportedChainIds).toEqual([10, 8453])
+    expect(err).toBeInstanceOf(ActionsError)
+    expect(err).toBeInstanceOf(BaseError)
+    expect(err.shortMessage).toContain('999')
+  })
+
+  it('MarketNotAllowedError with pair', () => {
+    const err = new MarketNotAllowedError({
+      assetInSymbol: 'ETH',
+      assetOutSymbol: 'USDC',
+      chainId: 10,
+      reason: 'Pair is blocked',
+    })
+    expect(err.name).toBe('MarketNotAllowedError')
+    expect(err.assetInSymbol).toBe('ETH')
+    expect(err.assetOutSymbol).toBe('USDC')
+    expect(err.chainId).toBe(10)
+    expect(err).toBeInstanceOf(ActionsError)
+    expect(err).toBeInstanceOf(BaseError)
+    expect(err.shortMessage).toContain('ETH/USDC')
+  })
+
+  it('MarketNotAllowedError with address', () => {
+    const err = new MarketNotAllowedError({
+      address: '0xabc',
+      chainId: 8453,
+    })
+    expect(err.address).toBe('0xabc')
+    expect(err.shortMessage).toContain('0xabc')
+  })
+
+  it('ProviderNotConfiguredError', () => {
+    const err = new ProviderNotConfiguredError({
+      provider: 'lend',
+      details: 'Please configure lend',
+    })
+    expect(err.name).toBe('ProviderNotConfiguredError')
+    expect(err.provider).toBe('lend')
+    expect(err).toBeInstanceOf(ActionsError)
+    expect(err.shortMessage).toContain('lend')
+  })
+
+  it('MarketIdRequiredError', () => {
+    const err = new MarketIdRequiredError()
+    expect(err.name).toBe('MarketIdRequiredError')
+    expect(err).toBeInstanceOf(ActionsError)
+    expect(err.shortMessage).toBe('marketId is required')
+  })
+
+  it('AmountRequiredError', () => {
+    const err = new AmountRequiredError()
+    expect(err.name).toBe('AmountRequiredError')
+    expect(err).toBeInstanceOf(ActionsError)
+    expect(err.shortMessage).toContain('amountIn or amountOut')
+  })
+
+  it('InvalidAmountError', () => {
+    const err = new InvalidAmountError(-5)
+    expect(err.name).toBe('InvalidAmountError')
+    expect(err.amount).toBe(-5)
+    expect(err).toBeInstanceOf(ActionsError)
+  })
+
+  it('ConflictingAmountsError', () => {
+    const err = new ConflictingAmountsError()
+    expect(err.name).toBe('ConflictingAmountsError')
+    expect(err).toBeInstanceOf(ActionsError)
+  })
+
+  it('SameAssetError', () => {
+    const err = new SameAssetError('USDC')
+    expect(err.name).toBe('SameAssetError')
+    expect(err.symbol).toBe('USDC')
+    expect(err).toBeInstanceOf(ActionsError)
+  })
+
+  it('QuoteExpiredError', () => {
+    const err = new QuoteExpiredError({ expiresAt: 1000, currentTime: 2000 })
+    expect(err.name).toBe('QuoteExpiredError')
+    expect(err.expiresAt).toBe(1000)
+    expect(err.currentTime).toBe(2000)
+    expect(err).toBeInstanceOf(ActionsError)
+  })
+
+  it('ExactOutputNotSupportedError', () => {
+    const err = new ExactOutputNotSupportedError('Velodrome')
+    expect(err.name).toBe('ExactOutputNotSupportedError')
+    expect(err.provider).toBe('Velodrome')
+    expect(err).toBeInstanceOf(ActionsError)
+    expect(err.shortMessage).toContain('Velodrome')
+  })
+
+  it('AddressRequiredError', () => {
+    const err = new AddressRequiredError('walletAddress')
+    expect(err.name).toBe('AddressRequiredError')
+    expect(err.label).toBe('walletAddress')
+    expect(err).toBeInstanceOf(ActionsError)
+    expect(err.shortMessage).toBe('walletAddress is required')
+  })
+
+  it('ZeroAddressError', () => {
+    const err = new ZeroAddressError('walletAddress', '0x0')
+    expect(err.name).toBe('ZeroAddressError')
+    expect(err.label).toBe('walletAddress')
+    expect(err.address).toBe('0x0')
+    expect(err).toBeInstanceOf(ActionsError)
+    expect(err.shortMessage).toContain('walletAddress')
+  })
+
+  it('SlippageOutOfRangeError', () => {
+    const err = new SlippageOutOfRangeError(0.6, 0.5)
+    expect(err.name).toBe('SlippageOutOfRangeError')
+    expect(err.slippage).toBe(0.6)
+    expect(err.maxSlippage).toBe(0.5)
+    expect(err).toBeInstanceOf(ActionsError)
+    expect(err.shortMessage).toContain('0.6')
+  })
+
+  it('AssetNotSupportedOnChainError', () => {
+    const err = new AssetNotSupportedOnChainError('USDC', 999)
+    expect(err.name).toBe('AssetNotSupportedOnChainError')
+    expect(err.symbol).toBe('USDC')
+    expect(err.chainId).toBe(999)
+    expect(err).toBeInstanceOf(ActionsError)
+    expect(err.shortMessage).toContain('USDC')
+    expect(err.shortMessage).toContain('999')
+  })
+
+  it('NativeAssetAddressError', () => {
+    const err = new NativeAssetAddressError('ETH')
+    expect(err.name).toBe('NativeAssetAddressError')
+    expect(err.symbol).toBe('ETH')
+    expect(err).toBeInstanceOf(ActionsError)
+    expect(err.shortMessage).toContain('ETH')
+  })
+
+  it('MarketNotFoundError with poolId', () => {
+    const err = new MarketNotFoundError({ chainId: 10, poolId: '0xabc' })
+    expect(err.name).toBe('MarketNotFoundError')
+    expect(err.chainId).toBe(10)
+    expect(err.poolId).toBe('0xabc')
+    expect(err).toBeInstanceOf(ActionsError)
+    expect(err).toBeInstanceOf(BaseError)
+    expect(err.shortMessage).toContain('0xabc')
+    expect(err.shortMessage).toContain('10')
+  })
+
+  it('MarketNotFoundError without poolId', () => {
+    const err = new MarketNotFoundError({ chainId: 8453 })
+    expect(err.chainId).toBe(8453)
+    expect(err.poolId).toBeUndefined()
+    expect(err.shortMessage).toContain('8453')
+  })
+
+  it('AssetMetadataRequiredError', () => {
+    const err = new AssetMetadataRequiredError('decimals field is missing')
+    expect(err.name).toBe('AssetMetadataRequiredError')
+    expect(err.context).toBe('decimals field is missing')
+    expect(err).toBeInstanceOf(ActionsError)
+    expect(err.shortMessage).toBe('Asset metadata is required')
+  })
+
+  it('all errors are instanceof BaseError', () => {
+    const errors = [
+      new AddressRequiredError('x'),
+      new ChainNotSupportedError({ chainId: 1 }),
+      new MarketNotAllowedError({ chainId: 1 }),
+      new MarketNotFoundError({ chainId: 1 }),
+      new ProviderNotConfiguredError({ provider: 'x' }),
+      new MarketIdRequiredError(),
+      new AmountRequiredError(),
+      new InvalidAmountError(0),
+      new ConflictingAmountsError(),
+      new SameAssetError('ETH'),
+      new QuoteExpiredError({ expiresAt: 0, currentTime: 1 }),
+      new ExactOutputNotSupportedError('X'),
+      new ZeroAddressError('label'),
+      new SlippageOutOfRangeError(1, 0.5),
+      new AssetNotSupportedOnChainError('X', 1),
+      new NativeAssetAddressError('ETH'),
+      new AssetMetadataRequiredError(),
+      new InvalidParamsError({ param: 'x', expected: 'y' }),
+    ]
+    for (const err of errors) {
+      expect(err).toBeInstanceOf(ActionsError)
+      expect(err).toBeInstanceOf(BaseError)
+    }
+  })
+
+  it('InvalidParamsError carries param + expected (and optional received)', () => {
+    const err = new InvalidParamsError({
+      param: 'chainIds',
+      expected: 'SupportedChainId[] (non-empty)',
+      received: '[]',
+    })
+    expect(err.name).toBe('InvalidParamsError')
+    expect(err.param).toBe('chainIds')
+    expect(err.expected).toBe('SupportedChainId[] (non-empty)')
+    expect(err.received).toBe('[]')
+    expect(err.shortMessage).toContain('chainIds')
+    expect(err).toBeInstanceOf(ActionsError)
+  })
+})

package/src/core/error/errors.ts

@@ -1,27 +1,324 @@
-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
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Swap Quote
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Thrown when a pre-built `SwapQuote` is dispatched against a wallet whose
+ * address differs from the quote's `recipient`. Some routers (Velodrome
+ * v2/leaf) encode the recipient directly into calldata, so silently swapping
+ * recipients would route output tokens to the wrong address.
+ */
+export class QuoteRecipientMismatchError extends ActionsError {
+  override name = 'QuoteRecipientMismatchError' as const
+  quoteRecipient: string
+  walletAddress: string
+
+  constructor(params: { quoteRecipient: string; walletAddress: string }) {
+    super(
+      `SwapQuote was generated for a different recipient (${params.quoteRecipient}); re-quote via wallet.swap.getQuote(...) so calldata is bound to this wallet (${params.walletAddress})`,
+    )
+    this.quoteRecipient = params.quoteRecipient
+    this.walletAddress = params.walletAddress
+  }
+}
+
+/**
+ * Thrown when a provider's `_getQuote` returns a `SwapQuote` without a
+ * `recipient`. The base namespace requires every quote to be wallet-bound
+ * before approvals or calldata are built.
+ */
+export class QuoteRecipientMissingError extends ActionsError {
+  override name = 'QuoteRecipientMissingError' as const
+
+  constructor() {
+    super('SwapQuote.recipient missing — _getQuote must populate it')
   }
 }

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,
@@ -48,7 +58,9 @@ export {
   WSTETH,
 } from '@/constants/assets.js'
 export {
-  ACTIONS_SUPPORTED_CHAIN_IDS,
+  chainIdFromShortname,
+  SUPPORTED_CHAIN_IDS,
+  SUPPORTED_CHAIN_SHORTNAMES,
   type SupportedChainId,
 } from '@/constants/supportedChains.js'
 export * from '@/core/error/errors.js'
@@ -59,22 +71,19 @@ export {
   EnsResolutionError,
   EnsRpcError,
   type NameServiceProvider,
-} from '@/ens/index.js'
-export { LendProvider, MorphoLendProvider } from '@/lend/index.js'
+} from '@/services/nameservices/ens/index.js'
 export {
-  SwapProvider,
-  type UniswapMarketConfig,
-  UniswapSwapProvider,
-  type UniswapSwapProviderConfig,
-  type VelodromeMarketConfig,
-  VelodromeSwapProvider,
-  type VelodromeSwapProviderConfig,
-} from '@/swap/index.js'
+  type EnsName,
+  isEnsName,
+  resolveAddress,
+} from '@/services/nameservices/ens/utils.js'
 export type {
   ActionsConfig,
+  ApprovalMode,
   ApyBreakdown,
   Asset,
   EOATransactionReceipt,
+  LendAction,
   LendConfig,
   LendMarket,
   LendMarketConfig,
@@ -82,8 +91,8 @@ export type {
   LendMarketMetadata,
   LendMarketPosition,
   LendMarketSupply,
-  LendOptions,
   LendProviderConfig,
+  LendProviderName,
   LendTransaction,
   LendTransactionReceipt,
   SwapConfig,
@@ -103,11 +112,20 @@ export type {
   SwapTransaction,
   TokenBalance,
   TransactionData,
+  TransactionOptions,
   UserOperationTransactionReceipt,
   WalletConfig,
   WalletSwapParams,
 } from '@/types/index.js'
+export {
+  APPROVAL_MODES,
+  LEND_ACTIONS,
+  LEND_PROVIDER_NAMES,
+  SWAP_PROVIDER_NAMES,
+} from '@/types/index.js'
 export { getAssetAddress, isAssetSupportedOnChain } from '@/utils/assets.js'
-export { type EnsName, isEnsName, resolveAddress } from '@/utils/ens.js'
+export { getLendMarketAllowlist } from '@/utils/lendConfig.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'