CLI + SDK Improvements

.changeset/add-actions-cli-package.md

@@ -0,0 +1,8 @@
+---
+'actions-cli': minor
+---
+
+Add actions-cli package: agent-first CLI for the Actions SDK. Ships scaffolding,
+JSON output pipeline, smart-wallet bootstrap, and smoke commands (`assets`,
+`chains`, `wallet address`, `wallet balance`). Lend and swap namespaces land
+in subsequent PRs.

.changeset/sdk-cli-boundary-cleanup.md

@@ -0,0 +1,29 @@
+---
+'@eth-optimism/actions-sdk': minor
+'actions-cli': patch
+---
+
+SDK: barrel-export the lend / approval / capability vocabulary that downstream
+tooling was reaching past the public API to consume.
+
+- Re-export `ApprovalMode`, `LendProviderName`, and the new `LendAction` literal
+  from the package root.
+- Add a runtime mirror for each: `APPROVAL_MODES` and `LEND_ACTIONS`.
+  `ApprovalMode` and `LendAction` are now derived from these tuples, so the
+  type and the runtime list cannot drift.
+- Add `CHAIN_SHORTNAMES`, a canonical `Record<SupportedChainId, string>` of
+  human-friendly chain shortnames (`base`, `op-sepolia`, ...). Use this as
+  the source of truth for `--chain` parsing and any other surface that maps
+  user-typed chain strings to a `SupportedChainId`. Adding a new
+  `SupportedChainId` requires a corresponding entry here.
+- Add `getLendMarketAllowlist(lend)`, which flattens every provider's
+  `marketAllowlist` from a `LendConfig` and skips the `settings` sibling.
+- Add `Wallet.has(namespace)` capability check for the `lend` and `swap`
+  namespaces. Lets callers branch on whether a namespace was registered
+  without poking at internal fields.
+
+CLI: drop the local mirrors and reach for the SDK exports instead. Help-text
+examples now derive from the resolved config (asset symbols, chain shortnames,
+chain ids) rather than hard-coding `USDC_DEMO` / `base-sepolia` / `84532`.
+`runLendMarket` passes the resolved `LendMarketConfig` straight through to
+`actions.lend.getMarket` instead of rebuilding `{address, chainId}`.

.changeset/sdk-eoa-perf.md

@@ -0,0 +1,28 @@
+---
+'@eth-optimism/actions-sdk': minor
+---
+
+Perf: cut EOA swap dispatch wall-time on fast L2s.
+
+- `EOAWallet.sendBatch` no longer waits for `confirmations: 2` between sub-txs.
+  One inclusion wait per tx is enough now that `EOAWallet.walletClient` attaches
+  viem's default `nonceManager` to the signer, which keeps nonces sequential
+  locally instead of relying on `eth_getTransactionCount('pending')` on every
+  send (avoids races on load-balanced RPCs).
+- `ChainManager` now defaults the viem `pollingInterval` per chain class:
+  1000ms for L2-class chains (~1-2s blocks) and 4000ms for L1 mainnet/sepolia
+  (~12s blocks). Saves ~3 RPC poll cycles per receipt wait on Base/OP/Unichain.
+  This default applies to the public client used by `getPublicClient()` and to
+  the public client wrapping the simple bundler client. There is no override
+  knob; if a real consumer needs one we'll add it then.
+
+Behavioural notes for consumers:
+
+- `sendBatch` is sequential and assumes a sequencer-ordered chain (e.g.
+  OP-stack L2s). On reorg-heavy chains, callers should consider an additional
+  confirmations pass at the call site.
+- The Velodrome swap path uses **direct ERC-20 max approval** to its universal
+  router when `approvalMode: 'max'` is requested — there is no Permit2
+  intermediary as on Uniswap. The full allowance persists at the router until
+  manually revoked. Continue to scope `approvalMode: 'max'` to demo/testnet
+  paths.

packages/cli/src/commands/__tests__/walletLendClose.test.ts

