@tuwaio/orbit-core 0.2.8 → 0.2.12
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 +46 -140
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,188 +1,94 @@
|
|
|
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` is the Tier 1 core logic and foundational state wrapper layer of the TUWA Orbit multi-chain framework. It is completely **headless** and **framework-agnostic**, engineered to decouple raw blockchain connection interfaces from visual frontend layers. By establishing a unified type-safe interface, it enables consistent cross-chain connection management and persistent user account tracking.
|
|
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 Primitives:** Establishes the structural `BaseAdapter` interface and the `OrbitAdapter` enum (EVM, Solana, Starknet) to serve as the abstract layer for multi-chain communication.
|
|
13
|
+
- **Connection State Persistence:** Implements SSR-safe storage helpers (`lastConnectedConnectorHelpers`, `recentConnectedConnectorHelpers`) to track and resume wallet connection history via `localStorage`.
|
|
14
|
+
- **Autonomy-Focused Utilities:** Technical utility helpers for formatting chain IDs, parsing connector names, and executing asynchronous operations (`waitFor`, `delay`).
|
|
15
|
+
- **Account Impersonation Engine:** Built-in `impersonatedHelpers` for sandboxed testing and account auditing.
|
|
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
|
+
## 🚀 Architectural Integration
|
|
47
28
|
|
|
48
|
-
###
|
|
29
|
+
### Runtime Adapter Resolution
|
|
49
30
|
|
|
50
|
-
|
|
31
|
+
Register and resolve chain-specific primitive adapters dynamically:
|
|
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 primitive adapter mapping
|
|
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
|
-
});
|
|
44
|
+
getExplorerUrl: (url, cluster) => `https://solscan.io/${url}?cluster=${cluster}`,
|
|
45
|
+
},
|
|
46
|
+
];
|
|
88
47
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
} else {
|
|
92
|
-
console.error('EVM Adapter not found or configured.');
|
|
93
|
-
}
|
|
94
|
-
|
|
95
|
-
// Select the Solana adapter
|
|
96
|
-
const selectedSolanaAdapter = selectAdapterByKey({
|
|
48
|
+
// Dynamically select target execution adapter
|
|
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(activeAdapter.getExplorerUrl('tx/0x...', 'mainnet-beta'));
|
|
106
56
|
}
|
|
107
57
|
```
|
|
108
58
|
|
|
109
|
-
###
|
|
59
|
+
### Connection State Storage
|
|
60
|
+
|
|
61
|
+
Read and write connected connector metadata securely with `localStorage` fallback checks:
|
|
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
|
+
// Persist 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 safely during client-side hydration
|
|
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`).
|
|
173
|
-
|
|
174
|
-
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.
|
|
175
|
-
|
|
176
|
-
-----
|
|
78
|
+
---
|
|
177
79
|
|
|
178
|
-
##
|
|
80
|
+
## 🔧 API & Module Architecture
|
|
179
81
|
|
|
180
|
-
|
|
82
|
+
`@tuwaio/orbit-core` exposes the following modules:
|
|
181
83
|
|
|
182
|
-
|
|
84
|
+
- **Core Primitives:** `OrbitAdapter`, `BaseAdapter`, `ConnectorType`, `RecentlyConnectedConnectorData`.
|
|
85
|
+
- **Registry Resolvers:** `selectAdapterByKey`, `getAdapterFromConnectorType`, `getConnectorTypeFromName`.
|
|
86
|
+
- **Formatters:** `formatConnectorName`, `formatConnectorChainId`.
|
|
87
|
+
- **Storage Helpers:** `lastConnectedConnectorHelpers`, `recentConnectedConnectorHelpers`, `impersonatedHelpers`.
|
|
88
|
+
- **Core Primitives:** `isSafeApp`, `delay`, `waitFor`, `filterUniqueByKey`.
|
|
183
89
|
|
|
184
|
-
|
|
90
|
+
---
|
|
185
91
|
|
|
186
92
|
## 📄 License
|
|
187
93
|
|
|
188
|
-
|
|
94
|
+
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-core",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.12",
|
|
4
4
|
"private": false,
|
|
5
5
|
"author": "Oleksandr Tkach",
|
|
6
6
|
"license": "Apache-2.0",
|
|
7
|
-
"description": "
|
|
7
|
+
"description": "Tier 1 of the TUWA Ecosystem. Framework-agnostic library for abstracting core multi-chain types, errors, and localStorage helper utilities.",
|
|
8
8
|
"main": "./dist/index.js",
|
|
9
9
|
"module": "./dist/index.mjs",
|
|
10
10
|
"types": "./dist/index.d.ts",
|