@tuwaio/orbit-core 0.2.8 → 0.2.11
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 +47 -137
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,188 +1,98 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @tuwaio/orbit-core
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@tuwaio/orbit-core)
|
|
4
4
|
[](./LICENSE)
|
|
5
|
-
[](https://github.com/TuwaIO/orbit/actions)
|
|
6
5
|
|
|
7
|
-
|
|
6
|
+
`@tuwaio/orbit-core` serves as the core logic and connector layer for the Orbit Utils ecosystem. It is completely **headless** and **framework-agnostic**, ensuring compatibility across React, Vue, Svelte, or vanilla JS applications. It abstracts the underlying blockchain architectures into a unified interface, simplifying state handling in complex multi-chain UIs.
|
|
8
7
|
|
|
9
8
|
---
|
|
10
9
|
|
|
11
|
-
## 🏛️
|
|
10
|
+
## 🏛️ Core Capabilities
|
|
12
11
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
---
|
|
18
|
-
|
|
19
|
-
## ✨ Key Features
|
|
20
|
-
|
|
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 connector names and chain IDs (`formatConnectorName`, `formatConnectorChainId`).
|
|
27
|
-
- Identifying chain types (`isSolanaChain`, `getAdapterFromConnectorType`).
|
|
28
|
-
- Managing connector connection state in localStorage (`lastConnectedConnectorHelpers`, `recentConnectedConnectorHelpers`).
|
|
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.
|
|
12
|
+
- **Unified Multi-Chain Adapters:** Establishes the standard `BaseAdapter` interface and the `OrbitAdapter` enum (EVM, Solana, Starknet) to enable cross-chain UI layers.
|
|
13
|
+
- **Connection State Persistence:** Includes SSR-safe storage helpers (`lastConnectedConnectorHelpers`, `recentConnectedConnectorHelpers`) to track and resume wallet connection history.
|
|
14
|
+
- **autonomy-focused Utilities:** Native handlers for formatting chain IDs, parsing connector names, and managing async task execution (`waitFor`, `delay`).
|
|
15
|
+
- **Impersonation Engine:** Built-in `impersonatedHelpers` to support testing and debugging in different account contexts.
|
|
32
16
|
|
|
33
17
|
---
|
|
34
18
|
|
|
35
19
|
## 💾 Installation
|
|
36
20
|
|
|
37
21
|
```bash
|
|
38
|
-
# Using pnpm (recommended), but you can use npm, yarn or bun as well
|
|
39
22
|
pnpm add @tuwaio/orbit-core
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
*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.*
|
|
23
|
+
```
|
|
43
24
|
|
|
44
|
-
|
|
25
|
+
---
|
|
45
26
|
|
|
46
27
|
## 🚀 Quick Start
|
|
47
28
|
|
|
48
|
-
###
|
|
29
|
+
### Runtime Adapter Selection
|
|
49
30
|
|
|
50
|
-
|
|
31
|
+
Configure chain adapters dynamically and retrieve them at runtime using standard selectors:
|
|
51
32
|
|
|
52
33
|
```typescript
|
|
53
34
|
import { OrbitAdapter, selectAdapterByKey, BaseAdapter } from '@tuwaio/orbit-core';
|
|
54
35
|
|
|
55
|
-
//
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
key: OrbitAdapter.EVM;
|
|
59
|
-
}
|
|
60
|
-
interface SolanaAdapter extends BaseAdapter {
|
|
61
|
-
key: OrbitAdapter.SOLANA;
|
|
62
|
-
}
|
|
63
|
-
|
|
64
|
-
const evmAdapterImpl: EvmAdapter = {
|
|
36
|
+
// Configure adapters (mocked here, use @tuwaio/orbit-evm / @tuwaio/orbit-solana in production)
|
|
37
|
+
const adapters: BaseAdapter[] = [
|
|
38
|
+
{
|
|
65
39
|
key: OrbitAdapter.EVM,
|
|
66
|
-
getExplorerUrl: (url
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
};
|
|
70
|
-
|
|
71
|
-
const solanaAdapterImpl: SolanaAdapter = {
|
|
40
|
+
getExplorerUrl: (url) => `https://etherscan.io/${url}`,
|
|
41
|
+
},
|
|
42
|
+
{
|
|
72
43
|
key: OrbitAdapter.SOLANA,
|
|
73
|
-
getExplorerUrl: (url,
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
};
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
const configuredAdapters = [evmAdapterImpl, solanaAdapterImpl];
|
|
80
|
-
|
|
81
|
-
// --- Selecting an Adapter ---
|
|
82
|
-
|
|
83
|
-
// Select the EVM adapter based on its key
|
|
84
|
-
const selectedEvmAdapter = selectAdapterByKey({
|
|
85
|
-
adapterKey: OrbitAdapter.EVM,
|
|
86
|
-
adapter: configuredAdapters,
|
|
87
|
-
});
|
|
88
|
-
|
|
89
|
-
if (selectedEvmAdapter && selectedEvmAdapter.key === OrbitAdapter.EVM) {
|
|
90
|
-
console.log('Selected EVM Adapter Chain:', selectedEvmAdapter.getChainName()); // Output: Ethereum
|
|
91
|
-
} else {
|
|
92
|
-
console.error('EVM Adapter not found or configured.');
|
|
93
|
-
}
|
|
44
|
+
getExplorerUrl: (url, cluster) => `https://solscan.io/${url}?cluster=${cluster}`,
|
|
45
|
+
},
|
|
46
|
+
];
|
|
94
47
|
|
|
95
|
-
// Select
|
|
96
|
-
const
|
|
48
|
+
// Select adapter dynamically
|
|
49
|
+
const activeAdapter = selectAdapterByKey({
|
|
97
50
|
adapterKey: OrbitAdapter.SOLANA,
|
|
98
|
-
adapter:
|
|
51
|
+
adapter: adapters,
|
|
99
52
|
});
|
|
100
53
|
|
|
101
|
-
if (
|
|
102
|
-
|
|
103
|
-
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)
|
|
104
|
-
} else {
|
|
105
|
-
console.error('Solana Adapter not found or configured.');
|
|
54
|
+
if (activeAdapter) {
|
|
55
|
+
console.log('Selected:', activeAdapter.getExplorerUrl('tx/0x...', 'mainnet-beta'));
|
|
106
56
|
}
|
|
107
57
|
```
|
|
108
58
|
|
|
109
|
-
###
|
|
59
|
+
### Connection State Persistence
|
|
60
|
+
|
|
61
|
+
Persist last connected connector state in localStorage safely:
|
|
110
62
|
|
|
111
63
|
```typescript
|
|
112
|
-
import {
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
getAdapterFromConnectorType,
|
|
116
|
-
getConnectorTypeFromName,
|
|
117
|
-
isSolanaChain,
|
|
118
|
-
lastConnectedConnectorHelpers
|
|
119
|
-
} from '@tuwaio/orbit-core';
|
|
120
|
-
|
|
121
|
-
// Formatting
|
|
122
|
-
const formattedName = formatConnectorName('MetaMask'); // "metamask"
|
|
123
|
-
console.log(formattedName);
|
|
124
|
-
const connectorType = getConnectorTypeFromName(OrbitAdapter.EVM, 'Brave Wallet'); // "evm:bravewallet"
|
|
125
|
-
console.log(connectorType);
|
|
126
|
-
|
|
127
|
-
// Identification
|
|
128
|
-
const adapterType = getAdapterFromConnectorType(connectorType); // OrbitAdapter.EVM
|
|
129
|
-
console.log(adapterType);
|
|
130
|
-
console.log(isSolanaChain('devnet')); // true
|
|
131
|
-
console.log(isSolanaChain(1)); // false
|
|
132
|
-
|
|
133
|
-
// Local Storage Management for Last Connected Connector
|
|
64
|
+
import { lastConnectedConnectorHelpers } from '@tuwaio/orbit-core';
|
|
65
|
+
|
|
66
|
+
// Save connection metadata
|
|
134
67
|
lastConnectedConnectorHelpers.setLastConnectedConnector({
|
|
135
68
|
connectorType: 'evm:metamask',
|
|
136
69
|
chainId: 1,
|
|
137
|
-
address: '0x123...'
|
|
70
|
+
address: '0x123...',
|
|
138
71
|
});
|
|
139
|
-
const lastWallet = lastConnectedConnectorHelpers.getLastConnectedConnector();
|
|
140
|
-
console.log(lastWallet); // { connectorType: 'evm:metamask', chainId: 1, address: '0x123...' }
|
|
141
72
|
|
|
142
|
-
//
|
|
73
|
+
// Retrieve connection metadata (returns null in SSR environment)
|
|
74
|
+
const lastConnected = lastConnectedConnectorHelpers.getLastConnectedConnector();
|
|
75
|
+
console.log(lastConnected?.address); // "0x123..."
|
|
143
76
|
```
|
|
144
77
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
## 🔧 Architecture
|
|
148
|
-
|
|
149
|
-
Orbit Core is designed around modularity and abstraction:
|
|
150
|
-
|
|
151
|
-
1. **Core Types (`types.ts`):** Defines fundamental structures like `OrbitAdapter` (enum for EVM, Solana, Starknet), `BaseAdapter` (common interface), and `ConnectorType`.
|
|
152
|
-
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`).
|
|
153
|
-
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.
|
|
154
|
-
|
|
155
|
-
### Key Exports (`index.ts`)
|
|
156
|
-
|
|
157
|
-
- **Types:** `OrbitAdapter`, `BaseAdapter`, `ConnectorType`, `OrbitGenericAdapter`, `RecentConnectedConnector`.
|
|
158
|
-
- **Adapter Utilities:** `selectAdapterByKey`, `getAdapterFromConnectorType`.
|
|
159
|
-
- **Formatting Utilities:** `formatConnectorChainId`, `formatConnectorName`, `getConnectorTypeFromName`.
|
|
160
|
-
- **Chain Helpers:** `isSolanaChain`, `setChainId`.
|
|
161
|
-
- **Storage Helpers:** `lastConnectedConnectorHelpers`, `recentConnectedConnectorHelpers`, `impersonatedHelpers`, `getParsedStorageItem`.
|
|
162
|
-
- **General Utilities:** `delay`, `filterUniqueByKey`, `waitFor`, `isSafeApp`.
|
|
163
|
-
|
|
164
|
-
-----
|
|
165
|
-
|
|
166
|
-
## ✨ How It Connects to the Ecosystem
|
|
167
|
-
|
|
168
|
-
The Orbit Utils ecosystem is designed for modularity:
|
|
169
|
-
|
|
170
|
-
- **`@tuwaio/orbit-core`:** (This package) Provides the core, non-chain-specific types, utilities, and adapter structure.
|
|
171
|
-
- **`@tuwaio/orbit-evm`:** Contains the specific adapter implementation and helper functions for EVM-compatible chains (using libraries like `viem` and `@wagmi/core`).
|
|
172
|
-
- **`@tuwaio/orbit-solana`:** Contains the specific adapter implementation and helpers for the Solana blockchain (using libraries like `gill`).
|
|
78
|
+
---
|
|
173
79
|
|
|
174
|
-
|
|
80
|
+
## 🔧 API & Module Architecture
|
|
175
81
|
|
|
176
|
-
|
|
82
|
+
`@tuwaio/orbit-core` exports the following structures:
|
|
177
83
|
|
|
178
|
-
|
|
84
|
+
- **Core Types:** `OrbitAdapter`, `BaseAdapter`, `ConnectorType`, `RecentlyConnectedConnectorData`.
|
|
85
|
+
- **Registry Utilities:** `selectAdapterByKey`, `getAdapterFromConnectorType`, `getConnectorTypeFromName`.
|
|
86
|
+
- **Formatters:** `formatConnectorName`, `formatConnectorChainId`.
|
|
87
|
+
- **Storage Persisters:** `lastConnectedConnectorHelpers`, `recentConnectedConnectorHelpers`, `impersonatedHelpers`.
|
|
88
|
+
- **General Utilities:** `isSafeApp`, `delay`, `waitFor`, `filterUniqueByKey`.
|
|
179
89
|
|
|
180
|
-
|
|
90
|
+
---
|
|
181
91
|
|
|
182
|
-
|
|
92
|
+
## 🤝 Contributing
|
|
183
93
|
|
|
184
|
-
|
|
94
|
+
Please read our main **[Contribution Guidelines](https://github.com/TuwaIO/workflows/blob/main/CONTRIBUTING.md)** before submitting pull requests.
|
|
185
95
|
|
|
186
96
|
## 📄 License
|
|
187
97
|
|
|
188
|
-
|
|
98
|
+
Licensed under the **Apache-2.0 License**. See the [LICENSE](./LICENSE) file for details.
|