@eth-optimism/actions-sdk 0.3.0 → 0.5.0

package/src/utils/{permit2.test.ts → approve.test.ts}

@@ -3,12 +3,15 @@ import { decodeFunctionData } from 'viem'
 import { describe, expect, it, vi } from 'vitest'
 
 import {
+  buildApprovalTxIfNeeded,
+  buildErc20ApprovalTx,
   buildPermit2ApprovalTx,
   buildTokenApprovalTx,
   checkPermit2Allowance,
   checkTokenAllowance,
   DEFAULT_PERMIT2_EXPIRY_SECONDS,
-} from '@/utils/permit2.js'
+  getApprovalDeficit,
+} from '@/utils/approve.js'
 
 const PERMIT2_ABI = [
   {
@@ -140,3 +143,116 @@ describe('buildPermit2ApprovalTx', () => {
     )
   })
 })
+
+describe('buildErc20ApprovalTx', () => {
+  it('builds approval for exact amount', () => {
+    const tx = buildErc20ApprovalTx(TOKEN, SPENDER, 500000n)
+
+    expect(tx.to).toBe(TOKEN)
+    expect(tx.value).toBe(0n)
+    expect(tx.data).toMatch(/^0x/)
+  })
+})
+
+describe('getApprovalDeficit', () => {
+  it('returns 0n when allowance is sufficient', async () => {
+    const publicClient = {
+      readContract: vi.fn().mockResolvedValue(1000000n),
+    } as unknown as PublicClient
+
+    const deficit = await getApprovalDeficit({
+      publicClient,
+      token: TOKEN,
+      owner: OWNER,
+      spender: SPENDER,
+      amount: 500000n,
+    })
+
+    expect(deficit).toBe(0n)
+  })
+
+  it('returns deficit when allowance is insufficient', async () => {
+    const publicClient = {
+      readContract: vi.fn().mockResolvedValue(300000n),
+    } as unknown as PublicClient
+
+    const deficit = await getApprovalDeficit({
+      publicClient,
+      token: TOKEN,
+      owner: OWNER,
+      spender: SPENDER,
+      amount: 500000n,
+    })
+
+    expect(deficit).toBe(200000n)
+  })
+
+  it('returns full amount when allowance is zero', async () => {
+    const publicClient = {
+      readContract: vi.fn().mockResolvedValue(0n),
+    } as unknown as PublicClient
+
+    const deficit = await getApprovalDeficit({
+      publicClient,
+      token: TOKEN,
+      owner: OWNER,
+      spender: SPENDER,
+      amount: 500000n,
+    })
+
+    expect(deficit).toBe(500000n)
+  })
+})
+
+describe('buildApprovalTxIfNeeded', () => {
+  it('returns undefined when allowance is sufficient', async () => {
+    const publicClient = {
+      readContract: vi.fn().mockResolvedValue(1000000n),
+    } as unknown as PublicClient
+
+    const tx = await buildApprovalTxIfNeeded({
+      publicClient,
+      token: TOKEN,
+      owner: OWNER,
+      spender: SPENDER,
+      amount: 500000n,
+    })
+
+    expect(tx).toBeUndefined()
+  })
+
+  it('returns approval tx for the deficit only', async () => {
+    const publicClient = {
+      readContract: vi.fn().mockResolvedValue(300000n),
+    } as unknown as PublicClient
+
+    const tx = await buildApprovalTxIfNeeded({
+      publicClient,
+      token: TOKEN,
+      owner: OWNER,
+      spender: SPENDER,
+      amount: 500000n,
+    })
+
+    expect(tx).toBeDefined()
+    expect(tx!.to).toBe(TOKEN)
+    expect(tx!.value).toBe(0n)
+  })
+
+  it('returns approval for full amount when allowance is zero', async () => {
+    const publicClient = {
+      readContract: vi.fn().mockResolvedValue(0n),
+    } as unknown as PublicClient
+
+    const tx = await buildApprovalTxIfNeeded({
+      publicClient,
+      token: TOKEN,
+      owner: OWNER,
+      spender: SPENDER,
+      amount: 500000n,
+    })
+
+    expect(tx).toBeDefined()
+    expect(tx!.to).toBe(TOKEN)
+  })
+})

package/src/utils/{permit2.ts → approve.ts}

