@trezo/evm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Holiday
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,264 @@
+# @trezo/evm
+
+A **high‑performance, type‑safe EVM state orchestration layer** for modern Web3 applications.
+
+`@trezo/evm` provides a unified interface for **smart‑contract interactions**, **wallet connections**, and **reactive state management**, while keeping your application logic independent from specific wallet kits.
+
+## Core Architecture
+
+`@trezo/evm` is built around a **Factory Pattern** that generates a specialized hook and provider for your specific smart contract.
+
+### Store Layer
+
+A lightweight **Zustand-based store** that synchronizes:
+
+- Wallet state
+- Provider instances
+- Contract abstractions
+
+### Factory Layer
+
+Generates **fully type-safe wrappers** for your contract ABI, ensuring:
+
+- Compile‑time safety
+- Autocomplete for contract functions
+- Strict argument validation
+
+### Kit Bridge
+
+An abstraction layer that allows switching wallet kits without modifying application logic.
+
+Supported kits can include:
+
+- ConnectKit
+- Reown (AppKit)
+- Additional kits **coming soon**
+
+### Dynamic Loading
+
+Wallet kits and their heavy dependencies are **dynamically imported only when required**, ensuring:
+
+- Minimal initial bundle size
+- Faster page loads
+- Better tree‑shaking
+
+## Installation
+
+Install using your preferred package manager.
+
+```bash
+pnpm add @trezo/evm
+```
+
+## Usage
+
+### 1. Unified Configuration
+
+Initialize your dApp by defining:
+
+- Contract address
+- Contract ABI
+- Supported chains
+- Wallet kit configuration
+
+Each wallet kit may require **different configuration fields**.
+
+### Example: ConnectKit
+
+```ts
+"use client"; // Required for Next.js
+
+import { create, EvmChains } from "@trezo/evm";
+
+const MyContractAbi = [...] as const;
+
+export const evmConfig = create({
+  address: "0x...",
+  abi: MyContractAbi,
+  chains: [EvmChains.optimismSepolia],
+  kit: {
+    name: "connectkit",
+    config: {
+      projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID,
+      metadata: {
+        appName: "Trezo Dapp",
+        appIcon: "https://...",
+        appDescription: "...",
+        appUrl: "https://..."
+      }
+    }
+  }
+});
+
+export const { Provider, ConnectButton } = evmConfig;
+```
+
+### Example: Reown (AppKit)
+
+```ts
+export const evmConfig = create({
+  address: "0x...",
+  abi: MyContractAbi,
+  chains: [EvmChains.optimismSepolia],
+  kit: {
+    name: "reown",
+    config: {
+      projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID,
+      ssr: true,
+      metadata: {
+        name: "Trezo",
+        description: "...",
+        url: "https://...",
+        icons: ["https://..."],
+      },
+    },
+  },
+});
+
+export const { Provider, ConnectButton } = evmConfig;
+```
+
+### 2. Provider Injection
+
+Wrap your application (or a specific route) with the generated `Provider`.
+
+This provider handles:
+
+- Wallet kit initialization
+- State synchronization
+- Provider injection
+
+```tsx
+import { Provider } from "./evm.config";
+
+export default function Layout({ children }) {
+  return <Provider>{children}</Provider>;
+}
+```
+
+### 3. Contract Orchestration (Hooks)
+
+The `evmConfig()` hook exposes the reactive interface for interacting with:
+
+- Smart contracts
+- Wallet state
+- Web3 provider
+
+```ts
+const { call, wallet, web3Provider } = evmConfig();
+```
+
+### Wallet State
+
+Access wallet connection status and account details.
+
+```ts
+const { isConnected, isConnecting, address, chainId, error } = wallet.account;
+```
+
+The wallet state automatically updates when the user:
+
+- Connects a wallet
+- Switches accounts
+- Changes networks
+
+### Web3 Provider Availability
+
+Check if the user has an injected wallet provider (MetaMask, Rabby, etc).
+
+```ts
+const { isAvailable, error } = web3Provider;
+
+if (!isAvailable) {
+  console.log("No wallet installed:", error?.message);
+}
+```
+
+## Read Operations (Queries)
+
+Execute **type-safe contract read operations**.
+
+Arguments must match the ABI signature.
+
+```ts
+const result = await call.queryFn("getBalance", [address]);
+
+if (result.data) {
+  console.log(result.data);
+}
+```
+
+Read operations use:
+
+- Configured RPC URL
+- OR the connected wallet provider
+
+### Write Operations (Mutations)
+
+Execute **state-changing transactions**.
+
+These require a connected wallet.
+
+```ts
+const tx = await call.mutateFn("transfer", [to, amount]);
+
+if (tx.data) {
+  console.log("Transaction Hash:", tx.data.hash);
+}
+```
+
+The orchestration layer automatically handles:
+
+- Signer injection
+- Gas estimation
+- Transaction sending
+
+### Real-time Event Listening
+
+Listen to contract events with automatic polling fallback when RPC filters are not supported.
+
+```ts
+useEffect(() => {
+  const unwatch = call.listenFn("Transfer", (from, to, value) => {
+    console.log(`Transfer detected: ${value} from ${from} to ${to}`);
+  });
+
+  return () => unwatch();
+}, []);
+```
+
+## 4. Custom ConnectButton (Render Props)
+
+The default `ConnectButton` works out-of-the-box, but you can build fully custom UI using **render props**.
+
+```tsx
+import { formatAddress } from "@trezo/evm";
+
+<ConnectButton>
+  {({ isConnected, ensName, address, open }) => (
+    <button onClick={open} className="custom-style">
+      {isConnected ? (ensName ?? formatAddress(address)) : "Connect Wallet"}
+    </button>
+  )}
+</ConnectButton>;
+```
+
+This allows complete control over:
+
+- UI design
+- Styling
+- Button behavior
+
+while still using the wallet kit's internal logic.
+
+## Design Goals
+
+`@trezo/evm` is designed to provide:
+
+- Type-safe contract interactions
+- Wallet-kit agnostic architecture
+- Minimal bundle size
+- Composable Web3 state
+- Excellent developer experience
+
+---