@@ -51,6 +51,9 @@ describe('runWalletLendClose', () => {
           openPosition: async () => null,
           getPosition: getPosition ?? (async () => null),
         },
+        has(namespace: 'lend' | 'swap') {
+          return namespace === 'lend'
+        },
       } as never,
     })
   }

packages/cli/src/commands/__tests__/walletLendOpen.test.ts

@@ -44,6 +44,9 @@ describe('runWalletLendOpen', () => {
       wallet: {
         address: '0xabc',
         lend: { openPosition, closePosition: async () => null },
+        has(namespace: 'lend' | 'swap') {
+          return namespace === 'lend'
+        },
       } as never,
     })
   }
@@ -210,7 +213,12 @@ describe('runWalletLendOpen', () => {
       config: getDemoConfig(),
       actions: {} as never,
       signer: {} as never,
-      wallet: { address: '0xabc' } as never,
+      wallet: {
+        address: '0xabc',
+        has() {
+          return false
+        },
+      } as never,
     })
     try {
       await runWalletLendOpen({ market: 'gauntlet-usdc', amount: '1' })

packages/cli/src/commands/__tests__/walletLendPosition.test.ts

@@ -45,6 +45,9 @@ describe('runWalletLendPosition', () => {
               closePosition: async () => null,
             }
           : undefined,
+        has(namespace: 'lend' | 'swap') {
+          return namespace === 'lend' && withLend
+        },
       } as never,
     })
   }

packages/cli/src/commands/actions/lend/index.ts

@@ -2,6 +2,9 @@ import { Command } from 'commander'
 
 import { runLendMarket } from '@/commands/actions/lend/market.js'
 import { runLendMarkets } from '@/commands/actions/lend/markets.js'
