@eth-optimism/actions-sdk 0.6.0 → 0.7.0

package/src/actions/shared/morpho/contracts.ts

@@ -78,7 +78,7 @@ export function getMorphoContracts(
 /**
  * Get all chain IDs where Morpho contracts are deployed.
  * Returns chains present in the local contracts registry.
- * Filtering against ACTIONS_SUPPORTED_CHAIN_IDS and developer-configured chains
+ * Filtering against SUPPORTED_CHAIN_IDS and developer-configured chains
  * is handled by the LendProvider base class.
  */
 export function getSupportedChainIds(): number[] {

package/src/actions/swap/core/SwapProvider.ts

@@ -3,11 +3,12 @@ import { formatUnits } from 'viem'
 
 import { UNIVERSAL_ROUTER_MSG_SENDER } from '@/actions/swap/core/markets.js'
 import type { SupportedChainId } from '@/constants/supportedChains.js'
-import { ACTIONS_SUPPORTED_CHAIN_IDS } from '@/constants/supportedChains.js'
+import { SUPPORTED_CHAIN_IDS } from '@/constants/supportedChains.js'
 import {
   MarketNotAllowedError,
   ProviderNotConfiguredError,
   QuoteExpiredError,
+  QuoteRecipientMissingError,
 } from '@/core/error/errors.js'
 import type { ChainManager } from '@/services/ChainManager.js'
 import type {
@@ -221,7 +222,7 @@ export abstract class SwapProvider<
     const configuredChains = this.chainManager.getSupportedChains()
     return this.protocolSupportedChainIds().filter(
       (id) =>
-        (ACTIONS_SUPPORTED_CHAIN_IDS as readonly number[]).includes(id) &&
+        (SUPPORTED_CHAIN_IDS as readonly number[]).includes(id) &&
         configuredChains.includes(id),
     )
   }
@@ -436,9 +437,7 @@ export abstract class SwapProvider<
     quote: SwapQuote,
   ): Promise<SwapTransaction> {
     if (!quote.recipient) {
-      throw new Error(
-        'SwapQuote.recipient missing — _getQuote must populate it',
-      )
+      throw new QuoteRecipientMissingError()
     }
     const approvals = await this._buildApprovals(quote)
 

package/src/actions/swap/namespaces/WalletSwapNamespace.ts

@@ -3,6 +3,7 @@ import { isAddressEqual } from 'viem'
 import { QUOTE_DISCRIMINATOR } from '@/actions/swap/core/SwapProvider.js'
 import { BaseSwapNamespace } from '@/actions/swap/namespaces/BaseSwapNamespace.js'
 import type { SupportedChainId } from '@/constants/supportedChains.js'
+import { QuoteRecipientMismatchError } from '@/core/error/errors.js'
 import type { SwapExecuteParamsResolved } from '@/services/nameservices/ens/types.js'
 import type { RecipientResolver } from '@/services/nameservices/ens/utils.js'
 import type { SwapSettings } from '@/types/actions.js'
@@ -91,10 +92,10 @@ export class WalletSwapNamespace extends BaseSwapNamespace {
    */
   private requireQuoteForThisWallet(quote: SwapQuote): SwapQuote {
     if (!isAddressEqual(quote.recipient, this.wallet.address)) {
-      throw new Error(
-        `SwapQuote was generated for a different recipient (${quote.recipient}). ` +
-          `Re-quote via wallet.swap.getQuote(...) so calldata is bound to this wallet (${this.wallet.address}).`,
-      )
+      throw new QuoteRecipientMismatchError({
+        quoteRecipient: quote.recipient,
+        walletAddress: this.wallet.address,
+      })
     }
     return quote
   }

package/src/constants/supportedChains.ts

@@ -20,26 +20,86 @@ import {
   worldchain,
 } from 'viem/chains'
 
-export const ACTIONS_SUPPORTED_CHAIN_IDS = [
-  mainnet.id,
-  sepolia.id,
-  optimism.id,
-  optimismSepolia.id,
-  base.id,
-  baseSepolia.id,
-  unichain.id,
-  unichainSepolia.id,
-  worldchain.id,
-  bob.id,
-  celo.id,
-  fraxtal.id,
-  ink.id,
-  lisk.id,
-  metalL2.id,
-  mode.id,
-  soneium.id,
-  superseed.id,
-  swellchain.id,
+const slug = (name: string): string => name.toLowerCase().replace(/\s+/g, '-')
+
+/**
+ * Single source of truth for the chains the SDK supports. All other
+ * chain-related constants in this module are derived from this list.
+ */
+const SUPPORTED_CHAINS = [
+  mainnet,
+  sepolia,
+  optimism,
+  optimismSepolia,
+  base,
+  baseSepolia,
+  unichain,
+  unichainSepolia,
+  worldchain,
+  bob,
+  celo,
+  fraxtal,
+  ink,
+  lisk,
+  metalL2,
+  mode,
+  soneium,
+  superseed,
+  swellchain,
 ] as const
 
-export type SupportedChainId = (typeof ACTIONS_SUPPORTED_CHAIN_IDS)[number]
+export type SupportedChainId = (typeof SUPPORTED_CHAINS)[number]['id']
+
+export const SUPPORTED_CHAIN_IDS = SUPPORTED_CHAINS.map(
+  (c) => c.id,
+) as readonly SupportedChainId[]
+
+/**
+ * Extra names that resolve to a chain in addition to its canonical
+ * `slug(chain.name)`. Add entries here only when there's a shorter or
+ * more familiar name worth accepting alongside the viem one.
+ */
+const EXTRA_CHAIN_ALIASES: Partial<
+  Record<SupportedChainId, readonly string[]>
+> = {
+  [mainnet.id]: ['mainnet'], // viem: 'ethereum'
+  [optimism.id]: ['optimism'], // viem: 'op-mainnet'
+  [worldchain.id]: ['worldchain'], // viem: 'world-chain'
+  [metalL2.id]: ['metal'], // viem: 'metal-l2'
+  [mode.id]: ['mode'], // viem: 'mode-mainnet'
+  [soneium.id]: ['soneium'], // viem: 'soneium-mainnet'
+  [swellchain.id]: ['swell'], // viem: 'swellchain'
+}
+
+/**
+ * Canonical CLI / human-friendly shortname for each supported chain:
+ * `slug(chain.name)` (e.g. `base-sepolia`, `ethereum`, `op-mainnet`).
+ * Use this for display. For input parsing prefer `chainIdFromShortname`,
+ * which also accepts entries from `EXTRA_CHAIN_ALIASES`.
+ */
+export const SUPPORTED_CHAIN_SHORTNAMES: Record<SupportedChainId, string> =
+  Object.fromEntries(
+    SUPPORTED_CHAINS.map((chain) => [chain.id, slug(chain.name)]),
+  ) as Record<SupportedChainId, string>
+
+const NAME_TO_ID: Record<string, SupportedChainId> = (() => {
+  const index: Record<string, SupportedChainId> = {}
+  for (const chain of SUPPORTED_CHAINS) {
+    const id = chain.id as SupportedChainId
+    index[SUPPORTED_CHAIN_SHORTNAMES[id]] = id
+    for (const alias of EXTRA_CHAIN_ALIASES[id] ?? []) index[alias] = id
+  }
+  return index
+})()
+
+/**
+ * Resolve a user-typed chain name to a `SupportedChainId`. Accepts both
+ * the canonical shortname (`mainnet`, `optimism`) and the viem `chain.name`
+ * slug (`ethereum`, `op-mainnet`). Case-insensitive. Returns `undefined`
+ * for unknown names.
+ */
+export function chainIdFromShortname(
+  name: string,
+): SupportedChainId | undefined {
+  return NAME_TO_ID[name.toLowerCase()]
+}

package/src/core/error/errors.ts

@@ -285,3 +285,40 @@ export class InvalidParamsError extends ActionsError {
     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

@@ -58,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'
@@ -77,9 +79,11 @@ export {
 } from '@/services/nameservices/ens/utils.js'
 export type {
   ActionsConfig,
+  ApprovalMode,
   ApyBreakdown,
   Asset,
   EOATransactionReceipt,
+  LendAction,
   LendConfig,
   LendMarket,
   LendMarketConfig,
@@ -88,6 +92,7 @@ export type {
   LendMarketPosition,
   LendMarketSupply,
   LendProviderConfig,
+  LendProviderName,
   LendTransaction,
   LendTransactionReceipt,
   SwapConfig,
@@ -112,7 +117,14 @@ export type {
   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 { 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'

package/src/services/ChainManager.ts

@@ -11,11 +11,28 @@ import {
 } from 'viem'
 import type { BundlerClient, SmartAccount } from 'viem/account-abstraction'
 import { createBundlerClient } from 'viem/account-abstraction'
+import { mainnet, sepolia } from 'viem/chains'
 
 import type { SupportedChainId } from '@/constants/supportedChains.js'
 import { ChainNotSupportedError } from '@/core/error/errors.js'
 import type { ChainConfig } from '@/types/chain.js'
 
+/** viem `pollingInterval` (ms) for L2-class chains with ~1-2s blocks. */
+const L2_POLLING_INTERVAL_MS = 1000
+/** viem `pollingInterval` (ms) for L1-class chains with ~12s blocks. */
+const L1_POLLING_INTERVAL_MS = 4000
+
+const L1_CHAIN_IDS: ReadonlySet<SupportedChainId> = new Set([
+  mainnet.id,
+  sepolia.id,
+])
+
+function pollingIntervalForChain(chainId: SupportedChainId): number {
+  return L1_CHAIN_IDS.has(chainId)
+    ? L1_POLLING_INTERVAL_MS
+    : L2_POLLING_INTERVAL_MS
+}
+
 /**
  * Chain Manager Service
  * @description Manages public clients and chain infrastructure for the Verbs SDK.
@@ -99,6 +116,7 @@ export class ChainManager {
     const client = createPublicClient({
       chain: this.getChain(chainId),
       transport: http(bundlerUrl),
+      pollingInterval: pollingIntervalForChain(chainId),
     })
     return createBundlerClient({
       account,
@@ -191,6 +209,7 @@ export class ChainManager {
       const client = createPublicClient({
         chain,
         transport: this.getTransportForChain(chainConfig.chainId),
+        pollingInterval: pollingIntervalForChain(chainConfig.chainId),
       })
 
       clients.set(chainConfig.chainId, client)

package/src/types/actions.ts

@@ -4,14 +4,24 @@ import type { ChainManager } from '@/services/ChainManager.js'
 import type { Asset } from '@/types/asset.js'
 import type { ChainConfig } from '@/types/chain.js'
 import type { LendProviderConfig } from '@/types/lend/index.js'
-import type { LendProviders, SwapProviders } from '@/types/providers.js'
+import type {
+  LendProviders,
+  SwapProviderName,
+  SwapProviders,
+} from '@/types/providers.js'
 import type { SwapProviderConfig } from '@/types/swap/index.js'
 import type { ProviderSpec } from '@/wallet/core/providers/hosted/types/index.js'
 
 // Re-export provider configs for convenience
 export type { LendProviderConfig, SwapProviderConfig }
-// Re-export centralized provider maps
-export type { LendProviders, SwapProviders } from '@/types/providers.js'
+// Re-export centralized provider maps and constants
+export type {
+  LendProviderName,
+  LendProviders,
+  SwapProviderName,
+  SwapProviders,
+} from '@/types/providers.js'
+export { LEND_PROVIDER_NAMES, SWAP_PROVIDER_NAMES } from '@/types/providers.js'
 
 /** Require at least one property to be defined */
 type RequireAtLeastOne<T> = {
@@ -42,12 +52,6 @@ export type LendConfig = RequireAtLeastOne<{
   settings?: LendSettings
 }
 
-/** Names of available swap providers — derived from SwapProviders registry */
-export type SwapProviderName = keyof SwapProviders
-
-/** Names of available lend providers — derived from LendProviders registry */
-export type LendProviderName = keyof LendProviders
-
 /** Routing strategy for selecting a provider when multiple are configured. */
 export type SwapRoutingStrategy = 'price'
 
@@ -151,7 +155,18 @@ export interface ActionsContext {
  * Default is `"exact"` for safety. Demo / dogfood configs typically opt into
  * `"max"` to avoid an extra approval tx per swap or supply.
  */
-export type ApprovalMode = 'exact' | 'max'
+export const APPROVAL_MODES = ['exact', 'max'] as const
+
+export type ApprovalMode = (typeof APPROVAL_MODES)[number]
+
+/**
+ * The lend write actions exposed by the SDK's wallet namespace
+ * (`openPosition` / `closePosition`). Useful for callers that emit
+ * action-tagged output envelopes or branch on the action being performed.
+ */
+export const LEND_ACTIONS = ['open', 'close'] as const
+
+export type LendAction = (typeof LEND_ACTIONS)[number]
 
 /**
  * Actions SDK configuration

package/src/types/providers.ts

@@ -3,20 +3,38 @@ import type { SwapProvider } from '@/actions/swap/core/SwapProvider.js'
 import type { LendProviderConfig } from '@/types/lend/index.js'
 import type { SwapProviderConfig } from '@/types/swap/index.js'
 
+/**
+ * Runtime list of lend provider names. Source of truth for both the
+ * `LendProviderName` type union and any consumer (CLI, validators) that
+ * needs to enumerate provider names at runtime.
+ */
+export const LEND_PROVIDER_NAMES = ['morpho', 'aave'] as const
+
+/** Names of available lend providers. */
+export type LendProviderName = (typeof LEND_PROVIDER_NAMES)[number]
+
 /**
  * Map of available lend providers keyed by provider name.
- * Add new lend providers here — this is the single source of truth.
+ * Add new providers by extending `LEND_PROVIDER_NAMES`.
  */
 export type LendProviders = {
-  morpho?: LendProvider<LendProviderConfig>
-  aave?: LendProvider<LendProviderConfig>
+  [K in LendProviderName]?: LendProvider<LendProviderConfig>
 }
 
+/**
+ * Runtime list of swap provider names. Source of truth for both the
+ * `SwapProviderName` type union and any consumer (CLI, validators) that
+ * needs to enumerate provider names at runtime.
+ */
+export const SWAP_PROVIDER_NAMES = ['uniswap', 'velodrome'] as const
+
+/** Names of available swap providers. */
+export type SwapProviderName = (typeof SWAP_PROVIDER_NAMES)[number]
+
 /**
  * Map of available swap providers keyed by provider name.
- * Add new swap providers here — this is the single source of truth.
+ * Add new providers by extending `SWAP_PROVIDER_NAMES`.
  */
 export type SwapProviders = {
-  uniswap?: SwapProvider<SwapProviderConfig>
-  velodrome?: SwapProvider<SwapProviderConfig>
+  [K in SwapProviderName]?: SwapProvider<SwapProviderConfig>
 }

package/src/utils/__tests__/lendConfig.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest'
+
+import { MockUSDCAsset } from '@/__mocks__/MockAssets.js'
+import type { LendConfig } from '@/types/actions.js'
+import type { LendMarketConfig } from '@/types/lend/base.js'
+import { getLendMarketAllowlist } from '@/utils/lendConfig.js'
+
+const morphoMarket: LendMarketConfig = {
+  address: '0x0000000000000000000000000000000000000001',
+  chainId: 130,
+  name: 'Morpho USDC',
+  asset: MockUSDCAsset,
+  lendProvider: 'morpho',
+}
+
+const aaveMarket: LendMarketConfig = {
+  address: '0x0000000000000000000000000000000000000002',
+  chainId: 130,
+  name: 'Aave USDC',
+  asset: MockUSDCAsset,
+  lendProvider: 'aave',
+}
+
+describe('getLendMarketAllowlist', () => {
+  it('returns empty list when lend config is undefined', () => {
+    expect(getLendMarketAllowlist(undefined)).toEqual([])
+  })
+
+  it('flattens allowlists across all providers', () => {
+    const lend: LendConfig = {
+      morpho: { marketAllowlist: [morphoMarket] },
+      aave: { marketAllowlist: [aaveMarket] },
+    }
+    expect(getLendMarketAllowlist(lend)).toEqual([morphoMarket, aaveMarket])
+  })
+
+  it('skips the settings sibling key', () => {
+    const lend: LendConfig = {
+      morpho: { marketAllowlist: [morphoMarket] },
+      settings: { approvalMode: 'max' },
+    }
+    expect(getLendMarketAllowlist(lend)).toEqual([morphoMarket])
+  })
+
+  it('returns empty list when no provider declares an allowlist', () => {
+    const lend: LendConfig = {
+      morpho: {},
+      settings: { approvalMode: 'exact' },
+    }
+    expect(getLendMarketAllowlist(lend)).toEqual([])
+  })
+})

package/src/utils/lendConfig.ts

@@ -0,0 +1,17 @@
+import type { LendConfig } from '@/types/actions.js'
+import type { LendMarketConfig } from '@/types/lend/base.js'
+import { LEND_PROVIDER_NAMES } from '@/types/providers.js'
+
+/**
+ * Flatten every provider's `marketAllowlist` from a `LendConfig` into a single
+ * list. Returns an empty list when `lend` is undefined or no provider declares
+ * an allowlist.
+ */
+export function getLendMarketAllowlist(
+  lend: LendConfig | undefined,
+): readonly LendMarketConfig[] {
+  if (!lend) return []
+  return LEND_PROVIDER_NAMES.flatMap(
+    (name) => lend[name]?.marketAllowlist ?? [],
+  )
+}

package/src/wallet/core/wallets/abstract/Wallet.ts

@@ -84,6 +84,18 @@ export abstract class Wallet {
     }
   }
 
+  /**
+   * Check whether a wallet namespace (`lend`, `swap`) is configured on this
+   * wallet. Useful for callers that branch on capability instead of catching
+   * a `TypeError` from `wallet.lend!.openPosition(...)` later. Returns `false`
+   * when the namespace is undefined (no providers were registered for it).
+   * @param namespace - Wallet namespace name to probe.
+   * @returns `true` when the namespace is configured.
+   */
+  has(namespace: 'lend' | 'swap'): boolean {
+    return this[namespace] !== undefined
+  }
+
   /**
    * Get asset balances across the requested chains (or all supported chains).
    * @description Fetches ETH and ERC20 token balances for this wallet. By default queries every chain returned by the SDK's `ChainManager`. Pass `options.chainIds` to restrict the query to a subset of those chains; each id is validated against the configured chains and an `InvalidParamsError` / `ChainNotSupportedError` is thrown for unusable input. Uses the configured supported assets from `ActionsConfig.assets` if provided.

package/src/wallet/core/wallets/abstract/__tests__/Wallet.spec.ts

@@ -125,4 +125,19 @@ describe('Wallet (base)', () => {
     expect(wallet.lend).toBeDefined()
     expect(wallet.lend).toEqual({})
   })
+
+  describe('has', () => {
+    it("returns false for a namespace that wasn't configured", () => {
+      const wallet = new TestWallet(chainManager, address, signer)
+      expect(wallet.has('lend')).toBe(false)
+      expect(wallet.has('swap')).toBe(false)
+    })
+
+    it('returns true once a namespace has been attached', () => {
+      const wallet = new TestWallet(chainManager, address, signer)
+      wallet.lend = {} as WalletLendNamespace
+      expect(wallet.has('lend')).toBe(true)
+      expect(wallet.has('swap')).toBe(false)
+    })
+  })
 })

package/src/wallet/core/wallets/eoa/EOAWallet.ts

@@ -5,7 +5,7 @@ import type {
   LocalAccount,
   WalletClient,
 } from 'viem'
-import { createWalletClient } from 'viem'
+import { createWalletClient, nonceManager } from 'viem'
 
 import type { SupportedChainId } from '@/constants/supportedChains.js'
 import type { TransactionData } from '@/types/lend/index.js'
@@ -23,8 +23,10 @@ export abstract class EOAWallet extends Wallet {
   /**
    * Create a WalletClient for this EOA wallet.
    *
-   * Creates a viem-compatible WalletClient configured with this wallet's account
-   * and the specified chain. Supports fallback transport for multiple RPC URLs.
+   * Attaches viem's default `nonceManager` to the signer so back-to-back
+   * `sendTransaction` calls receive sequential nonces without re-fetching
+   * `eth_getTransactionCount('pending')` per tx. This avoids races on
+   * load-balanced RPCs where pending state lags by one block.
    * @param chainId - The chain ID to create the wallet client for
    * @returns Promise resolving to a WalletClient configured for the specified chain
    */
@@ -39,8 +41,11 @@ export abstract class EOAWallet extends Wallet {
       []
     >
   > {
+    const account: LocalAccount = this.signer.nonceManager
+      ? this.signer
+      : { ...this.signer, nonceManager }
     return createWalletClient({
-      account: this.signer,
+      account,
       chain: this.chainManager.getChain(chainId),
       transport: this.chainManager.getTransportForChain(chainId),
     })
@@ -70,8 +75,14 @@ export abstract class EOAWallet extends Wallet {
   /**
    * Send multiple transactions sequentially from this EOA wallet.
    *
-   * Executes transactions one at a time in order, waiting for 2 confirmations
-   * between each to ensure nonce updates. Returns an array of receipts.
+   * Each transaction is awaited to inclusion (one confirmation) via `send()`
+   * before the next is signed. The `nonceManager` attached in `walletClient()`
+   * keeps nonces in sequence locally, so the wait does not need extra
+   * confirmations to guarantee nonce monotonicity.
+   *
+   * Note: this method assumes a sequencer-ordered chain (e.g. OP-stack L2s).
+   * On chains with deeper reorg risk, consider an additional confirmations
+   * pass at the call site.
    * @param transactionData - Array of transactions to send
    * @param chainId - Chain to send the transactions on
    * @returns Promise resolving to array of transaction receipts (one per transaction)
@@ -83,12 +94,6 @@ export abstract class EOAWallet extends Wallet {
     const receipts: EOATransactionReceipt[] = []
     for (const tx of transactionData) {
       const receipt = await this.send(tx, chainId)
-      const publicClient = this.chainManager.getPublicClient(chainId)
-      // wait an extra confirmation so give time for nonce to be updated
-      await publicClient.waitForTransactionReceipt({
-        hash: receipt.transactionHash,
-        confirmations: 2,
-      })
       receipts.push(receipt)
     }
     return receipts