package/dist/chunk-I6Z24RI3.mjs

@@ -0,0 +1,26 @@
+// src/components/KitBridge.tsx
+import { useEffect } from "react";
+import { useAccount, useWalletClient } from "wagmi";
+import { ethers } from "ethers";
+function KitBridge({
+  onConnect,
+  onDisconnect
+}) {
+  const { address, chainId, isConnected } = useAccount();
+  const { data: walletClient } = useWalletClient();
+  useEffect(() => {
+    if (!isConnected || !address || !chainId || !walletClient) {
+      onDisconnect();
+      return;
+    }
+    const provider = new ethers.BrowserProvider(walletClient);
+    provider.getSigner().then((signer) => {
+      onConnect(address, chainId, signer);
+    });
+  }, [isConnected, address, chainId, walletClient]);
+  return null;
+}
+
+export {
+  KitBridge
+};

package/dist/connectkit.provider-6R2D3NSB.mjs

@@ -0,0 +1,63 @@
+"use client";
+import {
+  KitBridge
+} from "./chunk-I6Z24RI3.mjs";
+
+// src/components/providers/connectkit.provider.tsx
+import { WagmiProvider, createConfig, http } from "wagmi";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import {
+  ConnectKitProvider,
+  getDefaultConfig,
+  ConnectKitButton
+} from "connectkit";
+import { jsx, jsxs } from "react/jsx-runtime";
+function createConnectkitProvider(kitConfig, chains, rpcUrl, bridgeProps) {
+  const wagmiConfig = createConfig(
+    getDefaultConfig({
+      chains,
+      transports: Object.fromEntries(chains.map((c) => [c.id, http(rpcUrl)])),
+      walletConnectProjectId: kitConfig.config.projectId,
+      appName: kitConfig.config.metadata.appName,
+      appDescription: kitConfig.config.metadata.appDescription,
+      appUrl: kitConfig.config.metadata.appUrl,
+      appIcon: kitConfig.config.metadata.appIcon
+    })
+  );
+  const queryClient = new QueryClient();
+  const Provider = ({ children }) => /* @__PURE__ */ jsx(WagmiProvider, { config: wagmiConfig, children: /* @__PURE__ */ jsx(QueryClientProvider, { client: queryClient, children: /* @__PURE__ */ jsxs(ConnectKitProvider, { children: [
+    /* @__PURE__ */ jsx(KitBridge, { ...bridgeProps }),
+    children
+  ] }) }) });
+  const ConnectButton = ({
+    children,
+    ...props
+  }) => {
+    if (children) {
+      return /* @__PURE__ */ jsx(ConnectKitButton.Custom, { children: ({
+        isConnected,
+        isConnecting,
+        show,
+        hide,
+        address,
+        ensName,
+        chain
+      }) => children({
+        isConnected,
+        isConnecting,
+        address,
+        ensName,
+        chain,
+        open: show ?? (() => {
+        }),
+        close: hide ?? (() => {
+        })
+      }) });
+    }
+    return /* @__PURE__ */ jsx(ConnectKitButton, { ...props });
+  };
+  return { Provider, ConnectButton };
+}
+export {
+  createConnectkitProvider
+};