+import { loadConfig } from '@/config/loadConfig.js'
+import { configuredAssets } from '@/resolvers/assets.js'
+import { CHAIN_EXAMPLES } from '@/resolvers/chains.js'
 
 /**
  * @description Builds the root `lend` subcommand tree. Children read
@@ -11,6 +14,8 @@ import { runLendMarkets } from '@/commands/actions/lend/markets.js'
  * @returns Commander `Command` configured with `markets` and `market`.
  */
 export function lendCommand(): Command {
+  const assetExample =
+    configuredAssets(loadConfig())[0]?.metadata.symbol ?? 'USDC'
   const command = new Command('lend').description(
     'Read-only lending market commands (no PRIVATE_KEY required).',
   )
@@ -19,15 +24,15 @@ export function lendCommand(): Command {
     .description('List all lending markets across configured providers.')
     .option(
       '--asset <symbol>',
-      'filter to markets denominated in one asset (e.g. USDC_DEMO). Case-insensitive.',
+      `filter to markets denominated in one asset (e.g. ${assetExample}). Case-insensitive.`,
     )
     .option(
       '--chain <shortname>',
-      'filter to markets on one chain by shortname (e.g. base-sepolia); mutually exclusive with --chain-id',
+      `filter to markets on one chain by shortname (e.g. ${CHAIN_EXAMPLES.shortname}); mutually exclusive with --chain-id`,
     )
     .option(
       '--chain-id <id>',
-      'filter to markets on one chain by numeric id (e.g. 84532); mutually exclusive with --chain',
+      `filter to markets on one chain by numeric id (e.g. ${CHAIN_EXAMPLES.chainId}); mutually exclusive with --chain`,
     )
     .action(runLendMarkets)
   command

packages/cli/src/commands/actions/lend/market.ts

@@ -10,10 +10,7 @@ export async function runLendMarket(flags: { market: string }): Promise<void> {
   const { actions, config } = baseContext()
   const market = resolveMarket(flags.market, configuredMarkets(config))
   try {
-    const result = await actions.lend.getMarket({
-      address: market.address,
-      chainId: market.chainId,
-    })
+    const result = await actions.lend.getMarket(market)
     printOutput('lendMarket', result)
   } catch (err) {
     rethrowAsCliError(err)

packages/cli/src/commands/wallet/index.ts

@@ -4,6 +4,7 @@ import { runWalletAddress } from '@/commands/wallet/address.js'
 import { runWalletBalance } from '@/commands/wallet/balance.js'
 import { walletLendCommand } from '@/commands/wallet/lend/index.js'
 import { walletSwapCommand } from '@/commands/wallet/swap/index.js'
+import { CHAIN_EXAMPLES } from '@/resolvers/chains.js'
 
 /**
  * @description Builds the `wallet` subcommand tree. Registered children
@@ -23,11 +24,11 @@ export function walletCommand(): Command {
     .description('Print ETH and ERC-20 balances across every configured chain.')
     .option(
       '--chain <shortnames>',
-      'filter to one or more chains by shortname; comma-separated (e.g. base-sepolia or base-sepolia,op-sepolia); mutually exclusive with --chain-id',
+      `filter to one or more chains by shortname; comma-separated (e.g. ${CHAIN_EXAMPLES.shortname} or ${CHAIN_EXAMPLES.shortnameList}); mutually exclusive with --chain-id`,
     )
     .option(
       '--chain-id <ids>',
-      'filter to one or more chains by numeric id; comma-separated (e.g. 84532 or 84532,130); mutually exclusive with --chain',
+      `filter to one or more chains by numeric id; comma-separated (e.g. ${CHAIN_EXAMPLES.chainId} or ${CHAIN_EXAMPLES.chainIdList}); mutually exclusive with --chain`,
     )
     .action(runWalletBalance)
   command.addCommand(walletLendCommand())

packages/cli/src/commands/wallet/lend/index.ts

@@ -1,3 +1,4 @@
+import { APPROVAL_MODES } from '@eth-optimism/actions-sdk'
 import { Command } from 'commander'
 
 import { runWalletLendClose } from '@/commands/wallet/lend/close.js'
@@ -24,7 +25,7 @@ export function walletLendCommand(): Command {
       'amount to supply in human-readable units (e.g. 10 for 10 USDC)',
     )
     .option(
-      '--approval-mode <exact|max>',
+      `--approval-mode <${APPROVAL_MODES.join('|')}>`,
       'ERC-20 approval strategy: "exact" approves only this call (default, gas-heavier on repeat); "max" approves max-uint to amortise across future supplies',
     )
     .action(runWalletLendOpen)

packages/cli/src/commands/wallet/lend/requireLendCapability.ts

@@ -1,14 +1,16 @@
+import type { Wallet } from '@eth-optimism/actions-sdk'
+
 import { CliError } from '@/output/errors.js'
 
 /**
- * @description Asserts that a `Wallet` has the lend namespace configured. Narrows `wallet.lend` to non-null on the caller side so each handler can reach `wallet.lend.openPosition` etc. without re-checking. Throws `CliError('config')` when no lend providers are configured (`ActionsConfig.lend` was omitted or empty).
+ * @description Asserts that a `Wallet` has the lend namespace configured. Defers the runtime check to `Wallet.has('lend')` and narrows `wallet.lend` to non-null on the caller side so each handler can reach `wallet.lend.openPosition` etc. without re-checking. Throws `CliError('config')` when no lend providers are configured (`ActionsConfig.lend` was omitted or empty).
  * @param wallet - Wallet instance from `walletContext()`.
  * @throws `CliError` with code `config` when `wallet.lend` is undefined.
  */
-export function requireLendCapability<W extends { lend?: unknown }>(
+export function requireLendCapability<W extends Wallet>(
   wallet: W,
 ): asserts wallet is W & { lend: NonNullable<W['lend']> } {
-  if (!wallet.lend) {
+  if (!wallet.has('lend')) {
     throw new CliError(
       'config',
       'Lending is not configured (no providers in config.lend)',

packages/cli/src/commands/wallet/lend/runLendAction.ts

@@ -1,3 +1,9 @@
+import {
+  APPROVAL_MODES,
+  type ApprovalMode,
+  type LendAction,
+} from '@eth-optimism/actions-sdk'
+
 import { walletContext } from '@/context/walletContext.js'
 import { CliError, rethrowAsCliError } from '@/output/errors.js'
 import { printOutput } from '@/output/printOutput.js'
@@ -7,14 +13,6 @@ import { ensureOnchainSuccess, toReceiptArray } from '@/utils/receipts.js'
 
 import { requireLendCapability } from './requireLendCapability.js'
 
-// Mirrors the SDK's `ApprovalMode = 'exact' | 'max'` (declared in
-// `@/types/actions` but not re-exported from the SDK barrel).
-type ApprovalMode = 'exact' | 'max'
-const APPROVAL_MODES = [
-  'exact',
-  'max',
-] as const satisfies readonly ApprovalMode[]
-
 export interface LendOpenFlags {
   market: string
   amount: string
@@ -29,16 +27,14 @@ export type LendCloseFlags =
   | { market: string; amount: string; max?: never }
   | { market: string; amount?: never; max: true }
 
-type LendAction = 'open' | 'close'
-
 function parseApprovalMode(raw: string | undefined): ApprovalMode | undefined {
   if (raw === undefined) return undefined
   if ((APPROVAL_MODES as readonly string[]).includes(raw)) {
     return raw as ApprovalMode
   }
   throw new CliError(
     'validation',
-    `Invalid --approval-mode: ${raw} (expected exact or max)`,
+    `Invalid --approval-mode: ${raw} (expected ${APPROVAL_MODES.join(' or ')})`,
     { approvalMode: raw },
   )
 }

packages/cli/src/demo/markets.ts

@@ -1,10 +1,10 @@
 import {
   ETH,
+  getAssetAddress,
   type LendMarketConfig,
   USDC_DEMO,
   WETH,
 } from '@eth-optimism/actions-sdk'
-import type { Address } from 'viem'
 import { baseSepolia, optimismSepolia } from 'viem/chains'
 
 /**
@@ -26,7 +26,7 @@ export const GauntletUSDCDemo: LendMarketConfig = {
  * gateway. Mirrored from the demo backend's config.
  */
 export const AaveETH: LendMarketConfig = {
-  address: WETH.address[optimismSepolia.id] as Address,
+  address: getAssetAddress(WETH, optimismSepolia.id),
   chainId: optimismSepolia.id,
   name: 'Aave ETH',
   asset: ETH,

packages/cli/src/output/printOutput.ts

@@ -1,7 +1,9 @@
 import type {
   Asset,
+  LendAction,
   LendMarket,
   LendMarketPosition,
+  LendProviderName,
   SupportedChainId,
   SwapMarket,
   SwapQuote,
@@ -28,12 +30,12 @@ export interface AddressDoc {
 }
 
 export interface LendActionDoc {
-  action: 'open' | 'close'
+  action: LendAction
   market: {
     name: string
     address: Address
     chainId: SupportedChainId
-    provider: string
+    provider: LendProviderName
   }
   asset: { symbol: string }
   amount: number

packages/cli/src/resolvers/__tests__/chains.test.ts

@@ -12,12 +12,16 @@ const ALL: SupportedChainId[] = [
   optimismSepolia.id,
 ]
 
-const SHORTNAMES = ['base', 'base-sepolia', 'optimism', 'op-sepolia'] as const
+const SHORTNAMES = ['base', 'base-sepolia', 'op-mainnet', 'op-sepolia'] as const
 
 describe('resolveChain', () => {
   it('resolves each canonical shortname to its chain id', () => {
     expect(resolveChain('base-sepolia', ALL)).toBe(baseSepolia.id)
     expect(resolveChain('op-sepolia', ALL)).toBe(optimismSepolia.id)
+    expect(resolveChain('op-mainnet', ALL)).toBe(optimism.id)
+  })
+
+  it('also accepts curated aliases on top of the viem name', () => {
     expect(resolveChain('optimism', ALL)).toBe(optimism.id)
   })
 
@@ -51,7 +55,7 @@ describe('shortnameFor', () => {
   it('returns the canonical shortname for each supported chain id', () => {
     expect(shortnameFor(baseSepolia.id)).toBe('base-sepolia')
     expect(shortnameFor(optimismSepolia.id)).toBe('op-sepolia')
-    expect(shortnameFor(optimism.id)).toBe('optimism')
+    expect(shortnameFor(optimism.id)).toBe('op-mainnet')
   })
 })