@tuwaio/orbit-core 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 +136 -42
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,88 +4,182 @@
|
|
|
4
4
|
[](./LICENSE)
|
|
5
5
|
[](https://github.com/TuwaIO/orbit/actions)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
The foundational, framework-agnostic library for the Orbit Utils ecosystem, providing core types, utilities, and an adapter system for seamless multi-chain blockchain interactions in user interfaces.
|
|
8
8
|
|
|
9
9
|
---
|
|
10
10
|
|
|
11
11
|
## 🏛️ What is `@tuwaio/orbit-core`?
|
|
12
12
|
|
|
13
|
-
`@tuwaio/orbit-core` is the
|
|
13
|
+
`@tuwaio/orbit-core` is the central pillar of the **Orbit Utils** ecosystem, designed by **TUWA** to simplify the creation of cross-chain web3 user interfaces. It's a **headless** library, meaning it contains no UI components or framework-specific logic, making it universally compatible with any JavaScript or TypeScript application, regardless of the frontend framework (React, Vue, Svelte, Angular, or vanilla JS).
|
|
14
14
|
|
|
15
|
-
Its primary
|
|
15
|
+
Its primary goal is to establish a **unified interface** for interacting with diverse blockchain architectures (like EVM and Solana) through a flexible **adapter system**. Built entirely in **TypeScript**, it ensures type safety and provides the essential infrastructure – including core types, utility functions, and adapter management – that underpins multi-chain dApp development within the TUWA ecosystem. It serves as the backbone for simplifying interactions rather than repeating logic across different projects.
|
|
16
16
|
|
|
17
17
|
---
|
|
18
18
|
|
|
19
19
|
## ✨ Key Features
|
|
20
20
|
|
|
21
|
-
-
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
|
|
21
|
+
- **Multi-Chain Foundation:** Defines the core `OrbitAdapter` enum (supporting EVM, Solana, Starknet) and types for building consistent multi-chain support.
|
|
22
|
+
- **Framework Agnostic & Headless:** Contains only logic, no UI components, ensuring compatibility with any frontend setup.
|
|
23
|
+
- **Type-Safe Development:** Fully written in TypeScript 5.9+ for a robust developer experience.
|
|
24
|
+
- **Flexible Adapter System:** Provides utilities like `selectAdapterByKey` to easily manage and switch between different blockchain adapter implementations.
|
|
25
|
+
- **Essential Utilities:** Includes common helpers for tasks such as:
|
|
26
|
+
* Formatting wallet names and chain IDs (`formatWalletName`, `formatWalletChainId`).
|
|
27
|
+
* Identifying chain types (`isSolanaChain`, `getAdapterFromWalletType`).
|
|
28
|
+
* Managing wallet connection state in localStorage (`lastConnectedWalletHelpers`, `recentConnectedWalletHelpers`).
|
|
29
|
+
* Handling impersonation for development/testing (`impersonatedHelpers`).
|
|
30
|
+
* Basic async operations (`delay`, `waitFor`).
|
|
31
|
+
- **SSR Safe:** Utilities are designed to work safely in both browser and Server-Side Rendering environments.
|
|
27
32
|
|
|
28
33
|
---
|
|
29
34
|
|
|
30
35
|
## 💾 Installation
|
|
36
|
+
|
|
31
37
|
```bash
|
|
32
|
-
# Using pnpm
|
|
38
|
+
# Using pnpm (recommended)
|
|
33
39
|
pnpm add @tuwaio/orbit-core
|
|
40
|
+
|
|
34
41
|
# Using npm
|
|
35
42
|
npm install @tuwaio/orbit-core
|
|
43
|
+
|
|
36
44
|
# Using yarn
|
|
37
45
|
yarn add @tuwaio/orbit-core
|
|
38
|
-
|
|
46
|
+
````
|
|
39
47
|
|
|
40
|
-
|
|
48
|
+
*Note: `@tuwaio/orbit-core` provides the core logic. You will typically install chain-specific packages like `@tuwaio/orbit-evm` or `@tuwaio/orbit-solana` alongside it.*
|
|
49
|
+
|
|
50
|
+
-----
|
|
41
51
|
|
|
42
52
|
## 🚀 Quick Start
|
|
43
53
|
|
|
44
|
-
### Basic Usage
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
const adapter = { key: OrbitAdapter.EVM }; // adapter implementation
|
|
49
|
-
// Select adapter for specific chain
|
|
50
|
-
const evmAdapter = selectAdapterByKey({ adapterKey: OrbitAdapter.EVM, adapter, });
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
### Supported Chain Types
|
|
54
|
+
### Basic Adapter Usage
|
|
55
|
+
|
|
56
|
+
`@tuwaio/orbit-core` defines the structure and allows selection, but requires chain-specific packages (`@tuwaio/orbit-evm`, `@tuwaio/orbit-solana`) for actual adapter implementations.
|
|
57
|
+
|
|
54
58
|
```typescript
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
+
import { OrbitAdapter, selectAdapterByKey, BaseAdapter } from '@tuwaio/orbit-core';
|
|
60
|
+
|
|
61
|
+
// Assume these are implementations provided by @tuwaio/orbit-evm and @tuwaio/orbit-solana
|
|
62
|
+
// (Implementations details are simplified for this example)
|
|
63
|
+
interface EvmAdapter extends BaseAdapter {
|
|
64
|
+
key: OrbitAdapter.EVM;
|
|
65
|
+
}
|
|
66
|
+
interface SolanaAdapter extends BaseAdapter {
|
|
67
|
+
key: OrbitAdapter.SOLANA;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
const evmAdapterImpl: EvmAdapter = {
|
|
71
|
+
key: OrbitAdapter.EVM,
|
|
72
|
+
getExplorerUrl: (url, chainId) => `https://etherscan.io/${url}`,
|
|
73
|
+
getName: async (address) => null, // Placeholder
|
|
74
|
+
getAvatar: async (name) => null, // Placeholder
|
|
75
|
+
};
|
|
76
|
+
|
|
77
|
+
const solanaAdapterImpl: SolanaAdapter = {
|
|
78
|
+
key: OrbitAdapter.SOLANA,
|
|
79
|
+
getExplorerUrl: (url, chainId) => `https://solscan.io/${url}?cluster=${chainId}`,
|
|
80
|
+
getName: async (address) => null, // Placeholder
|
|
81
|
+
getAvatar: async (name) => null, // Placeholder
|
|
82
|
+
};
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
const configuredAdapters = [evmAdapterImpl, solanaAdapterImpl];
|
|
86
|
+
|
|
87
|
+
// --- Selecting an Adapter ---
|
|
88
|
+
|
|
89
|
+
// Select the EVM adapter based on its key
|
|
90
|
+
const selectedEvmAdapter = selectAdapterByKey({
|
|
91
|
+
adapterKey: OrbitAdapter.EVM,
|
|
92
|
+
adapter: configuredAdapters,
|
|
93
|
+
});
|
|
94
|
+
|
|
95
|
+
if (selectedEvmAdapter && selectedEvmAdapter.key === OrbitAdapter.EVM) {
|
|
96
|
+
console.log('Selected EVM Adapter Chain:', selectedEvmAdapter.getChainName()); // Output: Ethereum
|
|
97
|
+
} else {
|
|
98
|
+
console.error('EVM Adapter not found or configured.');
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
// Select the Solana adapter
|
|
102
|
+
const selectedSolanaAdapter = selectAdapterByKey({
|
|
103
|
+
adapterKey: OrbitAdapter.SOLANA,
|
|
104
|
+
adapter: configuredAdapters,
|
|
105
|
+
});
|
|
106
|
+
|
|
107
|
+
if (selectedSolanaAdapter && selectedSolanaAdapter.key === OrbitAdapter.SOLANA) {
|
|
108
|
+
console.log('Selected Solana Adapter Cluster:', selectedSolanaAdapter.getCluster()); // Output: mainnet-beta
|
|
109
|
+
console.log('Explorer URL:', selectedSolanaAdapter.getExplorerUrl('tx/abc...', 'mainnet-beta')); // Output: [https://solscan.io/tx/abc...?cluster=mainnet-beta](https://solscan.io/tx/abc...?cluster=mainnet-beta)
|
|
110
|
+
} else {
|
|
111
|
+
console.error('Solana Adapter not found or configured.');
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Using Core Utilities
|
|
59
116
|
|
|
60
|
-
|
|
117
|
+
```typescript
|
|
118
|
+
import {
|
|
119
|
+
OrbitAdapter,
|
|
120
|
+
formatWalletName,
|
|
121
|
+
getAdapterFromWalletType,
|
|
122
|
+
getWalletTypeFromConnectorName,
|
|
123
|
+
isSolanaChain,
|
|
124
|
+
lastConnectedWalletHelpers
|
|
125
|
+
} from '@tuwaio/orbit-core';
|
|
126
|
+
|
|
127
|
+
// Formatting
|
|
128
|
+
const formattedName = formatWalletName('MetaMask'); // "metamask"
|
|
129
|
+
console.log(formattedName);
|
|
130
|
+
const walletType = getWalletTypeFromConnectorName(OrbitAdapter.EVM, 'Brave Wallet'); // "evm:bravewallet"
|
|
131
|
+
console.log(walletType);
|
|
132
|
+
|
|
133
|
+
// Identification
|
|
134
|
+
const adapterType = getAdapterFromWalletType(walletType); // OrbitAdapter.EVM
|
|
135
|
+
console.log(adapterType);
|
|
136
|
+
console.log(isSolanaChain('devnet')); // true
|
|
137
|
+
console.log(isSolanaChain(1)); // false
|
|
138
|
+
|
|
139
|
+
// Local Storage Management for Last Connected Wallet
|
|
140
|
+
lastConnectedWalletHelpers.setLastConnectedWallet({
|
|
141
|
+
walletType: 'evm:metamask',
|
|
142
|
+
chainId: 1,
|
|
143
|
+
address: '0x123...'
|
|
144
|
+
});
|
|
145
|
+
const lastWallet = lastConnectedWalletHelpers.getLastConnectedWallet();
|
|
146
|
+
console.log(lastWallet); // { walletType: 'evm:metamask', chainId: 1, address: '0x123...' }
|
|
147
|
+
|
|
148
|
+
// lastConnectedWalletHelpers.removeLastConnectedWallet();
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
-----
|
|
61
152
|
|
|
62
153
|
## 🔧 Architecture
|
|
63
154
|
|
|
64
|
-
Orbit Core is
|
|
155
|
+
Orbit Core is designed around modularity and abstraction:
|
|
65
156
|
|
|
66
|
-
1.
|
|
67
|
-
2.
|
|
68
|
-
3.
|
|
157
|
+
1. **Core Types (`types.ts`):** Defines fundamental structures like `OrbitAdapter` (enum for EVM, Solana, Starknet), `BaseAdapter` (common interface), and `WalletType`.
|
|
158
|
+
2. **Adapter System:** Enables handling multiple blockchain types via a common interface. The `selectAdapterByKey` utility allows runtime selection of the correct adapter implementation based on the `OrbitAdapter` key. Chain-specific logic resides in separate packages (e.g., `@tuwaio/orbit-evm`).
|
|
159
|
+
3. **Utilities (`utils/`):** A collection of framework-agnostic helper functions covering formatting, chain identification, localStorage management (for connection state persistence), async operations, and other common tasks needed when building multi-chain UIs.
|
|
69
160
|
|
|
70
|
-
###
|
|
161
|
+
### Key Exports (`index.ts`)
|
|
71
162
|
|
|
72
|
-
- `OrbitAdapter
|
|
73
|
-
- `selectAdapterByKey
|
|
74
|
-
-
|
|
163
|
+
- **Types:** `OrbitAdapter`, `BaseAdapter`, `WalletType`, `OrbitGenericAdapter`, `RecentConnectedWallet`.
|
|
164
|
+
- **Adapter Utilities:** `selectAdapterByKey`, `getAdapterFromWalletType`.
|
|
165
|
+
- **Formatting Utilities:** `formatWalletChainId`, `formatWalletName`, `getWalletTypeFromConnectorName`.
|
|
166
|
+
- **Chain Helpers:** `isSolanaChain`, `setChainId`.
|
|
167
|
+
- **Storage Helpers:** `lastConnectedWalletHelpers`, `recentConnectedWalletHelpers`, `impersonatedHelpers`, `getParsedStorageItem`.
|
|
168
|
+
- **General Utilities:** `delay`, `filterUniqueByKey`, `waitFor`, `isSafeApp`.
|
|
75
169
|
|
|
76
|
-
|
|
170
|
+
-----
|
|
77
171
|
|
|
78
172
|
## ✨ How It Connects to the Ecosystem
|
|
79
173
|
|
|
80
|
-
The Orbit ecosystem
|
|
174
|
+
The Orbit Utils ecosystem is designed for modularity:
|
|
81
175
|
|
|
82
|
-
- **`@tuwaio/orbit-core`:**
|
|
83
|
-
- **`@tuwaio/orbit-evm`:** EVM-
|
|
84
|
-
- **`@tuwaio/orbit-solana`:** Solana blockchain
|
|
176
|
+
- **`@tuwaio/orbit-core`:** (This package) Provides the core, non-chain-specific types, utilities, and adapter structure.
|
|
177
|
+
- **`@tuwaio/orbit-evm`:** Contains the specific adapter implementation and helper functions for EVM-compatible chains (using libraries like `viem` and `@wagmi/core`).
|
|
178
|
+
- **`@tuwaio/orbit-solana`:** Contains the specific adapter implementation and helpers for the Solana blockchain (using libraries like `gill`).
|
|
85
179
|
|
|
86
|
-
|
|
180
|
+
Developers typically install `@tuwaio/orbit-core` along with one or more chain-specific packages based on their application's needs. The core package ensures consistency and provides shared utilities, while the specific packages handle the unique aspects of each blockchain.
|
|
87
181
|
|
|
88
|
-
|
|
182
|
+
-----
|
|
89
183
|
|
|
90
184
|
## 🤝 Contributing & Support
|
|
91
185
|
|