@tuwaio/orbit-evm 0.2.22 → 1.0.0-feat-update-alpha.2.addd21d

package/README.md

@@ -61,6 +61,26 @@ async function switchNetwork(targetChainId: number) {
 }
 ```
 
+### ERC-4337 Pimlico Bundler Client
+
+Instantiate and cache Viem Bundler clients with automated Pimlico URL resolution:
+
+```typescript
+import { createBundlerRpcClient, createPimlicoRpcUrl } from '@tuwaio/orbit-evm';
+
+// Generate or retrieve cached Pimlico RPC endpoint
+const rpcUrl = createPimlicoRpcUrl({
+  chainId: 11155111,
+  apiKey: 'pim_test_key_123',
+});
+
+// Retrieve cached or new Viem Bundler Client (with in-memory cache)
+const bundlerClient = createBundlerRpcClient({
+  chainId: 11155111,
+  apiKey: 'pim_test_key_123',
+});
+```
+
 ---
 
 ## 🔧 API & Module Architecture
@@ -70,6 +90,7 @@ async function switchNetwork(targetChainId: number) {
 - **Chain Alignment:** `checkAndSwitchChain`.
 - **Client Factory:** `createViemClient`.
 - **ENS Resolvers:** `getAddress`, `getAvatar`, `getName`, `isEnsName`.
+- **ERC-4337 Account Abstraction:** `createPimlicoRpcUrl`, `createBundlerRpcClient`, `clearBundlerCache`.
 
 ---
 

package/dist/index.d.mts

@@ -1,6 +1,51 @@
+import { HttpTransport, PublicClient, Address, Hex } from 'viem';
+import { BundlerClientConfig, BundlerClient } from 'viem/account-abstraction';
 import { Chain } from 'viem/chains';
 import { Config } from '@wagmi/core';
-import { PublicClient, Address, Hex } from 'viem';
+
+/**
+ * @file Utilities for Pimlico and ERC-4337 Bundler client instantiation with local in-memory caching.
+ */
+
+/**
+ * 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'>>;
+/**
+ * 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>;
+/**
+ * Clears the in-memory cache of Pimlico URLs and Bundler clients.
+ * Useful for testing and resetting runtime state.
+ */
+declare function clearBundlerCache(): void;
 
 /**
  * Get EVM chain IDs from app chains configuration
@@ -97,4 +142,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 PimlicoUrlConfig, checkAndSwitchChain, clearBundlerCache, createBundlerRpcClient, createPimlicoRpcUrl, createViemClient, getAddress, getAvatar, getEvmChains, getName, isEnsName, isEvmChainList };

package/dist/index.d.ts

@@ -1,6 +1,51 @@
+import { HttpTransport, PublicClient, Address, Hex } from 'viem';
+import { BundlerClientConfig, BundlerClient } from 'viem/account-abstraction';
 import { Chain } from 'viem/chains';
 import { Config } from '@wagmi/core';
-import { PublicClient, Address, Hex } from 'viem';
+
+/**
+ * @file Utilities for Pimlico and ERC-4337 Bundler client instantiation with local in-memory caching.
+ */
+
+/**
+ * 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'>>;
+/**
+ * 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>;
+/**
+ * Clears the in-memory cache of Pimlico URLs and Bundler clients.
+ * Useful for testing and resetting runtime state.
+ */
+declare function clearBundlerCache(): void;
 
 /**
  * Get EVM chain IDs from app chains configuration
@@ -97,4 +142,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 PimlicoUrlConfig, checkAndSwitchChain, clearBundlerCache, createBundlerRpcClient, createPimlicoRpcUrl, 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 viem=require('viem'),accountAbstraction=require('viem/account-abstraction'),core=require('@wagmi/core'),chains=require('viem/chains'),ens=require('viem/ens');var l=new Map,c=new Map;function w(e){return e.bundlerUrl?`custom:${e.bundlerUrl.trim()}`:`${e.chainId}:${e.apiKey?.trim()??"public"}`}function b(e){let n=w(e),i=l.get(n);if(i)return i;let r;return e.bundlerUrl?r=e.bundlerUrl.trim():e.apiKey?r=`https://api.pimlico.io/v2/${e.chainId}/rpc?apikey=${e.apiKey.trim()}`:r=`https://public.pimlico.io/v2/${e.chainId}/rpc`,l.set(n,r),r}function K(e){let n=b(e),i=c.get(n);if(i)return i;let r={...e};delete r.bundlerUrl,delete r.apiKey;let t=accountAbstraction.createBundlerClient({...r,transport:viem.http(n)});return c.set(n,t),t}function M(){l.clear(),c.clear();}function x(e){return e!=null&&typeof e=="number"&&e>0}function S(e){return !e||e.length===0?[]:e.map(n=>n.id).filter(x)}function I(e){return e.length>0&&e.every(n=>typeof n=="number")}async function j(e,n){let{connector:i,chainId:r}=core.getConnection(n);if(i&&r!==e)try{await core.switchChain(n,{chainId:e});}catch(t){throw t?.cause?.name==="UserRejectedRequestError"?new Error("User rejected the request to switch network.",{cause:t}):(console.error("Failed to switch network:",t),new Error("An error occurred while switching the network.",{cause:t}))}}var m=new Map;function s(e,n){let i=n.find(t=>t.id===e),r=m.get(e);if(r&&r.chain?.rpcUrls.default.http[0]===i?.rpcUrls.default.http[0])return r;if(i){let t=viem.createPublicClient({chain:i,transport:viem.http()});return m.set(e,t),t}console.warn(`createViemClient: No chain configuration found for chainId ${e}. A client could not be created.`);}var p=new Map,h=new Map,C=new Map,u=e=>{let n=e.find(i=>i.id===chains.mainnet.id);return n?s(chains.mainnet.id,[n]):s(chains.mainnet.id,[chains.mainnet])},Z=async(e,n)=>{let i=u(n);if(!i)return null;let r=p.get(e);if(r!==void 0)return r;try{let t=await ens.getEnsName(i,{address:e});return p.set(e,t),t}catch(t){return console.error(`ENS name lookup failed for address ${e}:`,t),null}},_=async(e,n)=>{let i=u(n);if(!i)return null;let r=ens.normalize(e),t=h.get(r);if(t!==void 0)return t;try{let o=await ens.getEnsAvatar(i,{name:r});return h.set(r,o),o}catch(o){return console.error(`ENS avatar lookup failed for name ${e}:`,o),null}},ee=async(e,n)=>{let i=u(n);if(!i)return null;let r=ens.normalize(e),t=C.get(r);if(t!==void 0)return t;try{let o=await ens.getEnsAddress(i,{name:r}),d=o?o.toLowerCase():null;return C.set(r,d),d}catch(o){return console.error(`ENS address lookup failed for name ${e}:`,o),null}},re=e=>e.includes(".")&&!viem.isAddress(e);
+exports.checkAndSwitchChain=j;exports.clearBundlerCache=M;exports.createBundlerRpcClient=K;exports.createPimlicoRpcUrl=b;exports.createViemClient=s;exports.getAddress=ee;exports.getAvatar=_;exports.getEvmChains=S;exports.getName=Z;exports.isEnsName=re;exports.isEvmChainList=I;

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 {http,createPublicClient,isAddress}from'viem';import {createBundlerClient}from'viem/account-abstraction';import {getConnection,switchChain}from'@wagmi/core';import {mainnet}from'viem/chains';import {getEnsName,normalize,getEnsAvatar,getEnsAddress}from'viem/ens';var l=new Map,c=new Map;function w(e){return e.bundlerUrl?`custom:${e.bundlerUrl.trim()}`:`${e.chainId}:${e.apiKey?.trim()??"public"}`}function b(e){let n=w(e),i=l.get(n);if(i)return i;let r;return e.bundlerUrl?r=e.bundlerUrl.trim():e.apiKey?r=`https://api.pimlico.io/v2/${e.chainId}/rpc?apikey=${e.apiKey.trim()}`:r=`https://public.pimlico.io/v2/${e.chainId}/rpc`,l.set(n,r),r}function K(e){let n=b(e),i=c.get(n);if(i)return i;let r={...e};delete r.bundlerUrl,delete r.apiKey;let t=createBundlerClient({...r,transport:http(n)});return c.set(n,t),t}function M(){l.clear(),c.clear();}function x(e){return e!=null&&typeof e=="number"&&e>0}function S(e){return !e||e.length===0?[]:e.map(n=>n.id).filter(x)}function I(e){return e.length>0&&e.every(n=>typeof n=="number")}async function j(e,n){let{connector:i,chainId:r}=getConnection(n);if(i&&r!==e)try{await switchChain(n,{chainId:e});}catch(t){throw t?.cause?.name==="UserRejectedRequestError"?new Error("User rejected the request to switch network.",{cause:t}):(console.error("Failed to switch network:",t),new Error("An error occurred while switching the network.",{cause:t}))}}var m=new Map;function s(e,n){let i=n.find(t=>t.id===e),r=m.get(e);if(r&&r.chain?.rpcUrls.default.http[0]===i?.rpcUrls.default.http[0])return r;if(i){let t=createPublicClient({chain:i,transport:http()});return m.set(e,t),t}console.warn(`createViemClient: No chain configuration found for chainId ${e}. A client could not be created.`);}var p=new Map,h=new Map,C=new Map,u=e=>{let n=e.find(i=>i.id===mainnet.id);return n?s(mainnet.id,[n]):s(mainnet.id,[mainnet])},Z=async(e,n)=>{let i=u(n);if(!i)return null;let r=p.get(e);if(r!==void 0)return r;try{let t=await getEnsName(i,{address:e});return p.set(e,t),t}catch(t){return console.error(`ENS name lookup failed for address ${e}:`,t),null}},_=async(e,n)=>{let i=u(n);if(!i)return null;let r=normalize(e),t=h.get(r);if(t!==void 0)return t;try{let o=await getEnsAvatar(i,{name:r});return h.set(r,o),o}catch(o){return console.error(`ENS avatar lookup failed for name ${e}:`,o),null}},ee=async(e,n)=>{let i=u(n);if(!i)return null;let r=normalize(e),t=C.get(r);if(t!==void 0)return t;try{let o=await getEnsAddress(i,{name:r}),d=o?o.toLowerCase():null;return C.set(r,d),d}catch(o){return console.error(`ENS address lookup failed for name ${e}:`,o),null}},re=e=>e.includes(".")&&!isAddress(e);
+export{j as checkAndSwitchChain,M as clearBundlerCache,K as createBundlerRpcClient,b as createPimlicoRpcUrl,s as createViemClient,ee as getAddress,_ as getAvatar,S as getEvmChains,Z as getName,re as isEnsName,I as isEvmChainList};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuwaio/orbit-evm",
-  "version": "0.2.22",
+  "version": "1.0.0-feat-update-alpha.2.addd21d",
   "private": false,
   "author": "Oleksandr Tkach",
   "license": "Apache-2.0",
@@ -41,13 +41,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"
+    "viem": "^2.56.3"
   },
   "scripts": {
     "start": "tsup src/index.ts --watch",
-    "build": "tsup"
+    "build": "tsup",
+    "test": "vitest run"
   }
 }