package/dist/index.d.mts

@@ -0,0 +1,281 @@
+import { Abi, ExtractAbiFunctionNames, AbiParametersToPrimitiveTypes, ExtractAbiFunction, Address, ExtractAbiEventNames, ExtractAbiEvent } from 'abitype';
+export { Abi, AbiParameterToPrimitiveType, AbiParametersToPrimitiveTypes, ExtractAbiEvent, ExtractAbiEventNames, ExtractAbiFunction, ExtractAbiFunctionNames } from 'abitype';
+import * as Chains from 'viem/chains';
+import { ethers } from 'ethers';
+import React from 'react';
+
+type EvmAbiType = Abi;
+type EvmAbiFunctionArgsTuple<TAbi extends Abi, FnName extends ExtractAbiFunctionNames<TAbi>> = AbiParametersToPrimitiveTypes<ExtractAbiFunction<TAbi, FnName>["inputs"]>;
+type EvmAbiFunctionReturn<TAbi extends EvmAbiType, FnName extends ExtractAbiFunctionNames<TAbi>> = ExtractAbiFunction<TAbi, FnName>["outputs"] extends readonly [] ? void : AbiParametersToPrimitiveTypes<ExtractAbiFunction<TAbi, FnName>["outputs"]>[0];
+
+type ConnectkitConfig = {
+    projectId: string;
+    metadata: {
+        appName: string;
+        appIcon?: string;
+        appDescription?: string;
+        appUrl?: string;
+    };
+};
+
+type ReownConfig = {
+    projectId: string;
+    ssr?: boolean;
+    metadata: {
+        name: string;
+        description: string;
+        url: string;
+        icons: string[];
+    };
+};
+
+/**
+ * ---------------------------------------------------------------------------
+ * ⚠️  AUTO-GENERATED FILE — DO NOT EDIT MANUALLY
+ * ---------------------------------------------------------------------------
+ *
+ * Generated by:
+ *   scripts/genokit.ts
+ *
+ * Any manual changes will be overwritten.
+ *
+ * To update kits:
+ *   1. Add/remove files in src/kits/
+ *   2. Run:
+ *        pnpm tsx scripts/genokit.ts
+ *
+ * ---------------------------------------------------------------------------
+ */
+
+type EvmKitConfigType = {
+    name: "connectkit";
+    config: ConnectkitConfig;
+} | {
+    name: "reown";
+    config: ReownConfig;
+};
+
+declare const EvmChains: typeof Chains;
+type EvmAddressType = Address;
+type EvmChainsType = typeof EvmChains;
+type EvmConfigType<TAbi extends EvmAbiType> = {
+    abi: TAbi;
+    address: EvmAddressType;
+    chains: [Chains.Chain, ...Chains.Chain[]];
+    rpcUrl?: string;
+    kit: EvmKitConfigType;
+};
+
+type EvmStoreType<TAbi extends EvmAbiType> = {
+    wallet: {
+        isConnected: boolean;
+        isConnecting: boolean;
+        address?: EvmAddressType;
+        chainId?: number;
+        error?: Error;
+    };
+    provider: {
+        isAvailable: boolean;
+        error?: Error;
+    };
+    _signer?: ethers.Signer;
+    _provider?: ethers.Provider;
+    _contract?: ethers.Contract;
+    _abi?: TAbi;
+};
+
+declare function create<TAbi extends EvmAbiType>(config: EvmConfigType<TAbi>): {
+    (): {
+        call: {
+            queryFn: <FnName extends ExtractAbiFunctionNames<TAbi, "view" | "pure">>(functionName: FnName, args: EvmAbiFunctionArgsTuple<TAbi, FnName>) => Promise<{
+                data?: EvmAbiFunctionReturn<TAbi, FnName>;
+                error?: Error;
+            }>;
+            mutateFn: <FnName extends ExtractAbiFunctionNames<TAbi, "nonpayable" | "payable">>(functionName: FnName, args: EvmAbiFunctionArgsTuple<TAbi, FnName>) => Promise<{
+                data?: {
+                    hash: string;
+                };
+                error?: Error;
+            }>;
+            listenFn: <EventName extends ExtractAbiEventNames<TAbi>>(eventName: EventName, listener: (...args: AbiParametersToPrimitiveTypes<ExtractAbiEvent<TAbi, EventName>["inputs"]>) => void) => (() => void);
+        };
+        web3Provider: {
+            isAvailable: boolean;
+            error?: Error;
+        };
+        wallet: {
+            account: {
+                isConnected: boolean;
+                isConnecting: boolean;
+                address?: EvmAddressType;
+                chainId?: number;
+                error?: Error;
+            };
+        };
+    };
+    call: {
+        queryFn: <FnName extends ExtractAbiFunctionNames<TAbi, "view" | "pure">>(functionName: FnName, args: EvmAbiFunctionArgsTuple<TAbi, FnName>) => Promise<{
+            data?: EvmAbiFunctionReturn<TAbi, FnName>;
+            error?: Error;
+        }>;
+        mutateFn: <FnName extends ExtractAbiFunctionNames<TAbi, "nonpayable" | "payable">>(functionName: FnName, args: EvmAbiFunctionArgsTuple<TAbi, FnName>) => Promise<{
+            data?: {
+                hash: string;
+            };
+            error?: Error;
+        }>;
+        listenFn: <EventName extends ExtractAbiEventNames<TAbi>>(eventName: EventName, listener: (...args: AbiParametersToPrimitiveTypes<ExtractAbiEvent<TAbi, EventName>["inputs"]>) => void) => (() => void);
+    };
+    getState: () => EvmStoreType<TAbi>;
+    subscribe: (onStoreChange: () => void) => () => void;
+    Provider: React.FC<{
+        children: React.ReactNode;
+    }>;
+    ConnectButton: React.FC<{
+        label?: string;
+        showBalance?: boolean;
+        showAvatar?: boolean;
+        children?: (props: any) => React.ReactNode;
+    }>;
+} & {
+    call: {
+        queryFn: <FnName extends ExtractAbiFunctionNames<TAbi, "view" | "pure">>(functionName: FnName, args: EvmAbiFunctionArgsTuple<TAbi, FnName>) => Promise<{
+            data?: EvmAbiFunctionReturn<TAbi, FnName>;
+            error?: Error;
+        }>;
+        mutateFn: <FnName extends ExtractAbiFunctionNames<TAbi, "nonpayable" | "payable">>(functionName: FnName, args: EvmAbiFunctionArgsTuple<TAbi, FnName>) => Promise<{
+            data?: {
+                hash: string;
+            };
+            error?: Error;
+        }>;
+        listenFn: <EventName extends ExtractAbiEventNames<TAbi>>(eventName: EventName, listener: (...args: AbiParametersToPrimitiveTypes<ExtractAbiEvent<TAbi, EventName>["inputs"]>) => void) => (() => void);
+    };
+    getState: () => EvmStoreType<TAbi>;
+    subscribe: (onStoreChange: () => void) => () => void;
+    Provider: React.FC<{
+        children: React.ReactNode;
+    }>;
+    ConnectButton: React.FC<{
+        label?: string;
+        showBalance?: boolean;
+        showAvatar?: boolean;
+        children?: (props: any) => React.ReactNode;
+    }>;
+};
+
+/**
+ * Throws an Error with a specified message.
+ *
+ * This utility can be used to enforce required parameters or invalid states.
+ *
+ * @param message - Optional custom error message. Defaults to `"An unexpected error occurred"`.
+ *
+ * @throws Always throws an `Error` with the provided message.
+ *
+ * @example
+ * throwError("Invalid contract address");
+ * // Throws Error: "Invalid contract address"
+ *
+ * @example
+ * throwError();
+ * // Throws Error: "An unexpected error occurred"
+ */
+declare function throwError(message?: string): never;
+/**
+ * mapEthersError
+ * ------------------------------------------------------------
+ * Converts low-level Ethers.js / RPC / wallet errors into
+ * human-readable messages suitable for UI display.
+ *
+ * Ethereum libraries such as ethers.js emit structured errors
+ * that include a `code` property. These codes represent
+ * categories such as:
+ *
+ * - Blockchain execution errors
+ * - Wallet interaction errors
+ * - RPC/network failures
+ * - Argument validation problems
+ *
+ * This utility normalizes those errors into friendly messages.
+ *
+ * References:
+ * https://docs.ethers.org/v6/api/utils/errors/
+ */
+declare const mapEthersError: (error: any) => string;
+
+interface PollConfig {
+    provider: ethers.Provider;
+    contract: ethers.Contract;
+    eventName: string;
+    intervalMs?: number;
+}
+/**
+ * Manually polls for logs when eth_newFilter is unavailable
+ */
+declare const createEventPoller: ({ provider, contract, eventName, intervalMs }: PollConfig, listener: (...args: any[]) => void) => () => void;
+
+/**
+ * Converts a value from Wei to Ether.
+ *
+ * Uses `ethers.formatEther` to format the smallest Ethereum unit (Wei)
+ * into a human-readable Ether value.
+ *
+ * @param num - The value in Wei.
+ *
+ * @returns A string representing the value converted to Ether.
+ *
+ * @example
+ * fromWei(1000000000000000000)
+ * // "1.0"
+ */
+declare const fromWei: (value: bigint | string | number, decimals?: number) => string;
+/**
+ * Converts a value from Ether to Wei.
+ *
+ * Uses `ethers.parseEther` to convert a human-readable Ether value
+ * into Wei, the smallest Ethereum unit.
+ *
+ * @param num - The Ether value to convert.
+ *
+ * @returns A bigint representing the value in Wei.
+ *
+ * @example
+ * toWei(1)
+ * // 1000000000000000000n
+ */
+declare const toWei: (value: string, decimals?: number) => bigint;
+/**
+ * Formats an Ethereum address into a shortened, human-readable string.
+ *
+ * Keeps the first 4 characters of the address and a specified number of characters at the end.
+ * The middle (or end) can be replaced with a custom separator. Supported separators
+ * are `"..."`, `"-"`, `">"`, `"→"`.
+ *
+ * @param address - The full Ethereum address to format.
+ * @param options - Optional formatting options:
+ *   - `endChars` - Number of characters to keep at the end (default `6`).
+ *   - `separator` - String to place between start and end. Suggestions: `"..." | "-" | ">" | "→"` (default `"..."`).
+ *   - `position` - `"middle"` (default) or `"end"`. `"end"` appends the separator after the start characters.
+ *
+ * @returns The formatted address string.
+ *
+ * @example
+ * formatAddress("0x742d35Cc6634C0532925a3b844Bc454e4438f44e")
+ * // "0x74d3...38f44e"
+ *
+ * @example
+ * formatAddress("0x742d35Cc6634C0532925a3b844Bc454e4438f44e", { endChars: 4, separator: "→" })
+ * // "0x74d3→f44e"
+ *
+ * @example
+ * formatAddress("0x742d35Cc6634C0532925a3b844Bc454e4438f44e", { endChars: 0, separator: "...", position: "end" })
+ * // "0x74d3..."
+ */
+declare function formatAddress(address: string, options?: {
+    endChars?: number;
+    separator?: "..." | "-" | ">" | "→";
+    position?: "middle" | "end";
+}): string;
+
+export { type EvmAbiFunctionArgsTuple, type EvmAbiFunctionReturn, type EvmAbiType, type EvmAddressType, EvmChains, type EvmChainsType, type EvmConfigType, type EvmStoreType, create, createEventPoller, formatAddress, fromWei, mapEthersError, throwError, toWei };