@tuwaio/orbit-evm 0.2.13 → 0.2.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +38 -102
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,142 +1,78 @@
1
- # Orbit EVM
1
+ # @tuwaio/orbit-evm
2
2
 
3
3
  [![NPM Version](https://img.shields.io/npm/v/@tuwaio/orbit-evm.svg)](https://www.npmjs.com/package/@tuwaio/orbit-evm)
4
4
  [![License](https://img.shields.io/npm/l/@tuwaio/orbit-evm.svg)](./LICENSE)
5
- [![Build Status](https://img.shields.io/github/actions/workflow/status/TuwaIO/orbit/release.yml?branch=main)](https://github.com/TuwaIO/orbit/actions)
6
5
 
7
- EVM-specific adapter implementation and utilities for the **Orbit Utils** ecosystem by **TUWA**. Provides helpers for interacting with EVM-compatible blockchains like Ethereum, Polygon, BSC, etc., leveraging **wagmi** and **viem**.
6
+ `@tuwaio/orbit-evm` provides concrete implementations of low-level EVM-specific communication primitives for Tier 2 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`.
8
7
 
9
8
  ---
10
9
 
11
- ## 🏛️ What is `@tuwaio/orbit-evm`?
10
+ ## 🏛️ Core Capabilities
12
11
 
13
- `@tuwaio/orbit-evm` provides concrete implementations and utilities tailored specifically for **EVM (Ethereum Virtual Machine)** compatible blockchains. It acts as the EVM adapter within the Orbit Utils ecosystem, designed to simplify interactions with networks like Ethereum, Polygon, Binance Smart Chain, and others.
14
-
15
- Built with **TypeScript** and leveraging powerful libraries like **`@wagmi/core`** and **`viem`**, this package offers specialized tools for common EVM tasks required in web3 UI development.
16
-
17
- ---
18
-
19
- ## ✨ Key Features
20
-
21
- - **Chain Switching:** Utility (`checkAndSwitchChain`) to prompt users to switch their wallet to the correct EVM network.
22
- - **Viem Public Client Management:** Efficiently creates and caches `viem` Public Clients for read-only blockchain interactions (`createViemClient`).
23
- - **ENS (Ethereum Name Service) Utilities:**
24
- - Resolve ENS names to addresses (`getAddress`).
25
- - Reverse resolve addresses to primary ENS names (`getName`).
26
- - Fetch ENS avatar URLs (`getAvatar`).
27
- - Basic ENS name format checking (`isEnsName`).
28
- - All ENS lookups target Ethereum Mainnet and include caching.
29
- - **Built on Wagmi & Viem:** Leverages the robust and type-safe functionalities provided by `@wagmi/core` and `viem`.
30
- - **Type-Safe Development:** Fully typed with TypeScript 5.9+.
31
- - **Optimized Bundling:** Built with `tsup` for efficient CommonJS and ESM outputs with tree-shaking.
12
+ - **Viem Client Optimization:** Creates and caches high-performance `viem` public clients (`createViemClient`) to minimize request latency and avoid duplicate RPC instantiation.
13
+ - **ENS Metadata Engine:** Direct lookup utilities (`getName`, `getAvatar`, `getAddress`) on the Ethereum Mainnet context with local caching.
14
+ - **Deterministic Chain Switching:** Low-level utility (`checkAndSwitchChain`) to enforce network alignment with the target blockchain, requesting wallet configurations dynamically.
15
+ - **Strict Compile-Time Types:** Fully integrated with TypeScript standards v5.9+ and native Viem/Wagmi typings.
32
16
 
33
17
  ---
34
18
 
35
19
  ## 💾 Installation
36
20
 
37
- ### Requirements
38
-
39
- - Node.js 20-24
40
- - TypeScript 5.9+
41
-
42
21
  ```bash
43
- # Using pnpm (recommended), but you can use npm, yarn or bun as well
44
22
  pnpm add @tuwaio/orbit-evm @wagmi/core viem
45
- ````
23
+ ```
46
24
 
47
- *Note: `@wagmi/core` and `viem` are **peer dependencies** and must be installed alongside `@tuwaio/orbit-evm`*.
25
+ > [!IMPORTANT]
26
+ > `@wagmi/core` and `viem` are peer dependencies and must be installed alongside `@tuwaio/orbit-evm`.
48
27
 
49
- -----
28
+ ---
50
29
 
51
- ## 🚀 Quick Start
30
+ ## 🚀 Technical Integration
52
31
 
53
- ### Check and Switch Network
32
+ ### Cached Client Generation & Routing
54
33
 
55
- Ensure the user's wallet is connected to the desired EVM chain (e.g., Sepolia testnet, ID 11155111).
34
+ Create a public client wrapper to route queries to EVM nodes:
56
35
 
57
36
  ```typescript
58
- import { checkAndSwitchChain } from '@tuwaio/orbit-evm';
59
- import { type Config } from '@wagmi/core'; // Assuming you have your wagmi config
60
-
61
- // Assume 'wagmiConfig' is your initialized wagmi Config object
62
- declare const wagmiConfig: Config;
63
- const targetChainId = 11155111; // Sepolia
64
-
65
- async function ensureCorrectChain() {
66
- try {
67
- await checkAndSwitchChain(targetChainId, wagmiConfig);
68
- console.log(`Wallet is now connected to chain ID ${targetChainId}`);
69
- // Proceed with actions requiring the target chain
70
- } catch (error) {
71
- console.error('Failed to switch chain:', error);
72
- // Handle the error (e.g., show a message to the user)
73
- }
74
- }
75
-
76
- ensureCorrectChain();
37
+ import { createViemClient } from '@tuwaio/orbit-evm';
38
+ import { mainnet } from 'viem/chains';
77
39
 
40
+ // Retrieve cached or new Viem Public Client
41
+ const client = createViemClient(mainnet);
78
42
  ```
79
43
 
80
- ### Resolve ENS Name
44
+ ### Deterministic Chain Switcher
81
45
 
82
- Get the primary ENS name for an Ethereum address.
46
+ Enforce that the wallet's connection context matches the requested chain:
83
47
 
84
48
  ```typescript
85
- import { getName, isEnsName } from '@tuwaio/orbit-evm';
86
- import { mainnet } from 'viem/chains';
49
+ import { checkAndSwitchChain } from '@tuwaio/orbit-evm';
50
+ import { type Config } from '@wagmi/core';
87
51
 
88
- async function displayEnsName(address: `0x${string}`) {
89
- if (isEnsName(address)) { // Basic check, though getName expects an address
90
- console.log(`${address} looks like an ENS name, not an address.`);
91
- return;
92
- }
93
- const name = await getName(address, [mainnet]);
94
- if (name) {
95
- console.log(`The ENS name for ${address} is: ${name}`);
96
- } else {
97
- console.log(`No primary ENS name found for ${address}.`);
52
+ declare const config: Config;
53
+
54
+ async function switchNetwork(targetChainId: number) {
55
+ try {
56
+ await checkAndSwitchChain(targetChainId, config);
57
+ console.log(`Execution context successfully switched to: ${targetChainId}`);
58
+ } catch (error) {
59
+ console.error('Chain switch rejected:', error);
98
60
  }
99
61
  }
100
-
101
- displayEnsName('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'); // Example: Vitalik's address
102
62
  ```
103
63
 
104
- -----
105
-
106
- ## 🔧 Architecture
107
-
108
- `@tuwaio/orbit-evm` acts as an **adapter implementation** for the `OrbitAdapter.EVM` type defined in `@tuwaio/orbit-core`. It provides concrete functions that fulfill the `BaseAdapter` interface requirements (like `getName`, `getAvatar`) and adds EVM-specific utilities.
109
-
110
- ### Core Modules & Exports (`index.ts`)
111
-
112
- - **Chain Utilities (`checkAndSwitchChain`)**: Handles network switching logic using `@wagmi/core`.
113
- - **Client Utilities (`createViemClient`)**: Manages `viem` public client instances with caching.
114
- - **ENS Utilities (`ensUtils`)**: Provides functions (`getAddress`, `getAvatar`, `getName`, `isEnsName`) for interacting with the Ethereum Name Service on Mainnet, using `viem/ens`.
115
-
116
- ### Build System
117
-
118
- - Built using `tsup`.
119
- - Outputs CommonJS (`cjs`) and ECMAScript Module (`esm`) formats.
120
- - Generates TypeScript declaration files (`.d.ts`).
121
- - Configured for tree-shaking and minification.
122
-
123
- -----
124
-
125
- ## ✨ How It Connects to the Ecosystem
126
-
127
- - **Provides EVM Functionality:** Offers the specific logic needed for EVM chain interactions within applications using Orbit Utils.
128
- - **Leverages Wagmi/Viem:** Relies on `@wagmi/core` for wallet actions (like chain switching) and `viem` for RPC interactions (like ENS resolution and client creation).
129
-
130
- -----
64
+ ---
131
65
 
132
- ## 🤝 Contributing & Support
66
+ ## 🔧 API & Module Architecture
133
67
 
134
- Contributions are welcome! Please read our main **[Contribution Guidelines](https://github.com/TuwaIO/workflows/blob/main/CONTRIBUTING.md)**.
68
+ `@tuwaio/orbit-evm` exposes the following modules:
135
69
 
136
- If you find this library useful, please consider supporting its development. Every contribution helps!
70
+ - **Chain Alignment:** `checkAndSwitchChain`.
71
+ - **Client Factory:** `createViemClient`.
72
+ - **ENS Resolvers:** `getAddress`, `getAvatar`, `getName`, `isEnsName`.
137
73
 
138
- [**➡️ View Support Options**](https://github.com/TuwaIO/workflows/blob/main/Donation.md)
74
+ ---
139
75
 
140
76
  ## 📄 License
141
77
 
142
- This project is licensed under the **Apache-2.0 License** - see the [LICENSE](./LICENSE) file for details.
78
+ Licensed under the **Apache-2.0 License**. See the [LICENSE](./LICENSE) file for details.
package/package.json CHANGED
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "name": "@tuwaio/orbit-evm",
3
- "version": "0.2.13",
3
+ "version": "0.2.17",
4
4
  "private": false,
5
5
  "author": "Oleksandr Tkach",
6
6
  "license": "Apache-2.0",
7
- "description": "The core, with web3 EVM utilities and helpers for TUWA projects.",
7
+ "description": "Tier 2 of the TUWA Ecosystem. Low-level EVM-specific communication primitives powered strictly by viem and wagmi.",
8
8
  "main": "./dist/index.js",
9
9
  "module": "./dist/index.mjs",
10
10
  "types": "./dist/index.d.ts",
@@ -40,10 +40,10 @@
40
40
  "viem": "2.x.x"
41
41
  },
42
42
  "devDependencies": {
43
- "@wagmi/core": "^3.5.0",
43
+ "@wagmi/core": "^3.5.1",
44
44
  "tsup": "^8.5.1",
45
45
  "typescript": "^6.0.3",
46
- "viem": "^2.51.3"
46
+ "viem": "^2.52.2"
47
47
  },
48
48
  "scripts": {
49
49
  "start": "tsup src/index.ts --watch",