@tuwaio/orbit-evm 0.2.13 → 0.2.16
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 +45 -96
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,142 +1,91 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @tuwaio/orbit-evm
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@tuwaio/orbit-evm)
|
|
4
4
|
[](./LICENSE)
|
|
5
|
-
[](https://github.com/TuwaIO/orbit/actions)
|
|
6
5
|
|
|
7
|
-
|
|
6
|
+
`@tuwaio/orbit-evm` provides concrete implementations and utilities tailored specifically for EVM-compatible blockchains. Built entirely in **TypeScript** and powered by **`@wagmi/core`** and **`viem`**, it acts as the EVM adapter for the Orbit Utils ecosystem, simplifying client connections, chain switching, and identity lookups in web3 UIs.
|
|
8
7
|
|
|
9
8
|
---
|
|
10
9
|
|
|
11
|
-
## 🏛️
|
|
10
|
+
## 🏛️ Core Capabilities
|
|
12
11
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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
|
+
- **Public Client Caching:** Dynamically instantiates and caches `viem` public clients (`createViemClient`) to optimize RPC request efficiency.
|
|
13
|
+
- **ENS Metadata Engine:** Built-in ENS lookups targeting Ethereum Mainnet with internal caching for resolving ENS names to addresses, reverse resolving addresses, and fetching avatars.
|
|
14
|
+
- **Intelligent Chain Switcher:** Safe utility (`checkAndSwitchChain`) to prompt users' wallets to align with the required target network.
|
|
15
|
+
- **Type-Safe APIs:** Seamlessly aligned with typescript standards v5.9+ and Wagmi/Viem 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
|
-
|
|
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
30
|
## 🚀 Quick Start
|
|
52
31
|
|
|
53
|
-
###
|
|
32
|
+
### ENS Metadata Resolution
|
|
54
33
|
|
|
55
|
-
|
|
34
|
+
Retrieve profile metadata associated with an Ethereum address dynamically:
|
|
56
35
|
|
|
57
36
|
```typescript
|
|
58
|
-
import {
|
|
59
|
-
import {
|
|
37
|
+
import { getName, getAvatar } from '@tuwaio/orbit-evm';
|
|
38
|
+
import { mainnet } from 'viem/chains';
|
|
60
39
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
const
|
|
40
|
+
async function fetchUserProfile(address: `0x${string}`) {
|
|
41
|
+
// Resolve primary ENS name
|
|
42
|
+
const name = await getName(address, [mainnet]);
|
|
64
43
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
await
|
|
68
|
-
console.log(`
|
|
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)
|
|
44
|
+
if (name) {
|
|
45
|
+
// Resolve avatar image URL
|
|
46
|
+
const avatarUrl = await getAvatar(name, [mainnet]);
|
|
47
|
+
console.log(`ENS: ${name}, Avatar: ${avatarUrl}`);
|
|
73
48
|
}
|
|
74
49
|
}
|
|
75
|
-
|
|
76
|
-
ensureCorrectChain();
|
|
77
|
-
|
|
78
50
|
```
|
|
79
51
|
|
|
80
|
-
###
|
|
52
|
+
### Wallet Chain Alignment
|
|
81
53
|
|
|
82
|
-
|
|
54
|
+
Prompt the user's wallet to switch to the desired network context:
|
|
83
55
|
|
|
84
56
|
```typescript
|
|
85
|
-
import {
|
|
86
|
-
import {
|
|
57
|
+
import { checkAndSwitchChain } from '@tuwaio/orbit-evm';
|
|
58
|
+
import { type Config } from '@wagmi/core';
|
|
87
59
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
console.log(`No primary ENS name found for ${address}.`);
|
|
60
|
+
declare const wagmiConfig: Config; // Your wagmi configuration instance
|
|
61
|
+
|
|
62
|
+
async function alignNetwork() {
|
|
63
|
+
try {
|
|
64
|
+
const mainnetChainId = 1;
|
|
65
|
+
await checkAndSwitchChain(mainnetChainId, wagmiConfig);
|
|
66
|
+
console.log('Wallet aligned to Ethereum Mainnet');
|
|
67
|
+
} catch (error) {
|
|
68
|
+
console.error('Failed to align network:', error);
|
|
98
69
|
}
|
|
99
70
|
}
|
|
100
|
-
|
|
101
|
-
displayEnsName('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'); // Example: Vitalik's address
|
|
102
71
|
```
|
|
103
72
|
|
|
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
|
|
73
|
+
---
|
|
126
74
|
|
|
127
|
-
|
|
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).
|
|
75
|
+
## 🔧 API & Module Architecture
|
|
129
76
|
|
|
130
|
-
|
|
77
|
+
`@tuwaio/orbit-evm` exports the following modules:
|
|
131
78
|
|
|
132
|
-
|
|
79
|
+
- **Chain Switcher:** `checkAndSwitchChain`.
|
|
80
|
+
- **Public Client Factory:** `createViemClient` (cache-backed).
|
|
81
|
+
- **ENS Responders:** `getAddress`, `getAvatar`, `getName`, `isEnsName`.
|
|
133
82
|
|
|
134
|
-
|
|
83
|
+
---
|
|
135
84
|
|
|
136
|
-
|
|
85
|
+
## 🤝 Contributing
|
|
137
86
|
|
|
138
|
-
|
|
87
|
+
Please read our main **[Contribution Guidelines](https://github.com/TuwaIO/workflows/blob/main/CONTRIBUTING.md)** before submitting pull requests.
|
|
139
88
|
|
|
140
89
|
## 📄 License
|
|
141
90
|
|
|
142
|
-
|
|
91
|
+
Licensed under the **Apache-2.0 License**. See the [LICENSE](./LICENSE) file for details.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tuwaio/orbit-evm",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.16",
|
|
4
4
|
"private": false,
|
|
5
5
|
"author": "Oleksandr Tkach",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -40,10 +40,10 @@
|
|
|
40
40
|
"viem": "2.x.x"
|
|
41
41
|
},
|
|
42
42
|
"devDependencies": {
|
|
43
|
-
"@wagmi/core": "^3.5.
|
|
43
|
+
"@wagmi/core": "^3.5.1",
|
|
44
44
|
"tsup": "^8.5.1",
|
|
45
45
|
"typescript": "^6.0.3",
|
|
46
|
-
"viem": "^2.
|
|
46
|
+
"viem": "^2.52.2"
|
|
47
47
|
},
|
|
48
48
|
"scripts": {
|
|
49
49
|
"start": "tsup src/index.ts --watch",
|