@@ -75,25 +75,15 @@ export async function checkPermit2Allowance(params: {
 }
 
 /**
- * Build ERC20 token approval transaction to Permit2
+ * Build ERC20 token approval transaction to Permit2.
+ * Uses maxUint256 — the Uniswap-canonical pattern.
+ * Permit2 is immutable with no owner; spending is scoped by its own allowance system.
  */
 export function buildTokenApprovalTx(
   token: Address,
   permit2Address: Address,
 ): TransactionData {
-  const data = encodeFunctionData({
-    abi: erc20Abi,
-    functionName: 'approve',
-    // ERC20 -> Permit2: maxUint256 is the Uniswap-canonical pattern.
-    // Permit2 is immutable with no owner — spending is scoped by its own allowance system.
-    args: [permit2Address, maxUint256],
-  })
-
-  return {
-    to: token,
-    data,
-    value: 0n,
-  }
+  return buildErc20ApprovalTx(token, permit2Address, maxUint256)
 }
 
 /**
@@ -142,3 +132,66 @@ export async function checkTokenAllowance(params: {
     args: [owner, spender],
   })
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Generic ERC20 approval utilities
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Build an ERC20 approve transaction.
+ * @param token - ERC20 token address
+ * @param spender - Address to approve
+ * @param amount - Amount to approve
+ * @returns Transaction data for the approval
+ */
+export function buildErc20ApprovalTx(
+  token: Address,
+  spender: Address,
+  amount: bigint,
+): TransactionData {
+  return {
+    to: token,
+    data: encodeFunctionData({
+      abi: erc20Abi,
+      functionName: 'approve',
+      args: [spender, amount],
+    }),
+    value: 0n,
+  }
+}
+
+/**
+ * Compute how much additional ERC20 approval is needed.
+ * Returns 0n if current allowance is sufficient.
+ * @param params - Token, owner, spender, required amount, and public client
+ * @returns The deficit (required - current), or 0n if already sufficient
+ */
+export async function getApprovalDeficit(params: {
+  publicClient: PublicClient
+  token: Address
+  owner: Address
+  spender: Address
+  amount: bigint
+}): Promise<bigint> {
+  const current = await checkTokenAllowance(params)
+  return current >= params.amount ? 0n : params.amount - current
+}
+
+/**
+ * Build an ERC20 approval transaction only if needed, approving only the deficit.
+ * Checks the current on-chain allowance, returns undefined if already sufficient.
+ * @param params - Token, owner, spender, required amount, and public client
+ * @returns Approval transaction for the deficit amount, or undefined if allowance is sufficient
+ */
+export async function buildApprovalTxIfNeeded(params: {
+  publicClient: PublicClient
+  token: Address
+  owner: Address
+  spender: Address
+  amount: bigint
+}): Promise<TransactionData | undefined> {
+  const deficit = await getApprovalDeficit(params)
+  return deficit > 0n
+    ? buildErc20ApprovalTx(params.token, params.spender, deficit)
+    : undefined
+}

package/src/utils/assets.ts

@@ -86,3 +86,17 @@ export function getAssetAddress(
   }
   return address
 }
+
+/**
+ * Get all non-native contract addresses for an asset across all chains, lowercased.
+ * @param asset - Asset to extract addresses from
+ * @returns Array of lowercased contract addresses
+ */
+export function getAllAssetAddresses(asset: Asset): string[] {
+  return Object.values(asset.address)
+    .filter(
+      (addr): addr is Exclude<typeof addr, undefined | 'native'> =>
+        addr !== undefined && addr !== 'native',
+    )
+    .map((addr) => addr.toLowerCase())
+}

package/src/utils/ens.test.ts

@@ -0,0 +1,104 @@
+import type { Address, PublicClient } from 'viem'
+import { zeroAddress } from 'viem'
+import { describe, expect, it, vi } from 'vitest'
+
+import { resolveAddress } from '@/utils/ens.js'
+
+const REAL_ADDRESS = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' as Address
+const ZERO_ADDRESS = zeroAddress
+
+function mockClient(
+  returnValue: Address | null,
+  rejects = false,
+): PublicClient {
+  const getEnsAddress = rejects
+    ? vi.fn().mockRejectedValue(new Error('network error'))
+    : vi.fn().mockResolvedValue(returnValue)
+  return { getEnsAddress } as unknown as PublicClient
+}
+
+describe('resolveAddress', () => {
+  describe('hex address input', () => {
+    it('returns a valid hex address as-is', async () => {
+      expect(await resolveAddress(REAL_ADDRESS)).toBe(REAL_ADDRESS)
+    })
+
+    it('does not require a mainnet client for hex addresses', async () => {
+      await expect(resolveAddress(REAL_ADDRESS)).resolves.toBe(REAL_ADDRESS)
+    })
+  })
+
+  describe('ENS name input', () => {
+    it('resolves a valid ENS name', async () => {
+      const client = mockClient(REAL_ADDRESS)
+      const result = await resolveAddress('vitalik.eth', client)
+      expect(result).toBe(REAL_ADDRESS)
+      expect(client.getEnsAddress).toHaveBeenCalledWith({ name: 'vitalik.eth' })
+    })
+
+    it('normalises the ENS name before resolving', async () => {
+      const client = mockClient(REAL_ADDRESS)
+      await resolveAddress('Vitalik.ETH', client)
+      expect(client.getEnsAddress).toHaveBeenCalledWith({ name: 'vitalik.eth' })
+    })
+
+    it('throws EnsNotConfiguredError when no mainnet client is provided', async () => {
+      const { EnsNotConfiguredError } = await import('@/ens/errors.js')
+      await expect(resolveAddress('vitalik.eth')).rejects.toThrow(
+        EnsNotConfiguredError,
+      )
+    })
+
+    it('includes chain ID 1 in the error when no mainnet client provided', async () => {
+      await expect(resolveAddress('vitalik.eth')).rejects.toThrow('1')
+    })
+
+    it('throws when ENS name cannot be resolved (returns null)', async () => {
+      const client = mockClient(null)
+      await expect(resolveAddress('unresolvable.eth', client)).rejects.toThrow(
+        '"unresolvable.eth" could not be resolved',
+      )
+    })
+
+    it('throws when ENS name resolves to zero address', async () => {
+      const client = mockClient(ZERO_ADDRESS)
+      await expect(resolveAddress('zero.eth', client)).rejects.toThrow(
+        'zero address',
+      )
+    })
+
+    it('throws with RPC error label on network failure', async () => {
+      const client = mockClient(null, true)
+      await expect(resolveAddress('vitalik.eth', client)).rejects.toThrow(
+        'RPC error',
+      )
+    })
+
+    it('preserves the original cause on RPC failure', async () => {
+      const client = mockClient(null, true)
+      let caught: Error | undefined
+      try {
+        await resolveAddress('vitalik.eth', client)
+      } catch (e) {
+        caught = e as Error
+      }
+      expect(caught?.cause).toBeInstanceOf(Error)
+      expect((caught?.cause as Error).message).toBe('network error')
+    })
+  })
+
+  describe('invalid input', () => {
+    it('throws for ENS-shaped strings that fail normalisation', async () => {
+      // Has a dot so satisfies EnsName, but contains invalid ENS characters
+      await expect(
+        resolveAddress('not!valid.eth', {} as PublicClient),
+      ).rejects.toThrow('Invalid address or ENS name')
+    })
+
+    it('includes the invalid input in the error message', async () => {
+      await expect(
+        resolveAddress('!!bad!!.eth', {} as PublicClient),
+      ).rejects.toThrow('"!!bad!!.eth"')
+    })
+  })
+})

