@tuwaio/orbit-evm 0.2.22 → 0.3.1

package/README.md

@@ -1,18 +1,19 @@
 # @tuwaio/orbit-evm
 
 [![NPM Version](https://img.shields.io/npm/v/@tuwaio/orbit-evm.svg)](https://www.npmjs.com/package/@tuwaio/orbit-evm)
-[![License](https://img.shields.io/npm/l/@tuwaio/orbit-evm.svg)](./LICENSE)
+[![License](https://img.shields.io/npm/l/@tuwaio/orbit-evm.svg)](https://github.com/TuwaIO/orbit/blob/main/packages/orbit-evm/LICENSE)
 
-`@tuwaio/orbit-evm` provides concrete implementations of low-level EVM-specific communication primitives for Layer 2 (L2) of the TUWA Orbit stack. Engineered strictly on top of **`@wagmi/core`** and **`viem`**, this package provides deterministic chain switching, custom Viem client generation, and cached ENS metadata resolution, while enforcing a complete exclusion of legacy libraries like `ethers.js` or `web3.js`.
+`@tuwaio/orbit-evm` is the EVM Layer 2 (L2) package of **Orbit Utils**, the Stage 1 primitives layer of the TUWA ecosystem. It wraps **`viem`** and **`@wagmi/core`** into small, framework-agnostic helpers: cached public clients, chain switching, ENS resolution, and ERC-4337 smart accounts built on Solady with a Pimlico bundler and paymaster. It does not use `ethers.js` or `web3.js`.
 
 ---
 
 ## 🏛️ Core Capabilities
 
-- **Viem Client Optimization:** Creates and caches high-performance `viem` public clients (`createViemClient`) to minimize request latency and avoid duplicate RPC instantiation.
-- **ENS Metadata Engine:** Direct lookup utilities (`getName`, `getAvatar`, `getAddress`) on the Ethereum Mainnet context with local caching.
-- **Deterministic Chain Switching:** Low-level utility (`checkAndSwitchChain`) to enforce network alignment with the target blockchain, requesting wallet configurations dynamically.
-- **Strict Compile-Time Types:** Fully integrated with TypeScript standards v5.9+ and native Viem/Wagmi typings.
+- **Public clients:** `createViemClient` returns a cached `viem` public client per chain, so repeated reads do not create new clients.
+- **Chain alignment:** `checkAndSwitchChain` asks the connected wallet to switch networks only when it is on a different chain, and throws a readable error when the user rejects.
+- **ENS resolution:** `getName`, `getAvatar` and `getAddress` always resolve against Ethereum Mainnet and cache results in memory; `isEnsName` tells names and addresses apart.
+- **ERC-4337 smart accounts:** `createPimlicoSmartAccountClient` sets up a Solady smart account (EntryPoint v0.7), a bundler client and an optional gas-sponsoring paymaster in one call. Bundler and paymaster clients are cached in memory per endpoint. The building blocks (`createSoladySmartAccount`, `createBundlerRpcClient`, `createPimlicoPaymasterClient`, `createPimlicoRpcUrl`, `clearBundlerCache`) are exported for custom setups.
+- **Chain lists:** `getEvmChains` and `isEvmChainList` extract and detect EVM chain IDs in mixed multi-chain configurations.
 
 ---
 
@@ -23,56 +24,123 @@ pnpm add @tuwaio/orbit-evm @wagmi/core viem
 ```
 
 > [!IMPORTANT]
-> `@wagmi/core` and `viem` are peer dependencies and must be installed alongside `@tuwaio/orbit-evm`.
+> `viem` (2.x) and `@wagmi/core` (3.x) are peer dependencies and must be installed alongside `@tuwaio/orbit-evm`.
 
 ---
 
-## 🚀 Technical Integration
+## 🚀 Usage
 
-### Cached Client Generation & Routing
-
-Create a public client wrapper to route queries to EVM nodes:
+### Cached public client
 
 ```typescript
 import { createViemClient } from '@tuwaio/orbit-evm';
-import { mainnet } from 'viem/chains';
+import { mainnet, sepolia } from 'viem/chains';
+
+const chains = [mainnet, sepolia] as const;
 
-// Retrieve cached or new Viem Public Client
-const client = createViemClient(mainnet);
+// Returns undefined (and logs a warning) if the chain ID is not in `chains`.
+const client = createViemClient(sepolia.id, chains);
+const blockNumber = await client?.getBlockNumber();
 ```
 
-### Deterministic Chain Switcher
+The client uses the chain's default RPC URL. The cache is keyed by chain ID and is rebuilt when that URL changes.
 
-Enforce that the wallet's connection context matches the requested chain:
+### Chain switching
 
 ```typescript
-import { checkAndSwitchChain } from '@tuwaio/orbit-evm';
 import { type Config } from '@wagmi/core';
+import { checkAndSwitchChain } from '@tuwaio/orbit-evm';
 
-declare const config: Config;
+declare const wagmiConfig: Config;
 
-async function switchNetwork(targetChainId: number) {
-  try {
-    await checkAndSwitchChain(targetChainId, config);
-    console.log(`Execution context successfully switched to: ${targetChainId}`);
-  } catch (error) {
-    console.error('Chain switch rejected:', error);
-  }
+try {
+  await checkAndSwitchChain(11155111, wagmiConfig);
+} catch (error) {
+  // "User rejected the request to switch network." or a generic switch error (original error in `cause`).
+  console.error(error);
 }
 ```
 
----
+### ENS resolution
+
+```typescript
+import { getAddress, getAvatar, getName, isEnsName } from '@tuwaio/orbit-evm';
+import { mainnet } from 'viem/chains';
+
+const chains = [mainnet] as const;
+
+const name = await getName('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', chains); // "vitalik.eth" or null
+const avatar = name ? await getAvatar(name, chains) : null;
+
+const input = 'vitalik.eth';
+const address = isEnsName(input) ? await getAddress(input, chains) : null; // lowercased address or null
+```
+
+Lookups use the mainnet entry of `chains` when present (so your own RPC URL is used), otherwise viem's default mainnet RPC.
+
+### ERC-4337 smart account with Pimlico
+
+```typescript
+import { type Config } from '@wagmi/core';
+import { createPimlicoSmartAccountClient } from '@tuwaio/orbit-evm';
+import { sepolia } from 'viem/chains';
+
+declare const wagmiConfig: Config;
+
+const { account, bundlerClient } = await createPimlicoSmartAccountClient({
+  chain: sepolia,
+  wagmiConfig, // or pass `walletClient` directly
+  apiKey: process.env.NEXT_PUBLIC_PIMLICO_API_KEY, // or `bundlerUrl` for your own bundler endpoint
+});
+
+const userOpHash = await bundlerClient.sendUserOperation({
+  account,
+  calls: [{ to: '0x0000000000000000000000000000000000000000', value: 0n }],
+});
+const receipt = await bundlerClient.waitForUserOperationReceipt({ hash: userOpHash });
+```
+
+- A connected wallet is required: the EOA signs for the smart account.
+- Gas sponsorship (`sponsor`) is on by default when `apiKey` or `bundlerUrl` is set. Without either, the public Pimlico endpoint is used and no paymaster is attached.
+- The smart account uses viem's Solady implementation with its default EntryPoint v0.7 (`entryPoint07Address`).
+- The account salt defaults to the owner address right-padded to 32 bytes (`pad(owner, { dir: 'right', size: 32 })`). This satisfies the Solady factory's owner-prefix check (`SaltDoesNotStartWith()`) and gives every owner a deterministic, unique account address. Pass `salt` to override it.
 
-## 🔧 API & Module Architecture
+> [!WARNING]
+> The Pimlico API key becomes part of the bundler URL used by the browser. Use a key restricted to your domains and sponsorship policies, or proxy the bundler through your backend and pass its address as `bundlerUrl`.
 
-`@tuwaio/orbit-evm` exposes the following modules:
+### Low-level bundler building blocks
 
-- **Chain Alignment:** `checkAndSwitchChain`.
-- **Client Factory:** `createViemClient`.
-- **ENS Resolvers:** `getAddress`, `getAvatar`, `getName`, `isEnsName`.
+```typescript
+import {
+  clearBundlerCache,
+  createBundlerRpcClient,
+  createPimlicoPaymasterClient,
+  createPimlicoRpcUrl,
+} from '@tuwaio/orbit-evm';
+
+// Resolution order: bundlerUrl → https://api.pimlico.io/v2/{chainId}/rpc?apikey=… → https://public.pimlico.io/v2/{chainId}/rpc
+const rpcUrl = createPimlicoRpcUrl({ chainId: 11155111, apiKey: process.env.PIMLICO_API_KEY });
+
+// Cached by resolved URL.
+const paymasterClient = createPimlicoPaymasterClient({ chainId: 11155111, apiKey: process.env.PIMLICO_API_KEY });
+
+// Cached by resolved URL, paymaster presence and client presence.
+const bundlerClient = createBundlerRpcClient({
+  chainId: 11155111,
+  apiKey: process.env.PIMLICO_API_KEY,
+  paymaster: paymasterClient,
+});
+
+// Drops cached URLs, bundler and paymaster clients (e.g. after rotating the API key).
+clearBundlerCache();
+```
 
 ---
 
+## 📚 API Reference
+
+Every export, with signatures and types generated from the source, is documented at **[orbit.docs.tuwa.io/packages/orbit-evm](https://orbit.docs.tuwa.io/packages/orbit-evm)**. For a full walkthrough of sovereign account abstraction with Orbit, Pulsar and Quasar, see the [ERC-4337 guide](https://docs.tuwa.io/guides/erc-4337-sovereign-account-abstraction).
+
 ## 📄 License
 
-Licensed under the **Apache-2.0 License**. See the [LICENSE](./LICENSE) file for details.
+Licensed under the **Apache-2.0 License**. See the [LICENSE](https://github.com/TuwaIO/orbit/blob/main/packages/orbit-evm/LICENSE) file for details.

package/dist/index.d.mts

@@ -1,13 +1,148 @@
-import { Chain } from 'viem/chains';
 import { Config } from '@wagmi/core';
-import { PublicClient, Address, Hex } from 'viem';
+import { HttpTransport, Client, PublicClient, WalletClient, Hex, Chain, Address } from 'viem';
+import { BundlerClientConfig, toSoladySmartAccount, ToSoladySmartAccountReturnType, BundlerClient, PaymasterClient } from 'viem/account-abstraction';
+import { Chain as Chain$1 } from 'viem/chains';
 
 /**
- * Get EVM chain IDs from app chains configuration
+ * @file Utilities for Pimlico and ERC-4337 Bundler client instantiation with local in-memory caching.
  */
-declare function getEvmChains(appChains?: readonly [Chain, ...Chain[]]): number[];
+
+/**
+ * Exported alias for Solady Smart Account type.
+ */
+type SoladySmartAccount = ToSoladySmartAccountReturnType;
+/**
+ * Configuration options for generating Pimlico Bundler RPC URLs.
+ */
+interface PimlicoUrlConfig {
+    /** Target EVM chain ID (e.g. 1 for Ethereum Mainnet, 11155111 for Sepolia). */
+    chainId: number;
+    /** Optional Pimlico API key. If omitted, falls back to public RPC or bundlerUrl. */
+    apiKey?: string;
+    /** Optional explicit custom bundler RPC URL that takes precedence. */
+    bundlerUrl?: string;
+}
+/**
+ * Optional additional configuration forwarded to Viem's createBundlerClient.
+ */
+type BundlerRpcClientConfig = PimlicoUrlConfig & Partial<Omit<BundlerClientConfig<HttpTransport>, 'transport' | 'client'>> & {
+    /** Optional execution client or public client used for fee estimation. */
+    client?: Client | PublicClient;
+};
+/**
+ * Parameters for creating a Solady ERC-4337 Smart Account.
+ */
+interface CreateSoladySmartAccountParams {
+    /** The client used to interact with the blockchain. */
+    client: Parameters<typeof toSoladySmartAccount>[0]['client'];
+    /** The connected WalletClient (e.g. from Wagmi or browser provider) representing the EOA owner. */
+    walletClient: WalletClient;
+    /**
+     * Optional 32-byte salt for deterministic counterfactual deployment.
+     * Defaults to right-padded EOA address to satisfy Solady factory owner-prefix verification.
+     */
+    salt?: Hex;
+}
+/**
+ * Configuration options for instantiating a Pimlico-powered ERC-4337 Smart Account client.
+ */
+interface PimlicoSmartAccountClientConfig {
+    /** Target EVM chain. */
+    chain: Chain;
+    /** The connected WalletClient representing the EOA signer. */
+    walletClient?: WalletClient;
+    /** Wagmi Config used to resolve the walletClient if not explicitly provided. */
+    wagmiConfig?: Config;
+    /** Optional public client for reading chain state. If omitted, one is created automatically. */
+    client?: PublicClient | Client;
+    /** Optional Pimlico API key. */
+    apiKey?: string;
+    /** Optional explicit custom bundler RPC URL. */
+    bundlerUrl?: string;
+    /** Optional RPC URL for public client execution transport (e.g., Alchemy / Infura). */
+    rpcUrl?: string;
+    /**
+     * Whether to configure and attach Pimlico paymaster for gas sponsorship.
+     * Defaults to true if apiKey or bundlerUrl is provided.
+     */
+    sponsor?: boolean;
+    /** Optional 32-byte salt for Solady smart account. */
+    salt?: Hex;
+}
+/**
+ * Result object returned by `createPimlicoSmartAccountClient`.
+ */
+interface PimlicoSmartAccountClientResult {
+    /** The instantiated Solady smart account instance. */
+    account: SoladySmartAccount;
+    /** The configured Viem Bundler client. */
+    bundlerClient: BundlerClient<HttpTransport>;
+    /** The public client used for chain state reads and fee estimation. */
+    publicClient: PublicClient;
+    /** The Pimlico paymaster client if gas sponsorship is enabled. */
+    paymasterClient?: PaymasterClient;
+}
+/**
+ * Creates and caches a Pimlico RPC URL based on provided configuration.
+ *
+ * Priority order:
+ * 1. Explicit `bundlerUrl` (if provided, returned directly).
+ * 2. Dedicated Pimlico endpoint `https://api.pimlico.io/v2/${chainId}/rpc?apikey=${apiKey}` (if apiKey provided).
+ * 3. Public community endpoint `https://public.pimlico.io/v2/${chainId}/rpc` (fallback).
+ *
+ * @param config - The Pimlico URL configuration.
+ * @returns The resolved Bundler RPC URL string.
+ */
+declare function createPimlicoRpcUrl(config: PimlicoUrlConfig): string;
+/**
+ * Creates or retrieves a cached Viem Bundler Client configured for the resolved Pimlico endpoint.
+ *
+ * @param config - Bundler URL and optional client configuration parameters.
+ * @returns Cached or newly instantiated BundlerClient.
+ */
+declare function createBundlerRpcClient(config: BundlerRpcClientConfig): BundlerClient<HttpTransport>;
+/**
+ * Creates or retrieves a cached Viem Paymaster Client configured with the resolved Pimlico RPC endpoint.
+ * Side effect: stores the client in an in-memory cache keyed by the resolved RPC URL (see `clearBundlerCache`).
+ *
+ * @param config - Pimlico URL configuration.
+ * @returns Cached or newly instantiated PaymasterClient configured for Pimlico gas sponsorship.
+ */
+declare function createPimlicoPaymasterClient(config: PimlicoUrlConfig): PaymasterClient;
+/**
+ * Instantiates a Solady ERC-4337 smart account with automatic wallet signing delegation
+ * and Solady factory-compliant deterministic salt.
+ *
+ * @param params - Configuration parameters including client and walletClient.
+ * @returns Promise resolving to the initialized SoladySmartAccount.
+ */
+declare function createSoladySmartAccount({ client, walletClient, salt, }: CreateSoladySmartAccountParams): Promise<SoladySmartAccount>;
+/**
+ * High-level orchestration utility that instantiates a Solady smart account,
+ * configures a Pimlico paymaster (sponsorship), and binds them to a Pimlico Bundler client.
+ *
+ * @param config - Configuration options including chain, wallet/wagmi, and Pimlico credentials.
+ * @returns Promise resolving to { account, bundlerClient, publicClient, paymasterClient }.
+ */
+declare function createPimlicoSmartAccountClient(config: PimlicoSmartAccountClientConfig): Promise<PimlicoSmartAccountClientResult>;
+/**
+ * Clears the in-memory caches of Pimlico URLs, Bundler clients and Paymaster clients.
+ * Useful for testing and resetting runtime state (e.g. after rotating an API key).
+ */
+declare function clearBundlerCache(): void;
+
 /**
- * Type guard to check if a chain list contains EVM chain IDs
+ * Gets the EVM chain IDs from an app's viem chain configuration.
+ *
+ * @param appChains - The viem chains configured in the app.
+ * @returns The positive numeric chain IDs, or an empty array if no chains are provided.
+ */
+declare function getEvmChains(appChains?: readonly [Chain$1, ...Chain$1[]]): number[];
+/**
+ * Type guard to check if a chain list contains EVM chain IDs.
+ *
+ * @param chains - Mixed list of chain identifiers.
+ * @returns `true` if the list is non-empty and contains only numbers.
  */
 declare function isEvmChainList(chains: (string | number)[]): chains is number[];
 
@@ -46,7 +181,7 @@ declare function checkAndSwitchChain(chainId: number, config: Config): Promise<v
  * @returns {import('viem').PublicClient | undefined} A viem PublicClient instance if a matching chain is found, otherwise undefined.
  * It will also log a warning to the console if the chain is not configured.
  */
-declare function createViemClient(chainId: number, chains: readonly [Chain, ...Chain[]]): PublicClient | undefined;
+declare function createViemClient(chainId: number, chains: readonly [Chain$1, ...Chain$1[]]): PublicClient | undefined;
 
 /**
  * @file This file contains utility functions for interacting with the Ethereum Name Service (ENS).
@@ -62,7 +197,7 @@ declare function createViemClient(chainId: number, chains: readonly [Chain, ...C
  * @param {readonly [Chain, ...Chain[]]} chains - The list of chains to use for client creation.
  * @returns {Promise<string | null>} The ENS name if found, otherwise null.
  */
-declare const getName: (address: Hex, chains: readonly [Chain, ...Chain[]]) => Promise<string | null>;
+declare const getName: (address: Hex, chains: readonly [Chain$1, ...Chain$1[]]) => Promise<string | null>;
 /**
  * Fetches the avatar URL for a given ENS name from the Ethereum Mainnet.
  * Includes caching for performance.
@@ -71,7 +206,7 @@ declare const getName: (address: Hex, chains: readonly [Chain, ...Chain[]]) => P
  * @param {readonly [Chain, ...Chain[]]} chains - The list of chains to use for client creation.
  * @returns {Promise<string | null>} The URL of the avatar image if found, otherwise null.
  */
-declare const getAvatar: (name: string, chains: readonly [Chain, ...Chain[]]) => Promise<string | null>;
+declare const getAvatar: (name: string, chains: readonly [Chain$1, ...Chain$1[]]) => Promise<string | null>;
 /**
  * Fetches the Ethereum address associated with a given ENS name from the Ethereum Mainnet.
  * Includes caching for performance.
@@ -80,7 +215,7 @@ declare const getAvatar: (name: string, chains: readonly [Chain, ...Chain[]]) =>
  * @param {readonly [Chain, ...Chain[]]} chains - The list of chains to use for client creation.
  * @returns {Promise<Address | null>} The associated Ethereum address (lowercase) or null if not found.
  */
-declare const getAddress: (name: string, chains: readonly [Chain, ...Chain[]]) => Promise<Address | null>;
+declare const getAddress: (name: string, chains: readonly [Chain$1, ...Chain$1[]]) => Promise<Address | null>;
 /**
  * A heuristic to check if a string is likely an ENS name.
  *
@@ -97,4 +232,4 @@ declare const getAddress: (name: string, chains: readonly [Chain, ...Chain[]]) =
  */
 declare const isEnsName: (nameOrAddress: string) => boolean;
 
-export { checkAndSwitchChain, createViemClient, getAddress, getAvatar, getEvmChains, getName, isEnsName, isEvmChainList };
+export { type BundlerRpcClientConfig, type CreateSoladySmartAccountParams, type PimlicoSmartAccountClientConfig, type PimlicoSmartAccountClientResult, type PimlicoUrlConfig, type SoladySmartAccount, checkAndSwitchChain, clearBundlerCache, createBundlerRpcClient, createPimlicoPaymasterClient, createPimlicoRpcUrl, createPimlicoSmartAccountClient, createSoladySmartAccount, createViemClient, getAddress, getAvatar, getEvmChains, getName, isEnsName, isEvmChainList };

package/dist/index.d.ts

@@ -1,13 +1,148 @@
-import { Chain } from 'viem/chains';
 import { Config } from '@wagmi/core';
-import { PublicClient, Address, Hex } from 'viem';
+import { HttpTransport, Client, PublicClient, WalletClient, Hex, Chain, Address } from 'viem';
+import { BundlerClientConfig, toSoladySmartAccount, ToSoladySmartAccountReturnType, BundlerClient, PaymasterClient } from 'viem/account-abstraction';
+import { Chain as Chain$1 } from 'viem/chains';
 
 /**
- * Get EVM chain IDs from app chains configuration
+ * @file Utilities for Pimlico and ERC-4337 Bundler client instantiation with local in-memory caching.
  */
-declare function getEvmChains(appChains?: readonly [Chain, ...Chain[]]): number[];
+
+/**
+ * Exported alias for Solady Smart Account type.
+ */
+type SoladySmartAccount = ToSoladySmartAccountReturnType;
+/**
+ * Configuration options for generating Pimlico Bundler RPC URLs.
+ */
+interface PimlicoUrlConfig {
+    /** Target EVM chain ID (e.g. 1 for Ethereum Mainnet, 11155111 for Sepolia). */
+    chainId: number;
+    /** Optional Pimlico API key. If omitted, falls back to public RPC or bundlerUrl. */
+    apiKey?: string;
+    /** Optional explicit custom bundler RPC URL that takes precedence. */
+    bundlerUrl?: string;
+}
+/**
+ * Optional additional configuration forwarded to Viem's createBundlerClient.
+ */
+type BundlerRpcClientConfig = PimlicoUrlConfig & Partial<Omit<BundlerClientConfig<HttpTransport>, 'transport' | 'client'>> & {
+    /** Optional execution client or public client used for fee estimation. */
+    client?: Client | PublicClient;
+};
+/**
+ * Parameters for creating a Solady ERC-4337 Smart Account.
+ */
+interface CreateSoladySmartAccountParams {
+    /** The client used to interact with the blockchain. */
+    client: Parameters<typeof toSoladySmartAccount>[0]['client'];
+    /** The connected WalletClient (e.g. from Wagmi or browser provider) representing the EOA owner. */
+    walletClient: WalletClient;
+    /**
+     * Optional 32-byte salt for deterministic counterfactual deployment.
+     * Defaults to right-padded EOA address to satisfy Solady factory owner-prefix verification.
+     */
+    salt?: Hex;
+}
+/**
+ * Configuration options for instantiating a Pimlico-powered ERC-4337 Smart Account client.
+ */
+interface PimlicoSmartAccountClientConfig {
+    /** Target EVM chain. */
+    chain: Chain;
+    /** The connected WalletClient representing the EOA signer. */
+    walletClient?: WalletClient;
+    /** Wagmi Config used to resolve the walletClient if not explicitly provided. */
+    wagmiConfig?: Config;
+    /** Optional public client for reading chain state. If omitted, one is created automatically. */
+    client?: PublicClient | Client;
+    /** Optional Pimlico API key. */
+    apiKey?: string;
+    /** Optional explicit custom bundler RPC URL. */
+    bundlerUrl?: string;
+    /** Optional RPC URL for public client execution transport (e.g., Alchemy / Infura). */
+    rpcUrl?: string;
+    /**
+     * Whether to configure and attach Pimlico paymaster for gas sponsorship.
+     * Defaults to true if apiKey or bundlerUrl is provided.
+     */
+    sponsor?: boolean;
+    /** Optional 32-byte salt for Solady smart account. */
+    salt?: Hex;
+}
+/**
+ * Result object returned by `createPimlicoSmartAccountClient`.
+ */
+interface PimlicoSmartAccountClientResult {
+    /** The instantiated Solady smart account instance. */
+    account: SoladySmartAccount;
+    /** The configured Viem Bundler client. */
+    bundlerClient: BundlerClient<HttpTransport>;
+    /** The public client used for chain state reads and fee estimation. */
+    publicClient: PublicClient;
+    /** The Pimlico paymaster client if gas sponsorship is enabled. */
+    paymasterClient?: PaymasterClient;
+}
+/**
+ * Creates and caches a Pimlico RPC URL based on provided configuration.
+ *
+ * Priority order:
+ * 1. Explicit `bundlerUrl` (if provided, returned directly).
+ * 2. Dedicated Pimlico endpoint `https://api.pimlico.io/v2/${chainId}/rpc?apikey=${apiKey}` (if apiKey provided).
+ * 3. Public community endpoint `https://public.pimlico.io/v2/${chainId}/rpc` (fallback).
+ *
+ * @param config - The Pimlico URL configuration.
+ * @returns The resolved Bundler RPC URL string.
+ */
+declare function createPimlicoRpcUrl(config: PimlicoUrlConfig): string;
+/**
+ * Creates or retrieves a cached Viem Bundler Client configured for the resolved Pimlico endpoint.
+ *
+ * @param config - Bundler URL and optional client configuration parameters.
+ * @returns Cached or newly instantiated BundlerClient.
+ */
+declare function createBundlerRpcClient(config: BundlerRpcClientConfig): BundlerClient<HttpTransport>;
+/**
+ * Creates or retrieves a cached Viem Paymaster Client configured with the resolved Pimlico RPC endpoint.
+ * Side effect: stores the client in an in-memory cache keyed by the resolved RPC URL (see `clearBundlerCache`).
+ *
+ * @param config - Pimlico URL configuration.
+ * @returns Cached or newly instantiated PaymasterClient configured for Pimlico gas sponsorship.
+ */
+declare function createPimlicoPaymasterClient(config: PimlicoUrlConfig): PaymasterClient;
+/**
+ * Instantiates a Solady ERC-4337 smart account with automatic wallet signing delegation
+ * and Solady factory-compliant deterministic salt.
+ *
+ * @param params - Configuration parameters including client and walletClient.
+ * @returns Promise resolving to the initialized SoladySmartAccount.
+ */
+declare function createSoladySmartAccount({ client, walletClient, salt, }: CreateSoladySmartAccountParams): Promise<SoladySmartAccount>;
+/**
+ * High-level orchestration utility that instantiates a Solady smart account,
+ * configures a Pimlico paymaster (sponsorship), and binds them to a Pimlico Bundler client.
+ *
+ * @param config - Configuration options including chain, wallet/wagmi, and Pimlico credentials.
+ * @returns Promise resolving to { account, bundlerClient, publicClient, paymasterClient }.
+ */
+declare function createPimlicoSmartAccountClient(config: PimlicoSmartAccountClientConfig): Promise<PimlicoSmartAccountClientResult>;
+/**
+ * Clears the in-memory caches of Pimlico URLs, Bundler clients and Paymaster clients.
+ * Useful for testing and resetting runtime state (e.g. after rotating an API key).
+ */
+declare function clearBundlerCache(): void;
+
 /**
- * Type guard to check if a chain list contains EVM chain IDs
+ * Gets the EVM chain IDs from an app's viem chain configuration.
+ *
+ * @param appChains - The viem chains configured in the app.
+ * @returns The positive numeric chain IDs, or an empty array if no chains are provided.
+ */
+declare function getEvmChains(appChains?: readonly [Chain$1, ...Chain$1[]]): number[];
+/**
+ * Type guard to check if a chain list contains EVM chain IDs.
+ *
+ * @param chains - Mixed list of chain identifiers.
+ * @returns `true` if the list is non-empty and contains only numbers.
  */
 declare function isEvmChainList(chains: (string | number)[]): chains is number[];
 
@@ -46,7 +181,7 @@ declare function checkAndSwitchChain(chainId: number, config: Config): Promise<v
  * @returns {import('viem').PublicClient | undefined} A viem PublicClient instance if a matching chain is found, otherwise undefined.
  * It will also log a warning to the console if the chain is not configured.
  */
-declare function createViemClient(chainId: number, chains: readonly [Chain, ...Chain[]]): PublicClient | undefined;
+declare function createViemClient(chainId: number, chains: readonly [Chain$1, ...Chain$1[]]): PublicClient | undefined;
 
 /**
  * @file This file contains utility functions for interacting with the Ethereum Name Service (ENS).
@@ -62,7 +197,7 @@ declare function createViemClient(chainId: number, chains: readonly [Chain, ...C
  * @param {readonly [Chain, ...Chain[]]} chains - The list of chains to use for client creation.
  * @returns {Promise<string | null>} The ENS name if found, otherwise null.
  */
-declare const getName: (address: Hex, chains: readonly [Chain, ...Chain[]]) => Promise<string | null>;
+declare const getName: (address: Hex, chains: readonly [Chain$1, ...Chain$1[]]) => Promise<string | null>;
 /**
  * Fetches the avatar URL for a given ENS name from the Ethereum Mainnet.
  * Includes caching for performance.
@@ -71,7 +206,7 @@ declare const getName: (address: Hex, chains: readonly [Chain, ...Chain[]]) => P
  * @param {readonly [Chain, ...Chain[]]} chains - The list of chains to use for client creation.
  * @returns {Promise<string | null>} The URL of the avatar image if found, otherwise null.
  */
-declare const getAvatar: (name: string, chains: readonly [Chain, ...Chain[]]) => Promise<string | null>;
+declare const getAvatar: (name: string, chains: readonly [Chain$1, ...Chain$1[]]) => Promise<string | null>;
 /**
  * Fetches the Ethereum address associated with a given ENS name from the Ethereum Mainnet.
  * Includes caching for performance.
@@ -80,7 +215,7 @@ declare const getAvatar: (name: string, chains: readonly [Chain, ...Chain[]]) =>
  * @param {readonly [Chain, ...Chain[]]} chains - The list of chains to use for client creation.
  * @returns {Promise<Address | null>} The associated Ethereum address (lowercase) or null if not found.
  */
-declare const getAddress: (name: string, chains: readonly [Chain, ...Chain[]]) => Promise<Address | null>;
+declare const getAddress: (name: string, chains: readonly [Chain$1, ...Chain$1[]]) => Promise<Address | null>;
 /**
  * A heuristic to check if a string is likely an ENS name.
  *
@@ -97,4 +232,4 @@ declare const getAddress: (name: string, chains: readonly [Chain, ...Chain[]]) =
  */
 declare const isEnsName: (nameOrAddress: string) => boolean;
 
-export { checkAndSwitchChain, createViemClient, getAddress, getAvatar, getEvmChains, getName, isEnsName, isEvmChainList };
+export { type BundlerRpcClientConfig, type CreateSoladySmartAccountParams, type PimlicoSmartAccountClientConfig, type PimlicoSmartAccountClientResult, type PimlicoUrlConfig, type SoladySmartAccount, checkAndSwitchChain, clearBundlerCache, createBundlerRpcClient, createPimlicoPaymasterClient, createPimlicoRpcUrl, createPimlicoSmartAccountClient, createSoladySmartAccount, createViemClient, getAddress, getAvatar, getEvmChains, getName, isEnsName, isEvmChainList };

package/dist/index.js

@@ -1 +1,2 @@
-'use strict';var core=require('@wagmi/core'),viem=require('viem'),chains=require('viem/chains'),ens=require('viem/ens');function C(e){return e!=null&&typeof e=="number"&&e>0}function E(e){return !e||e.length===0?[]:e.map(r=>r.id).filter(C)}function N(e){return e.length>0&&e.every(r=>typeof r=="number")}async function U(e,r){let{connector:t,chainId:o}=core.getConnection(r);if(t&&o!==e)try{await core.switchChain(r,{chainId:e});}catch(n){throw n.cause?.name==="UserRejectedRequestError"?new Error("User rejected the request to switch network.",{cause:n}):(console.error("Failed to switch network:",n),new Error("An error occurred while switching the network.",{cause:n}))}}var u=new Map;function s(e,r){let t=r.find(n=>n.id===e),o=u.get(e);if(o&&o.chain?.rpcUrls.default.http[0]===t?.rpcUrls.default.http[0])return o;if(t){let n=viem.createPublicClient({chain:t,transport:viem.http()});return u.set(e,n),n}console.warn(`createViemClient: No chain configuration found for chainId ${e}. A client could not be created.`);}var d=new Map,m=new Map,f=new Map,c=e=>{let r=e.find(t=>t.id===chains.mainnet.id);return r?s(chains.mainnet.id,[r]):s(chains.mainnet.id,[chains.mainnet])},D=async(e,r)=>{let t=c(r);if(!t)return null;let o=d.get(e);if(o!==void 0)return o;try{let n=await ens.getEnsName(t,{address:e});return d.set(e,n),n}catch(n){return console.error(`ENS name lookup failed for address ${e}:`,n),null}},G=async(e,r)=>{let t=c(r);if(!t)return null;let o=ens.normalize(e),n=m.get(o);if(n!==void 0)return n;try{let i=await ens.getEnsAvatar(t,{name:o});return m.set(o,i),i}catch(i){return console.error(`ENS avatar lookup failed for name ${e}:`,i),null}},I=async(e,r)=>{let t=c(r);if(!t)return null;let o=ens.normalize(e),n=f.get(o);if(n!==void 0)return n;try{let i=await ens.getEnsAddress(t,{name:o}),l=i?i.toLowerCase():null;return f.set(o,l),l}catch(i){return console.error(`ENS address lookup failed for name ${e}:`,i),null}},J=e=>e.includes(".")&&!viem.isAddress(e);exports.checkAndSwitchChain=U;exports.createViemClient=s;exports.getAddress=I;exports.getAvatar=G;exports.getEvmChains=E;exports.getName=D;exports.isEnsName=J;exports.isEvmChainList=N;
+'use strict';var core=require('@wagmi/core'),viem=require('viem'),accountAbstraction=require('viem/account-abstraction'),accounts=require('viem/accounts'),chains=require('viem/chains'),ens=require('viem/ens');var m=new Map,p=new Map,C=new Map;function K(e){return e.bundlerUrl?`custom:${e.bundlerUrl.trim()}`:`${e.chainId}:${e.apiKey?.trim()??"public"}`}function N(e){let t=f(e),r=!!e.paymaster,n=!!e.client;return `${t}:pm=${r}:client=${n}`}function f(e){let t=K(e),r=m.get(t);if(r)return r;let n;return e.bundlerUrl?n=e.bundlerUrl.trim():e.apiKey?n=`https://api.pimlico.io/v2/${e.chainId}/rpc?apikey=${e.apiKey.trim()}`:n=`https://public.pimlico.io/v2/${e.chainId}/rpc`,m.set(t,n),n}function R(e){let t=N(e),r=p.get(t);if(r)return r;let n=f(e),i={...e};delete i.bundlerUrl,delete i.apiKey;let a=accountAbstraction.createBundlerClient({...i,transport:viem.http(n)});return p.set(t,a),a}function k(e){let t=f(e),r=C.get(t);if(r)return r;let n=accountAbstraction.createPaymasterClient({transport:viem.http(t)});return C.set(t,n),n}async function M({client:e,walletClient:t,salt:r}){if(!t.account)throw new Error("WalletClient must have an active account.");let n=t.account,i=accounts.toAccount({address:n.address,async signMessage({message:o}){return t.signMessage({account:n,message:o})},async signTransaction(o){return t.signTransaction({account:n,...o})},async signTypedData(o){return t.signTypedData({account:n,...o})}}),a=r??viem.pad(n.address,{dir:"right",size:32});return accountAbstraction.toSoladySmartAccount({client:e,owner:i,salt:a})}async function X(e){let{chain:t,apiKey:r,bundlerUrl:n,rpcUrl:i,salt:a,sponsor:o=!!(r||n)}=e,l=e.walletClient;if(!l&&e.wagmiConfig&&(l=await core.getWalletClient(e.wagmiConfig,{chainId:t.id})),!l||!l.account)throw new Error("Active wallet connection with account is required (provide walletClient or wagmiConfig).");let u=e.client??viem.createPublicClient({chain:t,transport:i?viem.http(i):viem.http()}),x=await M({client:u,walletClient:l,salt:a}),d=o&&(r||n)?k({chainId:t.id,apiKey:r,bundlerUrl:n}):void 0,S=R({chainId:t.id,apiKey:r,bundlerUrl:n,client:u,...d?{paymaster:d}:{}});return {account:x,bundlerClient:S,publicClient:u,paymasterClient:d}}function Y(){m.clear(),p.clear(),C.clear();}function I(e){return e!=null&&typeof e=="number"&&e>0}function _(e){return !e||e.length===0?[]:e.map(t=>t.id).filter(I)}function ee(e){return e.length>0&&e.every(t=>typeof t=="number")}async function ie(e,t){let{connector:r,chainId:n}=core.getConnection(t);if(r&&n!==e)try{await core.switchChain(t,{chainId:e});}catch(i){throw i?.cause?.name==="UserRejectedRequestError"?new Error("User rejected the request to switch network.",{cause:i}):(console.error("Failed to switch network:",i),new Error("An error occurred while switching the network.",{cause:i}))}}var g=new Map;function h(e,t){let r=t.find(i=>i.id===e),n=g.get(e);if(n&&n.chain?.rpcUrls.default.http[0]===r?.rpcUrls.default.http[0])return n;if(r){let i=viem.createPublicClient({chain:r,transport:viem.http()});return g.set(e,i),i}console.warn(`createViemClient: No chain configuration found for chainId ${e}. A client could not be created.`);}var w=new Map,P=new Map,b=new Map,y=e=>{let t=e.find(r=>r.id===chains.mainnet.id);return t?h(chains.mainnet.id,[t]):h(chains.mainnet.id,[chains.mainnet])},he=async(e,t)=>{let r=y(t);if(!r)return null;let n=w.get(e);if(n!==void 0)return n;try{let i=await ens.getEnsName(r,{address:e});return w.set(e,i),i}catch(i){return console.error(`ENS name lookup failed for address ${e}:`,i),null}},ye=async(e,t)=>{let r=y(t);if(!r)return null;let n=ens.normalize(e),i=P.get(n);if(i!==void 0)return i;try{let a=await ens.getEnsAvatar(r,{name:n});return P.set(n,a),a}catch(a){return console.error(`ENS avatar lookup failed for name ${e}:`,a),null}},ge=async(e,t)=>{let r=y(t);if(!r)return null;let n=ens.normalize(e),i=b.get(n);if(i!==void 0)return i;try{let a=await ens.getEnsAddress(r,{name:n}),o=a?a.toLowerCase():null;return b.set(n,o),o}catch(a){return console.error(`ENS address lookup failed for name ${e}:`,a),null}},we=e=>e.includes(".")&&!viem.isAddress(e);
+exports.checkAndSwitchChain=ie;exports.clearBundlerCache=Y;exports.createBundlerRpcClient=R;exports.createPimlicoPaymasterClient=k;exports.createPimlicoRpcUrl=f;exports.createPimlicoSmartAccountClient=X;exports.createSoladySmartAccount=M;exports.createViemClient=h;exports.getAddress=ge;exports.getAvatar=ye;exports.getEvmChains=_;exports.getName=he;exports.isEnsName=we;exports.isEvmChainList=ee;

package/dist/index.mjs

@@ -1 +1,2 @@
-import {getConnection,switchChain}from'@wagmi/core';import {createPublicClient,http,isAddress}from'viem';import {mainnet}from'viem/chains';import {getEnsName,normalize,getEnsAvatar,getEnsAddress}from'viem/ens';function C(e){return e!=null&&typeof e=="number"&&e>0}function E(e){return !e||e.length===0?[]:e.map(r=>r.id).filter(C)}function N(e){return e.length>0&&e.every(r=>typeof r=="number")}async function U(e,r){let{connector:t,chainId:o}=getConnection(r);if(t&&o!==e)try{await switchChain(r,{chainId:e});}catch(n){throw n.cause?.name==="UserRejectedRequestError"?new Error("User rejected the request to switch network.",{cause:n}):(console.error("Failed to switch network:",n),new Error("An error occurred while switching the network.",{cause:n}))}}var u=new Map;function s(e,r){let t=r.find(n=>n.id===e),o=u.get(e);if(o&&o.chain?.rpcUrls.default.http[0]===t?.rpcUrls.default.http[0])return o;if(t){let n=createPublicClient({chain:t,transport:http()});return u.set(e,n),n}console.warn(`createViemClient: No chain configuration found for chainId ${e}. A client could not be created.`);}var d=new Map,m=new Map,f=new Map,c=e=>{let r=e.find(t=>t.id===mainnet.id);return r?s(mainnet.id,[r]):s(mainnet.id,[mainnet])},D=async(e,r)=>{let t=c(r);if(!t)return null;let o=d.get(e);if(o!==void 0)return o;try{let n=await getEnsName(t,{address:e});return d.set(e,n),n}catch(n){return console.error(`ENS name lookup failed for address ${e}:`,n),null}},G=async(e,r)=>{let t=c(r);if(!t)return null;let o=normalize(e),n=m.get(o);if(n!==void 0)return n;try{let i=await getEnsAvatar(t,{name:o});return m.set(o,i),i}catch(i){return console.error(`ENS avatar lookup failed for name ${e}:`,i),null}},I=async(e,r)=>{let t=c(r);if(!t)return null;let o=normalize(e),n=f.get(o);if(n!==void 0)return n;try{let i=await getEnsAddress(t,{name:o}),l=i?i.toLowerCase():null;return f.set(o,l),l}catch(i){return console.error(`ENS address lookup failed for name ${e}:`,i),null}},J=e=>e.includes(".")&&!isAddress(e);export{U as checkAndSwitchChain,s as createViemClient,I as getAddress,G as getAvatar,E as getEvmChains,D as getName,J as isEnsName,N as isEvmChainList};
+import {getWalletClient,getConnection,switchChain}from'@wagmi/core';import {http,pad,createPublicClient,isAddress}from'viem';import {createBundlerClient,createPaymasterClient,toSoladySmartAccount}from'viem/account-abstraction';import {toAccount}from'viem/accounts';import {mainnet}from'viem/chains';import {getEnsName,normalize,getEnsAvatar,getEnsAddress}from'viem/ens';var m=new Map,p=new Map,C=new Map;function K(e){return e.bundlerUrl?`custom:${e.bundlerUrl.trim()}`:`${e.chainId}:${e.apiKey?.trim()??"public"}`}function N(e){let t=f(e),r=!!e.paymaster,n=!!e.client;return `${t}:pm=${r}:client=${n}`}function f(e){let t=K(e),r=m.get(t);if(r)return r;let n;return e.bundlerUrl?n=e.bundlerUrl.trim():e.apiKey?n=`https://api.pimlico.io/v2/${e.chainId}/rpc?apikey=${e.apiKey.trim()}`:n=`https://public.pimlico.io/v2/${e.chainId}/rpc`,m.set(t,n),n}function R(e){let t=N(e),r=p.get(t);if(r)return r;let n=f(e),i={...e};delete i.bundlerUrl,delete i.apiKey;let a=createBundlerClient({...i,transport:http(n)});return p.set(t,a),a}function k(e){let t=f(e),r=C.get(t);if(r)return r;let n=createPaymasterClient({transport:http(t)});return C.set(t,n),n}async function M({client:e,walletClient:t,salt:r}){if(!t.account)throw new Error("WalletClient must have an active account.");let n=t.account,i=toAccount({address:n.address,async signMessage({message:o}){return t.signMessage({account:n,message:o})},async signTransaction(o){return t.signTransaction({account:n,...o})},async signTypedData(o){return t.signTypedData({account:n,...o})}}),a=r??pad(n.address,{dir:"right",size:32});return toSoladySmartAccount({client:e,owner:i,salt:a})}async function X(e){let{chain:t,apiKey:r,bundlerUrl:n,rpcUrl:i,salt:a,sponsor:o=!!(r||n)}=e,l=e.walletClient;if(!l&&e.wagmiConfig&&(l=await getWalletClient(e.wagmiConfig,{chainId:t.id})),!l||!l.account)throw new Error("Active wallet connection with account is required (provide walletClient or wagmiConfig).");let u=e.client??createPublicClient({chain:t,transport:i?http(i):http()}),x=await M({client:u,walletClient:l,salt:a}),d=o&&(r||n)?k({chainId:t.id,apiKey:r,bundlerUrl:n}):void 0,S=R({chainId:t.id,apiKey:r,bundlerUrl:n,client:u,...d?{paymaster:d}:{}});return {account:x,bundlerClient:S,publicClient:u,paymasterClient:d}}function Y(){m.clear(),p.clear(),C.clear();}function I(e){return e!=null&&typeof e=="number"&&e>0}function _(e){return !e||e.length===0?[]:e.map(t=>t.id).filter(I)}function ee(e){return e.length>0&&e.every(t=>typeof t=="number")}async function ie(e,t){let{connector:r,chainId:n}=getConnection(t);if(r&&n!==e)try{await switchChain(t,{chainId:e});}catch(i){throw i?.cause?.name==="UserRejectedRequestError"?new Error("User rejected the request to switch network.",{cause:i}):(console.error("Failed to switch network:",i),new Error("An error occurred while switching the network.",{cause:i}))}}var g=new Map;function h(e,t){let r=t.find(i=>i.id===e),n=g.get(e);if(n&&n.chain?.rpcUrls.default.http[0]===r?.rpcUrls.default.http[0])return n;if(r){let i=createPublicClient({chain:r,transport:http()});return g.set(e,i),i}console.warn(`createViemClient: No chain configuration found for chainId ${e}. A client could not be created.`);}var w=new Map,P=new Map,b=new Map,y=e=>{let t=e.find(r=>r.id===mainnet.id);return t?h(mainnet.id,[t]):h(mainnet.id,[mainnet])},he=async(e,t)=>{let r=y(t);if(!r)return null;let n=w.get(e);if(n!==void 0)return n;try{let i=await getEnsName(r,{address:e});return w.set(e,i),i}catch(i){return console.error(`ENS name lookup failed for address ${e}:`,i),null}},ye=async(e,t)=>{let r=y(t);if(!r)return null;let n=normalize(e),i=P.get(n);if(i!==void 0)return i;try{let a=await getEnsAvatar(r,{name:n});return P.set(n,a),a}catch(a){return console.error(`ENS avatar lookup failed for name ${e}:`,a),null}},ge=async(e,t)=>{let r=y(t);if(!r)return null;let n=normalize(e),i=b.get(n);if(i!==void 0)return i;try{let a=await getEnsAddress(r,{name:n}),o=a?a.toLowerCase():null;return b.set(n,o),o}catch(a){return console.error(`ENS address lookup failed for name ${e}:`,a),null}},we=e=>e.includes(".")&&!isAddress(e);
+export{ie as checkAndSwitchChain,Y as clearBundlerCache,R as createBundlerRpcClient,k as createPimlicoPaymasterClient,f as createPimlicoRpcUrl,X as createPimlicoSmartAccountClient,M as createSoladySmartAccount,h as createViemClient,ge as getAddress,ye as getAvatar,_ as getEvmChains,he as getName,we as isEnsName,ee as isEvmChainList};

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@tuwaio/orbit-evm",
-  "version": "0.2.22",
+  "version": "0.3.1",
   "private": false,
   "author": "Oleksandr Tkach",
   "license": "Apache-2.0",
-  "description": "Layer 2 (L2) of the TUWA Ecosystem. Low-level EVM-specific communication primitives powered strictly by viem and wagmi.",
+  "description": "L2 EVM package of Orbit Utils (TUWA): cached viem clients, chain switching, ENS resolution and ERC-4337 smart accounts (Solady + Pimlico bundler/paymaster), built on viem and @wagmi/core.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -16,9 +16,18 @@
     "socket.json"
   ],
   "keywords": [
+    "tuwa",
+    "orbit",
     "web3",
-    "typescript",
     "evm",
+    "viem",
+    "wagmi",
+    "ens",
+    "erc-4337",
+    "account-abstraction",
+    "pimlico",
+    "solady",
+    "typescript",
     "headless"
   ],
   "repository": {
@@ -41,13 +50,14 @@
     "viem": "2.x.x"
   },
   "devDependencies": {
-    "@wagmi/core": "^3.6.4",
+    "@wagmi/core": "^3.6.5",
     "tsup": "^8.5.1",
-    "typescript": "^6.0.3",
-    "viem": "^2.55.11"
+    "typescript": "6.0.3",
+    "viem": "^2.56.9"
   },
   "scripts": {
     "start": "tsup src/index.ts --watch",
-    "build": "tsup"
+    "build": "tsup",
+    "test": "vitest run"
   }
 }