@eth-optimism/actions-sdk 0.5.0 → 0.7.0

package/src/{swap → actions/swap}/providers/velodrome/__tests__/encoding.v2.test.ts

@@ -1,4 +1,5 @@
-import type { Address } from 'viem'
+import type { Address, Hex } from 'viem'
+import { decodeAbiParameters } from 'viem'
 import { describe, expect, it } from 'vitest'
 
 import {
@@ -10,8 +11,9 @@ import {
   LEAF_ROUTER_ABI,
   UNIVERSAL_ROUTER_ABI,
   V2_ROUTER_ABI,
-} from '@/swap/providers/velodrome/abis.js'
-import { encodeSwap } from '@/swap/providers/velodrome/encoding/index.js'
+} from '@/actions/swap/providers/velodrome/abis.js'
+import { encodeSwap } from '@/actions/swap/providers/velodrome/encoding/index.js'
+import { V2_SWAP_EXACT_IN_INPUT_PARAMS } from '@/actions/swap/providers/velodrome/encoding/routers/v2.js'
 
 import {
   BASE_CHAIN_ID,
@@ -197,6 +199,35 @@ describe('encodeSwap', () => {
       expect(inputs).toHaveLength(1)
       expect(deadline).toBe(BigInt(DEADLINE))
     })
+
+    // Regression for #438: payerIsUser must be true so the router pulls tokens via
+    // transferFrom against an ERC20 allowance. payerIsUser=false requires tokens to
+    // be pre-deposited to the router, which only works when caller batches atomically.
+    it('encodes V2_SWAP_EXACT_IN with payerIsUser = true', () => {
+      const data = encodeSwap({
+        assetIn: MockUSDCAsset,
+        assetOut: MockWETHAsset,
+        amountInRaw: 1000000n,
+        amountOutMin: 400000000000000000n,
+        routerType: 'universal',
+        stable: false,
+        factoryAddress: FACTORY,
+        recipient: RECIPIENT,
+        deadline: DEADLINE,
+        chainId: BASE_CHAIN_ID,
+      })
+
+      const { args } = decode<[Hex, Hex[], bigint]>(UNIVERSAL_ROUTER_ABI, data)
+      const [, inputs] = args
+      const decoded = decodeAbiParameters(
+        V2_SWAP_EXACT_IN_INPUT_PARAMS,
+        inputs[0],
+      )
+      const payerIsUserIdx = V2_SWAP_EXACT_IN_INPUT_PARAMS.findIndex(
+        (p) => p.name === 'payerIsUser',
+      )
+      expect(decoded[payerIsUserIdx]).toBe(true)
+    })
   })
 
   describe('router type comparison', () => {

package/src/{swap → actions/swap}/providers/velodrome/config.ts

@@ -1,4 +1,5 @@
 import type { SupportedChainId } from '@/constants/supportedChains.js'
+import { ChainNotSupportedError } from '@/core/error/errors.js'
 
 import { VELODROME_CHAINS, type VelodromeChainConfig } from './addresses.js'
 import type { VelodromeMarketConfig } from './types.js'
@@ -20,7 +21,10 @@ export function getChainConfig(
 ): VelodromeChainConfig {
   const config = VELODROME_CHAINS[chainId]
   if (!config) {
-    throw new Error(`Velodrome/Aerodrome not supported on chain ${chainId}`)
+    throw new ChainNotSupportedError({
+      chainId,
+      supportedChainIds: getSupportedChainIds(),
+    })
   }
   return config
 }

package/src/{swap → actions/swap}/providers/velodrome/encoding/helpers.ts

@@ -1,9 +1,10 @@
 import type { Address } from 'viem'
 import { formatUnits } from 'viem'
 
+import { UNIVERSAL_ROUTER_MSG_SENDER } from '@/actions/swap/core/markets.js'
 import { WETH } from '@/constants/assets.js'
 import type { SupportedChainId } from '@/constants/supportedChains.js'
-import { UNIVERSAL_ROUTER_MSG_SENDER } from '@/swap/core/markets.js'
+import { ChainNotSupportedError } from '@/core/error/errors.js'
 import type { Asset } from '@/types/asset.js'
 import type { SwapPrice, SwapRoute } from '@/types/swap/index.js'
 import { getAssetAddress, isNativeAsset } from '@/utils/assets.js'
@@ -42,7 +43,7 @@ export function resolveTokens(
 export function getWrappedNativeAddress(chainId: SupportedChainId): Address {
   const addr = WETH.address[chainId]
   if (!addr || addr === 'native') {
-    throw new Error(`No WETH address configured for chain ${chainId}`)
+    throw new ChainNotSupportedError({ chainId })
   }
   return addr
 }

package/src/{swap → actions/swap}/providers/velodrome/encoding/index.ts

@@ -1,6 +1,5 @@
 export type { PoolQuoteResult } from './poolRouter.js'
 export { encodePoolSwap, fetchPoolQuote } from './poolRouter.js'
-export { buildTokenApproval } from './routers/approval.js'
 export type { EncodeCLSwapParams, GetCLQuoteParams } from './routers/cl.js'
 export { encodeCLSwap, getCLQuote } from './routers/cl.js'
 export type { EncodeSwapParams, GetQuoteParams } from './routers/v2.js'

package/src/{swap → actions/swap}/providers/velodrome/encoding/poolRouter.ts

@@ -1,8 +1,9 @@
 import type { Address, Hex, PublicClient } from 'viem'
 
+import type { VelodromeChainConfig } from '@/actions/swap/providers/velodrome/config.js'
+import type { ResolvedPoolConfig } from '@/actions/swap/providers/velodrome/types.js'
 import type { SupportedChainId } from '@/constants/supportedChains.js'
-import type { VelodromeChainConfig } from '@/swap/providers/velodrome/config.js'
-import type { ResolvedPoolConfig } from '@/swap/providers/velodrome/types.js'
+import { ChainNotSupportedError } from '@/core/error/errors.js'
 import type { Asset } from '@/types/asset.js'
 import type { SwapPrice } from '@/types/swap/index.js'
 
@@ -36,7 +37,7 @@ export async function fetchPoolQuote(
 
   if (poolConfig.type === 'cl') {
     if (!chain.contracts.clPoolFactory || !chain.contracts.clQuoterV2) {
-      throw new Error(`CL pools not supported on chain ${chainId}`)
+      throw new ChainNotSupportedError({ chainId })
     }
     const internalQuote = await getCLQuote({
       assetIn,

package/src/{swap → actions/swap}/providers/velodrome/encoding/routers/cl.ts

@@ -1,17 +1,18 @@
 import type { Address, Hex, PublicClient } from 'viem'
 import { encodeAbiParameters, encodeFunctionData, encodePacked } from 'viem'
 
-import type { SupportedChainId } from '@/constants/supportedChains.js'
 import {
   CL_POOL_FACTORY_ABI,
   CL_QUOTER_ABI,
   UNIVERSAL_ROUTER_ABI,
-} from '@/swap/providers/velodrome/abis.js'
+} from '@/actions/swap/providers/velodrome/abis.js'
 import {
   buildSwapPrice,
   resolveTokens,
   UNIVERSAL_ROUTER_MSG_SENDER,
-} from '@/swap/providers/velodrome/encoding/helpers.js'
+} from '@/actions/swap/providers/velodrome/encoding/helpers.js'
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import { MarketNotAllowedError } from '@/core/error/errors.js'
 import type { Asset } from '@/types/asset.js'
 import type { SwapPrice, SwapRoute } from '@/types/swap/index.js'
 
@@ -62,9 +63,12 @@ export async function getCLQuote(params: GetCLQuoteParams): Promise<SwapPrice> {
     !poolAddress ||
     poolAddress === '0x0000000000000000000000000000000000000000'
   ) {
-    throw new Error(
-      `No CL pool found for ${assetIn.metadata.symbol}/${assetOut.metadata.symbol} (tickSpacing=${tickSpacing})`,
-    )
+    throw new MarketNotAllowedError({
+      assetInSymbol: assetIn.metadata.symbol,
+      assetOutSymbol: assetOut.metadata.symbol,
+      chainId,
+      reason: `No CL pool found for ${assetIn.metadata.symbol}/${assetOut.metadata.symbol} (tickSpacing=${tickSpacing})`,
+    })
   }
 
   // Quote via QuoterV2.quoteExactInputSingle
@@ -109,9 +113,22 @@ export interface EncodeCLSwapParams {
 /** Universal Router V3_SWAP_EXACT_IN command byte */
 const V3_SWAP_EXACT_IN = 0x00
 
+/** ABI param shape for the V3_SWAP_EXACT_IN input payload. Shared with tests. */
+export const V3_SWAP_EXACT_IN_INPUT_PARAMS = [
+  { name: 'recipient', type: 'address' },
+  { name: 'amountIn', type: 'uint256' },
+  { name: 'amountOutMin', type: 'uint256' },
+  { name: 'path', type: 'bytes' },
+  { name: 'payerIsUser', type: 'bool' },
+] as const
+
 /**
  * Encode a V3_SWAP_EXACT_IN command for a CL/Slipstream pool on the Universal Router.
  * Path: encodePacked([tokenIn (20), tickSpacing as int24 (3), tokenOut (20)]) — 43 bytes.
+ *
+ * payerIsUser = true: the router pulls tokens from msg.sender via standard
+ * transferFrom against an existing ERC20 allowance. Works for both EOAs (sequential
+ * approve + execute) and smart wallets (atomic approve + execute in one UserOp).
  * @param params - CL swap encoding parameters
  * @returns Encoded calldata as hex string
  */
@@ -123,7 +140,7 @@ export function encodeCLSwap(params: EncodeCLSwapParams): Hex {
     chainId,
   )
 
-  const commands = `0x${V3_SWAP_EXACT_IN.toString(16).padStart(2, '0')}` as Hex
+  const commands = encodePacked(['uint8'], [V3_SWAP_EXACT_IN])
 
   // CL path: [tokenIn (20)] [tickSpacing as int24 (3)] [tokenOut (20)] — 43 bytes
   const path = encodePacked(
@@ -131,22 +148,13 @@ export function encodeCLSwap(params: EncodeCLSwapParams): Hex {
     [tokenIn, tickSpacing, tokenOut],
   )
 
-  const input = encodeAbiParameters(
-    [
-      { type: 'address' },
-      { type: 'uint256' },
-      { type: 'uint256' },
-      { type: 'bytes' },
-      { type: 'bool' },
-    ],
-    [
-      UNIVERSAL_ROUTER_MSG_SENDER, // recipient = msg.sender (Universal Router sentinel)
-      amountInRaw,
-      amountOutMin,
-      path,
-      false, // payerIsUser — tokens pre-transferred to router
-    ],
-  )
+  const input = encodeAbiParameters(V3_SWAP_EXACT_IN_INPUT_PARAMS, [
+    UNIVERSAL_ROUTER_MSG_SENDER, // recipient = msg.sender (Universal Router sentinel)
+    amountInRaw,
+    amountOutMin,
+    path,
+    true, // payerIsUser — router pulls from msg.sender via transferFrom
+  ])
 
   return encodeFunctionData({
     abi: UNIVERSAL_ROUTER_ABI,

package/src/{swap → actions/swap}/providers/velodrome/encoding/routers/v2.ts

@@ -1,20 +1,21 @@
 import type { Address, Hex, PublicClient } from 'viem'
 import { encodeAbiParameters, encodeFunctionData, encodePacked } from 'viem'
 
-import type { SupportedChainId } from '@/constants/supportedChains.js'
 import {
   LEAF_ROUTER_ABI,
   POOL_ABI,
   POOL_FACTORY_ABI,
   UNIVERSAL_ROUTER_ABI,
   V2_ROUTER_ABI,
-} from '@/swap/providers/velodrome/abis.js'
-import type { VelodromeRouterType } from '@/swap/providers/velodrome/config.js'
+} from '@/actions/swap/providers/velodrome/abis.js'
+import type { VelodromeRouterType } from '@/actions/swap/providers/velodrome/config.js'
 import {
   buildSwapPrice,
   resolveTokens,
   UNIVERSAL_ROUTER_MSG_SENDER,
-} from '@/swap/providers/velodrome/encoding/helpers.js'
+} from '@/actions/swap/providers/velodrome/encoding/helpers.js'
+import type { SupportedChainId } from '@/constants/supportedChains.js'
+import { MarketNotAllowedError } from '@/core/error/errors.js'
 import type { Asset } from '@/types/asset.js'
 import type { SwapPrice, SwapRoute } from '@/types/swap/index.js'
 import { isNativeAsset } from '@/utils/assets.js'
@@ -22,6 +23,16 @@ import { isNativeAsset } from '@/utils/assets.js'
 /** Universal Router V2_SWAP_EXACT_IN command byte */
 const V2_SWAP_EXACT_IN = 0x08
 
+/** ABI param shape for the V2_SWAP_EXACT_IN input payload. Shared with tests. */
+export const V2_SWAP_EXACT_IN_INPUT_PARAMS = [
+  { name: 'recipient', type: 'address' },
+  { name: 'amountIn', type: 'uint256' },
+  { name: 'amountOutMin', type: 'uint256' },
+  { name: 'route', type: 'bytes' },
+  { name: 'payerIsUser', type: 'bool' },
+  { name: 'isUni', type: 'bool' },
+] as const
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Quoting
 // ─────────────────────────────────────────────────────────────────────────────
@@ -109,9 +120,12 @@ async function fetchAmountOutViaPool(
     !poolAddress ||
     poolAddress === '0x0000000000000000000000000000000000000000'
   ) {
-    throw new Error(
-      `No Velodrome pool found for ${assetIn.metadata.symbol}/${assetOut.metadata.symbol} (stable=${stable})`,
-    )
+    throw new MarketNotAllowedError({
+      assetInSymbol: assetIn.metadata.symbol,
+      assetOutSymbol: assetOut.metadata.symbol,
+      chainId: params.chainId,
+      reason: `No Velodrome pool found for ${assetIn.metadata.symbol}/${assetOut.metadata.symbol} (stable=${stable})`,
+    })
   }
 
   return (await publicClient.readContract({
@@ -192,36 +206,29 @@ export function encodeSwap(params: EncodeSwapParams): Hex {
 /**
  * Encode a V2_SWAP_EXACT_IN command for the Universal Router.
  * Route: encodePacked(tokenIn, stable, tokenOut) — 41 bytes per hop.
- * payerIsUser = false: tokens are pre-transferred to the Router by the smart wallet.
+ *
+ * payerIsUser = true: the router pulls tokens from msg.sender via standard
+ * transferFrom against an existing ERC20 allowance. Works for both EOAs (sequential
+ * approve + execute) and smart wallets (atomic approve + execute in one UserOp).
  */
 function encodeUniversalV2Swap(
   tokenIn: Address,
   tokenOut: Address,
   params: EncodeSwapParams,
 ): Hex {
-  const commands = `0x${V2_SWAP_EXACT_IN.toString(16).padStart(2, '0')}` as Hex
+  const commands = encodePacked(['uint8'], [V2_SWAP_EXACT_IN])
   const routes = encodePacked(
     ['address', 'bool', 'address'],
     [tokenIn, params.stable, tokenOut],
   )
-  const input = encodeAbiParameters(
-    [
-      { type: 'address' },
-      { type: 'uint256' },
-      { type: 'uint256' },
-      { type: 'bytes' },
-      { type: 'bool' },
-      { type: 'bool' },
-    ],
-    [
-      UNIVERSAL_ROUTER_MSG_SENDER, // recipient = msg.sender (Universal Router sentinel)
-      params.amountInRaw,
-      params.amountOutMin,
-      routes,
-      false, // payerIsUser
-      false, // isUni — false for Velodrome/Aerodrome
-    ],
-  )
+  const input = encodeAbiParameters(V2_SWAP_EXACT_IN_INPUT_PARAMS, [
+    UNIVERSAL_ROUTER_MSG_SENDER, // recipient = msg.sender (Universal Router sentinel)
+    params.amountInRaw,
+    params.amountOutMin,
+    routes,
+    true, // payerIsUser — router pulls from msg.sender via transferFrom
+    false, // isUni — false for Velodrome/Aerodrome
+  ])
   return encodeFunctionData({
     abi: UNIVERSAL_ROUTER_ABI,
     functionName: 'execute',

package/src/{swap → actions/swap}/providers/velodrome/markets.ts

@@ -1,9 +1,10 @@
 import type { Address } from 'viem'
 import { concat, keccak256 } from 'viem'
 
+import { assetPairs } from '@/actions/swap/core/markets.js'
 import { VELODROME } from '@/constants/providers.js'
 import type { SupportedChainId } from '@/constants/supportedChains.js'
-import { assetPairs } from '@/swap/core/markets.js'
+import { AssetMetadataRequiredError } from '@/core/error/errors.js'
 import type { Asset } from '@/types/asset.js'
 import type { SwapMarket } from '@/types/swap/index.js'
 
@@ -22,12 +23,12 @@ export function resolvePoolConfig(
   const hasStable = config.stable !== undefined
   const hasTick = config.tickSpacing !== undefined
   if (hasStable && hasTick) {
-    throw new Error(
+    throw new AssetMetadataRequiredError(
       'stable and tickSpacing are mutually exclusive — set one, not both',
     )
   }
   if (!hasStable && !hasTick) {
-    throw new Error(
+    throw new AssetMetadataRequiredError(
       'Either stable (v2 AMM) or tickSpacing (CL) must be configured',
     )
   }

package/src/actions.ts

@@ -1,9 +1,13 @@
-import { EnsNamespace } from '@/ens/index.js'
-import { AaveLendProvider, MorphoLendProvider } from '@/lend/index.js'
-import { ActionsLendNamespace } from '@/lend/namespaces/ActionsLendNamespace.js'
+import { AaveLendProvider, MorphoLendProvider } from '@/actions/lend/index.js'
+import { ActionsLendNamespace } from '@/actions/lend/namespaces/ActionsLendNamespace.js'
+import {
+  UniswapSwapProvider,
+  VelodromeSwapProvider,
+} from '@/actions/swap/index.js'
+import { ActionsSwapNamespace } from '@/actions/swap/namespaces/ActionsSwapNamespace.js'
+import { ProviderNotConfiguredError } from '@/core/error/errors.js'
 import { ChainManager } from '@/services/ChainManager.js'
-import { UniswapSwapProvider, VelodromeSwapProvider } from '@/swap/index.js'
-import { ActionsSwapNamespace } from '@/swap/namespaces/ActionsSwapNamespace.js'
+import { EnsNamespace } from '@/services/nameservices/ens/index.js'
 import type {
   ActionsConfig,
   AssetsConfig,
@@ -80,16 +84,19 @@ export class Actions<
 
     this._ens = new EnsNamespace(this.chainManager)
 
+    const lendSettings = config.lend?.settings
     if (config.lend?.morpho) {
       this._lendProviders.morpho = new MorphoLendProvider(
         config.lend.morpho,
         this.chainManager,
+        lendSettings,
       )
     }
     if (config.lend?.aave) {
       this._lendProviders.aave = new AaveLendProvider(
         config.lend.aave,
         this.chainManager,
+        lendSettings,
       )
     }
     if (this._lendProviders.morpho || this._lendProviders.aave) {
@@ -132,9 +139,10 @@ export class Actions<
    */
   get lend(): ActionsLendNamespace {
     if (!this._lend) {
-      throw new Error(
-        'Lend provider not configured. Please add lend configuration to ActionsConfig.',
-      )
+      throw new ProviderNotConfiguredError({
+        provider: 'lend',
+        details: 'Please add lend configuration to ActionsConfig.',
+      })
     }
     return this._lend
   }
@@ -166,9 +174,10 @@ export class Actions<
    */
   get swap(): ActionsSwapNamespace {
     if (!this._swap) {
-      throw new Error(
-        'Swap provider not configured. Please add swap configuration to ActionsConfig.',
-      )
+      throw new ProviderNotConfiguredError({
+        provider: 'swap',
+        details: 'Please add swap configuration to ActionsConfig.',
+      })
     }
     return this._swap
   }
@@ -226,7 +235,42 @@ export class Actions<
       SmartWalletProvider
     >
   > {
-    const hostedWalletProviderConfig = config.hostedWalletConfig.provider
+    const hostedWalletProvider = config.hostedWalletConfig
+      ? await this.createHostedWalletProvider(config.hostedWalletConfig)
+      : undefined
+
+    const smartWalletProvider: SmartWalletProvider = (() => {
+      if (
+        !config.smartWalletConfig ||
+        config.smartWalletConfig.provider.type === 'default'
+      ) {
+        return new DefaultSmartWalletProvider(
+          this.chainManager,
+          this._lendProviders,
+          this._swapProviders,
+          this.getSupportedAssets(),
+          config.smartWalletConfig.provider.attributionSuffix,
+        )
+      }
+      throw new ProviderNotConfiguredError({
+        provider: config.smartWalletConfig.provider.type,
+      })
+    })()
+
+    return new WalletProvider(hostedWalletProvider, smartWalletProvider)
+  }
+
+  private async createHostedWalletProvider(
+    hostedWalletConfig: NonNullable<
+      ActionsConfig<
+        THostedWalletProviderType,
+        THostedWalletProvidersSchema['providerConfigs']
+      >['wallet']['hostedWalletConfig']
+    >,
+  ): Promise<
+    THostedWalletProvidersSchema['providerInstances'][THostedWalletProviderType]
+  > {
+    const hostedWalletProviderConfig = hostedWalletConfig.provider
     const factory = this.hostedWalletProviderRegistry.getFactory(
       hostedWalletProviderConfig.type,
     )
@@ -236,11 +280,12 @@ export class Actions<
         : undefined
     ) as unknown
     if (!factory.validateOptions(options)) {
-      throw new Error(
-        `Invalid options for hosted wallet provider: ${hostedWalletProviderConfig.type}`,
-      )
+      throw new ProviderNotConfiguredError({
+        provider: hostedWalletProviderConfig.type,
+        details: 'Invalid options',
+      })
     }
-    const hostedWalletProvider = await factory.create(
+    return factory.create(
       {
         chainManager: this.chainManager,
         lendProviders: this._lendProviders,
@@ -250,26 +295,6 @@ export class Actions<
       },
       options,
     )
-
-    let smartWalletProvider: SmartWalletProvider
-    if (
-      !config.smartWalletConfig ||
-      config.smartWalletConfig.provider.type === 'default'
-    ) {
-      smartWalletProvider = new DefaultSmartWalletProvider(
-        this.chainManager,
-        this._lendProviders,
-        this._swapProviders,
-        this.getSupportedAssets(),
-        config.smartWalletConfig.provider.attributionSuffix,
-      )
-    } else {
-      throw new Error(
-        `Unsupported smart wallet provider: ${config.smartWalletConfig.provider.type}`,
-      )
-    }
-
-    return new WalletProvider(hostedWalletProvider, smartWalletProvider)
   }
 
   /**
@@ -291,6 +316,12 @@ export class Actions<
       THostedWalletProvidersSchema['providerToActionsOptions'],
       THostedWalletProvidersSchema['providerInstances'][THostedWalletProviderType],
       SmartWalletProvider
-    >(providerFactory)
+    >(providerFactory, {
+      chainManager: this.chainManager,
+      lendProviders: this._lendProviders,
+      swapProviders: this._swapProviders,
+      supportedAssets: this.getSupportedAssets(),
+      swapSettings: this._swapSettings,
+    })
   }
 }

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()]
+}