package/src/utils/ens.ts

@@ -0,0 +1,85 @@
+import type { Address, PublicClient } from 'viem'
+import { isAddress, isAddressEqual, zeroAddress } from 'viem'
+import { normalize } from 'viem/ens'
+
+import {
+  EnsNotConfiguredError,
+  EnsResolutionError,
+  EnsRpcError,
+} from '@/ens/errors.js'
+import type { EnsName } from '@/ens/types.js'
+
+export { type EnsName, isEnsName } from '@/ens/types.js'
+
+/** Resolves an ENS name or address to a checksummed hex Address, or returns undefined. */
+export type RecipientResolver = (
+  recipient: Address | EnsName | undefined,
+) => Promise<Address | undefined>
+
+/** Pass-through resolver used when no ENS resolution is configured. Throws on ENS names. */
+export const passthroughResolver: RecipientResolver = (r) => {
+  if (r !== undefined && !isAddress(r, { strict: false })) {
+    throw new Error(`ENS resolution is not configured; received "${r}"`)
+  }
+  return Promise.resolve(r as Address | undefined)
+}
+
+/**
+ * Low-level utility to resolve an ENS name or hex address to a checksummed hex address.
+ * Use this when you manage your own viem PublicClient (e.g. inside providers or scripts).
+ *
+ * If you have an {@link Actions} instance, prefer `actions.ens.getAddress()` instead —
+ * it handles client lookup and fallback automatically from your chain configuration.
+ *
+ * Hex addresses (0x...) are returned as-is after format validation.
+ * ENS names require a mainnet public client for on-chain resolution.
+ * @param input - Hex address (0x...) or ENS name (e.g. "vitalik.eth")
+ * @param mainnetClient - Public client connected to Ethereum mainnet (required for ENS names)
+ * @returns Resolved hex address
+ * @throws {EnsNotConfiguredError} If mainnet client is not provided
+ * @throws {EnsResolutionError} If the name is invalid or cannot be resolved
+ * @throws {EnsRpcError} If the RPC call fails
+ */
+export async function resolveAddress(
+  input: Address | EnsName,
+  mainnetClient?: PublicClient,
+): Promise<Address> {
+  if (isAddress(input, { strict: false })) return input
+
+  if (!mainnetClient) throw new EnsNotConfiguredError()
+
+  const normalized = (() => {
+    try {
+      return normalize(input)
+    } catch (cause) {
+      throw new EnsResolutionError(
+        `Invalid address or ENS name: "${input}"`,
+        input,
+        { cause },
+      )
+    }
+  })()
+
+  const resolved = await mainnetClient
+    .getEnsAddress({ name: normalized })
+    .catch((cause: unknown) => {
+      throw new EnsRpcError(
+        `ENS resolution failed for "${input}": RPC error`,
+        input,
+        { cause },
+      )
+    })
+
+  if (!resolved)
+    throw new EnsResolutionError(
+      `ENS name "${input}" could not be resolved`,
+      input,
+    )
+  if (isAddressEqual(resolved, zeroAddress)) {
+    throw new EnsResolutionError(
+      `ENS name "${input}" resolved to the zero address`,
+      input,
+    )
+  }
+  return resolved
+}