Add viem fallback client helper

packages/core/README.md

@@ -0,0 +1,96 @@
+# @goodwidget/core
+
+Runtime helpers for GoodWidget providers, host detection, wallet context, and viem client setup.
+
+## viem fallback clients
+
+`createViemFallbackClient` wraps viem `createPublicClient` and `createWalletClient` so callers get a fallback HTTP transport built from cached Chainlist RPC URLs for the requested chain.
+
+The helper accepts a small key-value storage adapter. On initialization it reads cached RPC metadata from storage. If the cache is missing or older than 1 day, it starts a background refresh from Chainlist. Client creation waits for that first refresh only when no cached RPCs are available for the requested chain.
+
+```ts
+import { createViemFallbackClient } from '@goodwidget/core/viemFallbackClient'
+import { celo } from 'viem/chains'
+
+const viemClient = createViemFallbackClient(localStorage, {
+  onError(error) {
+    console.warn('RPC refresh failed', error)
+  },
+})
+
+const publicClient = await viemClient.createPublicClient({
+  chain: celo,
+  fallbackRpcs: ['https://forno.celo.org'],
+})
+```
+
+The same helper can create wallet clients. Any viem wallet client option, such as `account`, can be passed through.
+
+```ts
+import { privateKeyToAccount } from 'viem/accounts'
+import { celo } from 'viem/chains'
+
+const account = privateKeyToAccount('0x...')
+
+const walletClient = await viemClient.createWalletClient({
+  account,
+  chain: celo,
+  fallbackRpcs: ['https://forno.celo.org'],
+})
+```
+
+If you pass `transport`, the wrapper leaves it unchanged and does not create a fallback transport for that client.
+
+```ts
+import { http } from 'viem'
+import { celo } from 'viem/chains'
+
+const client = await viemClient.createPublicClient({
+  chain: celo,
+  transport: http('https://forno.celo.org'),
+})
+```
+
+## Storage adapters
+
+The adapter supports browser-style storage and Worker-style KV storage.
+
+```ts
+createViemFallbackClient(localStorage)
+```
+
+```ts
+createViemFallbackClient({
+  get: (key) => env.KV.get(key, 'json'),
+  put: (key, value) => env.KV.put(key, value),
+})
+```
+
+Cached values use this shape:
+
+```ts
+type ViemRpcCacheEntry = {
+  fetchedAt: string
+  rpcs: Array<{
+    chainId: number
+    rpcs: string[]
+  }>
+}
+```
+
+Only HTTPS RPC URLs are used. URLs containing Chainlist template placeholders are ignored.
+
+## Options
+
+```ts
+createViemFallbackClient(storage, {
+  cacheKey: 'goodwidget:viem-rpcs',
+  chainlistRpcsUrl: 'https://chainlist.org/rpcs.json',
+  refreshIntervalMs: 24 * 60 * 60 * 1000,
+  fetchTimeoutMs: 10_000,
+  fetch: globalThis.fetch,
+  onError: console.warn,
+})
+```
+
+`chainlistRpcsUrl` is intended for Chainlist's HTTPS RPC JSON endpoint. The helper blocks non-HTTPS URLs and hosts outside the expected Chainlist domain.

packages/core/package.json

@@ -15,6 +15,11 @@
       "types": "./dist/wagmi.d.ts",
       "import": "./dist/wagmi.js",
       "require": "./dist/wagmi.cjs"
+    },
+    "./viemFallbackClient": {
+      "types": "./dist/viemFallbackClient.d.ts",
+      "import": "./dist/viemFallbackClient.js",
+      "require": "./dist/viemFallbackClient.cjs"
     }
   },
   "scripts": {
@@ -35,7 +40,8 @@
   },
   "dependencies": {
     "@goodwidget/ui": "workspace:*",
-    "tamagui": "1.121.0"
+    "tamagui": "1.121.0",
+    "viem": "^2.0.0"
   },
   "devDependencies": {
     "react": "^18.3.0",

packages/core/src/index.ts

@@ -2,6 +2,16 @@ export { GoodWidgetProvider } from './provider'
 export type { WalletContextValue, HostContextValue, GoodWidgetContextValue } from './provider'
 export { useWallet, useHost, useGoodWidget } from './hooks'
 export { detectHost } from './detect'
+export { createViemFallbackClient } from './viemFallbackClient'
+export type {
+  CachedChainRpcs,
+  ViemFallbackClient,
+  ViemFallbackClientOptions,
+  ViemFallbackPublicClientParameters,
+  ViemFallbackStorage,
+  ViemFallbackWalletClientParameters,
+  ViemRpcCacheEntry,
+} from './viemFallbackClient'
 
 export type {
   EIP1193Provider,