@tuwaio/orbit-evm 0.1.0 → 0.1.1
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.
- package/README.md +102 -21
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,52 +4,137 @@
|
|
|
4
4
|
[](./LICENSE)
|
|
5
5
|
[](https://github.com/TuwaIO/orbit/actions)
|
|
6
6
|
|
|
7
|
-
EVM-specific implementation for the
|
|
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**.
|
|
8
8
|
|
|
9
9
|
---
|
|
10
10
|
|
|
11
11
|
## 🏛️ What is `@tuwaio/orbit-evm`?
|
|
12
12
|
|
|
13
|
-
`@tuwaio/orbit-evm`
|
|
13
|
+
`@tuwaio/orbit-evm` extends the core capabilities of `@tuwaio/orbit-core` by providing 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.
|
|
14
16
|
|
|
15
17
|
---
|
|
16
18
|
|
|
17
19
|
## ✨ Key Features
|
|
18
20
|
|
|
19
|
-
-
|
|
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.
|
|
21
32
|
|
|
22
33
|
---
|
|
23
34
|
|
|
24
35
|
## 💾 Installation
|
|
25
36
|
|
|
26
37
|
### Requirements
|
|
27
|
-
|
|
28
|
-
-
|
|
38
|
+
|
|
39
|
+
- Node.js 20+
|
|
40
|
+
- TypeScript 5.9+
|
|
41
|
+
- `@tuwaio/orbit-core` (as a foundational peer dependency)
|
|
29
42
|
|
|
30
43
|
```bash
|
|
31
44
|
# Using pnpm (recommended)
|
|
32
|
-
pnpm add @tuwaio/orbit-evm @wagmi/core viem
|
|
45
|
+
pnpm add @tuwaio/orbit-evm @tuwaio/orbit-core @wagmi/core viem
|
|
46
|
+
|
|
33
47
|
# Using npm
|
|
34
|
-
npm install @tuwaio/orbit-evm @wagmi/core viem
|
|
48
|
+
npm install @tuwaio/orbit-evm @tuwaio/orbit-core @wagmi/core viem
|
|
49
|
+
|
|
35
50
|
# Using yarn
|
|
36
|
-
yarn add @tuwaio/orbit-evm @wagmi/core viem
|
|
51
|
+
yarn add @tuwaio/orbit-evm @tuwaio/orbit-core @wagmi/core viem
|
|
52
|
+
````
|
|
53
|
+
|
|
54
|
+
*Note: `@wagmi/core` and `viem` are **peer dependencies** and must be installed alongside `@tuwaio/orbit-evm`*.
|
|
55
|
+
|
|
56
|
+
-----
|
|
57
|
+
|
|
58
|
+
## 🚀 Quick Start
|
|
59
|
+
|
|
60
|
+
### Check and Switch Network
|
|
61
|
+
|
|
62
|
+
Ensure the user's wallet is connected to the desired EVM chain (e.g., Sepolia testnet, ID 11155111).
|
|
63
|
+
|
|
64
|
+
```typescript
|
|
65
|
+
import { checkAndSwitchChain } from '@tuwaio/orbit-evm';
|
|
66
|
+
import { type Config } from '@wagmi/core'; // Assuming you have your wagmi config
|
|
67
|
+
|
|
68
|
+
// Assume 'wagmiConfig' is your initialized wagmi Config object
|
|
69
|
+
declare const wagmiConfig: Config;
|
|
70
|
+
const targetChainId = 11155111; // Sepolia
|
|
71
|
+
|
|
72
|
+
async function ensureCorrectChain() {
|
|
73
|
+
try {
|
|
74
|
+
await checkAndSwitchChain(targetChainId, wagmiConfig);
|
|
75
|
+
console.log(`Wallet is now connected to chain ID ${targetChainId}`);
|
|
76
|
+
// Proceed with actions requiring the target chain
|
|
77
|
+
} catch (error) {
|
|
78
|
+
console.error('Failed to switch chain:', error);
|
|
79
|
+
// Handle the error (e.g., show a message to the user)
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
ensureCorrectChain();
|
|
84
|
+
|
|
37
85
|
```
|
|
38
86
|
|
|
39
|
-
|
|
87
|
+
### Resolve ENS Name
|
|
88
|
+
|
|
89
|
+
Get the primary ENS name for an Ethereum address.
|
|
90
|
+
|
|
91
|
+
```typescript
|
|
92
|
+
import { getName, isEnsName } from '@tuwaio/orbit-evm';
|
|
93
|
+
|
|
94
|
+
async function displayEnsName(address: `0x${string}`) {
|
|
95
|
+
if (isEnsName(address)) { // Basic check, though getName expects an address
|
|
96
|
+
console.log(`${address} looks like an ENS name, not an address.`);
|
|
97
|
+
return;
|
|
98
|
+
}
|
|
99
|
+
const name = await getName(address);
|
|
100
|
+
if (name) {
|
|
101
|
+
console.log(`The ENS name for ${address} is: ${name}`);
|
|
102
|
+
} else {
|
|
103
|
+
console.log(`No primary ENS name found for ${address}.`);
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
displayEnsName('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'); // Example: Vitalik's address
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
-----
|
|
40
111
|
|
|
41
112
|
## 🔧 Architecture
|
|
42
113
|
|
|
43
|
-
|
|
114
|
+
`@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.
|
|
115
|
+
|
|
116
|
+
### Core Modules & Exports (`index.ts`)
|
|
117
|
+
|
|
118
|
+
- **Chain Utilities (`checkAndSwitchChain`)**: Handles network switching logic using `@wagmi/core`.
|
|
119
|
+
- **Client Utilities (`createViemClient`)**: Manages `viem` public client instances with caching.
|
|
120
|
+
- **ENS Utilities (`ensUtils`)**: Provides functions (`getAddress`, `getAvatar`, `getName`, `isEnsName`) for interacting with the Ethereum Name Service on Mainnet, using `viem/ens`.
|
|
44
121
|
|
|
45
122
|
### Build System
|
|
46
|
-
- Built with `tsup` for optimal bundling
|
|
47
|
-
- Outputs both CommonJS and ESM formats
|
|
48
|
-
- Generates TypeScript declarations
|
|
49
123
|
|
|
50
|
-
|
|
51
|
-
-
|
|
52
|
-
|
|
124
|
+
- Built using `tsup`.
|
|
125
|
+
- Outputs CommonJS (`cjs`) and ECMAScript Module (`esm`) formats.
|
|
126
|
+
- Generates TypeScript declaration files (`.d.ts`).
|
|
127
|
+
- Configured for tree-shaking and minification.
|
|
128
|
+
|
|
129
|
+
-----
|
|
130
|
+
|
|
131
|
+
## ✨ How It Connects to the Ecosystem
|
|
132
|
+
|
|
133
|
+
- **Depends on `@tuwaio/orbit-core`:** Inherits core types (`OrbitAdapter`, `BaseAdapter`) and potentially uses core utilities.
|
|
134
|
+
- **Provides EVM Functionality:** Offers the specific logic needed for EVM chain interactions within applications using Orbit Utils.
|
|
135
|
+
- **Leverages Wagmi/Viem:** Relies on `@wagmi/core` for wallet actions (like chain switching) and `viem` for RPC interactions (like ENS resolution and client creation).
|
|
136
|
+
|
|
137
|
+
-----
|
|
53
138
|
|
|
54
139
|
## 🤝 Contributing & Support
|
|
55
140
|
|
|
@@ -62,7 +147,3 @@ If you find this library useful, please consider supporting its development. Eve
|
|
|
62
147
|
## 📄 License
|
|
63
148
|
|
|
64
149
|
This project is licensed under the **Apache-2.0 License** - see the [LICENSE](./LICENSE) file for details.
|
|
65
|
-
|
|
66
|
-
## 👥 Contributors
|
|
67
|
-
|
|
68
|
-
- **Oleksandr Tkach** - [GitHub](https://github.com/Argeare5)
|