@tuwaio/orbit-solana 0.2.6 → 0.2.10
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 +34 -132
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -1,171 +1,73 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @tuwaio/orbit-solana
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@tuwaio/orbit-solana)
|
|
4
4
|
[](./LICENSE)
|
|
5
|
-
[](https://github.com/TuwaIO/orbit/actions)
|
|
6
5
|
|
|
7
|
-
Solana-specific
|
|
6
|
+
`@tuwaio/orbit-solana` provides concrete implementations of low-level Solana-specific communication primitives for Tier 2 of the TUWA Orbit stack. Engineered strictly on top of **`gill`** (the modern high-performance alternative to legacy Solana web3.js classes), this package integrates Wallet Standard capabilities for discovery and persistent caching of RPC connections.
|
|
8
7
|
|
|
9
8
|
---
|
|
10
9
|
|
|
11
|
-
## 🏛️
|
|
10
|
+
## 🏛️ Core Capabilities
|
|
12
11
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
---
|
|
18
|
-
|
|
19
|
-
## ✨ Key Features
|
|
20
|
-
|
|
21
|
-
- **RPC Client Management:** Efficiently creates and caches Solana RPC clients (`SolanaClient` and lower-level `RPC`) using `gill` (`createSolanaClientWithCache`, `createSolanaRPC`). Supports default and custom RPC URLs.
|
|
22
|
-
- **Wallet Standard Integration:** Discovers available Solana wallets compatible with the Wallet Standard (`getAvailableSolanaConnectors`). Retrieves the currently connected wallet based on stored address (`getConnectedSolanaConnector`).
|
|
23
|
-
- **Account Info Resolution:** Fetches user-set account labels (names) and icons (avatars) directly from the connected wallet's accounts (`getSolanaAddressName`, `getSolanaAddressAvatar`), including caching.
|
|
24
|
-
- **Cluster & RPC URL Helpers:** Utilities to parse cluster names (e.g., 'mainnet', 'devnet') from chain IDs and retrieve corresponding RPC URLs (`getCluster`, `getRpcUrlForCluster`).
|
|
25
|
-
- **Explorer Link Generation:** Creates links to Solana explorers (like Solscan) for transactions, addresses, etc., correctly handling cluster parameters (`getSolanaExplorerLink`).
|
|
26
|
-
- **Type-Safe Development:** Fully typed using TypeScript 5.9+.
|
|
27
|
-
- **Optimized Bundling:** Built with `tsup` for efficient CommonJS and ESM outputs with tree-shaking.
|
|
12
|
+
- **Gill RPC Caching:** Creates and caches high-performance Solana RPC connections (`createSolanaClientWithCache`, `createSolanaRPC`) to optimize transaction dispatching and query pipelines.
|
|
13
|
+
- **Wallet Standard Integration:** Low-level discovery routines (`getAvailableSolanaConnectors`, `getConnectedSolanaConnector`) that strictly align with the `@wallet-standard/app` specifications.
|
|
14
|
+
- **Profile Metadata Engine:** Resolves user-defined account descriptors (names, avatars) directly from Wallet Standard providers.
|
|
15
|
+
- **Cluster Parameter Resolution:** Maps Solana RPC clusters (mainnet, devnet, testnet) to explorer endpoints and RPC configurations.
|
|
28
16
|
|
|
29
17
|
---
|
|
30
18
|
|
|
31
19
|
## 💾 Installation
|
|
32
20
|
|
|
33
|
-
### Requirements
|
|
34
|
-
|
|
35
|
-
- Node.js 20-24
|
|
36
|
-
- TypeScript 5.9+
|
|
37
|
-
- `@tuwaio/orbit-core` (as a foundational peer dependency)
|
|
38
|
-
|
|
39
21
|
```bash
|
|
40
|
-
# Using pnpm (recommended), but you can use npm, yarn or bun as well
|
|
41
22
|
pnpm add @tuwaio/orbit-solana @tuwaio/orbit-core gill @wallet-standard/app @wallet-standard/ui-core @wallet-standard/ui-registry
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
*Note: `@tuwaio/orbit-core`, `gill`, `@wallet-standard/app`, `@wallet-standard/ui-core`, and `@wallet-standard/ui-registry` are **peer dependencies** and must be installed alongside `@tuwaio/orbit-solana`*.
|
|
45
|
-
|
|
46
|
-
-----
|
|
23
|
+
```
|
|
47
24
|
|
|
48
|
-
|
|
25
|
+
> [!IMPORTANT]
|
|
26
|
+
> `gill` and `@wallet-standard` packages are peer dependencies and must be installed alongside `@tuwaio/orbit-solana`.
|
|
49
27
|
|
|
50
|
-
|
|
28
|
+
---
|
|
51
29
|
|
|
52
|
-
|
|
30
|
+
## 🚀 Technical Integration
|
|
53
31
|
|
|
54
|
-
|
|
55
|
-
import { getAvailableWallets } from '@tuwaio/orbit-solana';
|
|
56
|
-
|
|
57
|
-
const wallets = getAvailableWallets();
|
|
58
|
-
console.log('Available Solana Wallets:', wallets.map(w => w.name));
|
|
59
|
-
// Example Output: ['Phantom', 'MetaMask', ...]
|
|
60
|
-
```
|
|
32
|
+
### Cached RPC Connection
|
|
61
33
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
Get a `gill` SolanaClient instance for interacting with the mainnet. Caching ensures you reuse the same client instance.
|
|
34
|
+
Establish cached RPC endpoints dynamically:
|
|
65
35
|
|
|
66
36
|
```typescript
|
|
67
37
|
import { createSolanaClientWithCache } from '@tuwaio/orbit-solana';
|
|
68
38
|
|
|
69
|
-
//
|
|
70
|
-
const
|
|
71
|
-
console.log('Mainnet Client:', mainnetClient);
|
|
72
|
-
|
|
73
|
-
// Get client using a custom RPC URL
|
|
74
|
-
const customClient = createSolanaClientWithCache({ rpcUrlOrMoniker: 'https://my-custom-rpc.com' });
|
|
75
|
-
console.log('Custom Client:', customClient);
|
|
76
|
-
|
|
77
|
-
// Get client for devnet, potentially using custom URLs if provided
|
|
78
|
-
const devnetClient = createSolanaClientWithCache({
|
|
79
|
-
rpcUrlOrMoniker: 'devnet',
|
|
80
|
-
rpcUrls: { devnet: 'https://api.devnet.solana.com' } // Optional: Provide specific URLs
|
|
81
|
-
});
|
|
82
|
-
console.log('Devnet Client:', devnetClient);
|
|
83
|
-
|
|
84
|
-
// You can now use the client, e.g., mainnetClient.rpc.getBalance(...)
|
|
39
|
+
// Obtain cached connection primitive
|
|
40
|
+
const client = createSolanaClientWithCache({ rpcUrlOrMoniker: 'mainnet' });
|
|
85
41
|
```
|
|
86
42
|
|
|
87
|
-
###
|
|
43
|
+
### Wallet Standard Discovery
|
|
88
44
|
|
|
89
|
-
|
|
45
|
+
Query the browser runtime for installed Wallet Standard adapters:
|
|
90
46
|
|
|
91
47
|
```typescript
|
|
92
|
-
import {
|
|
93
|
-
import { lastConnectedConnectorHelpers } from '@tuwaio/orbit-core'; // Needed to know which address is connected
|
|
94
|
-
|
|
95
|
-
async function displayAccountName() {
|
|
96
|
-
const connectedWalletInfo = lastConnectedConnectorHelpers.getLastConnectedConnector();
|
|
97
|
-
if (connectedWalletInfo?.address && connectedWalletInfo.walletType.startsWith('solana:')) {
|
|
98
|
-
try {
|
|
99
|
-
const name = await getSolanaAddressName(connectedWalletInfo.address);
|
|
100
|
-
console.log(`Label for address ${connectedWalletInfo.address}: ${name}`);
|
|
101
|
-
// If no label is set in the wallet, 'name' will be the address itself.
|
|
102
|
-
} catch (error) {
|
|
103
|
-
console.error("Could not get account name. Is a Solana wallet connected and registered?", error);
|
|
104
|
-
// This relies on getConnectedSolanaWallet finding the wallet via Wallet Standard registry
|
|
105
|
-
}
|
|
106
|
-
} else {
|
|
107
|
-
console.log("No Solana wallet seems to be connected.");
|
|
108
|
-
}
|
|
109
|
-
}
|
|
110
|
-
|
|
111
|
-
// Make sure Wallet Standard wallets are registered before calling this
|
|
112
|
-
// (This usually happens automatically when wallet extensions load)
|
|
113
|
-
setTimeout(displayAccountName, 1000); // Give wallets time to register
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
### Generate Explorer Link
|
|
117
|
-
|
|
118
|
-
Create a URL for a transaction on Solscan for the devnet cluster.
|
|
119
|
-
|
|
120
|
-
```typescript
|
|
121
|
-
import { getSolanaExplorerLink } from '@tuwaio/orbit-solana';
|
|
48
|
+
import { getAvailableSolanaConnectors } from '@tuwaio/orbit-solana';
|
|
122
49
|
|
|
123
|
-
const
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
50
|
+
const connectors = getAvailableSolanaConnectors();
|
|
51
|
+
console.log(
|
|
52
|
+
'Available Standard Adapters:',
|
|
53
|
+
connectors.map((c) => c.name),
|
|
54
|
+
);
|
|
127
55
|
```
|
|
128
56
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
## 🔧 Architecture
|
|
132
|
-
|
|
133
|
-
`@tuwaio/orbit-solana` serves as the **adapter implementation** for `OrbitAdapter.SOLANA`, integrating Solana-specific functionalities into the Orbit Utils framework.
|
|
134
|
-
|
|
135
|
-
### Core Modules & Exports (`index.ts`)
|
|
136
|
-
|
|
137
|
-
- **Types (`types.ts`)**: Defines Solana-specific types like `SolanaRPCUrls`.
|
|
138
|
-
- **Cluster Helpers (`clusterHelpers.ts`)**: Functions `getCluster` and `getRpcUrlForCluster` for managing Solana network identifiers and RPC endpoints.
|
|
139
|
-
- **Client Creation (`createSolanaClientWithCache.ts`, `createSolanaRPC.ts`)**: Provides cached instances of `gill`'s `SolanaClient` and `RPC`. Includes default RPC URLs.
|
|
140
|
-
- **Wallet Interaction (`getAvailableSolanaConnectors.ts`, `getConnectedSolanaConnector.ts`)**: Leverages `@wallet-standard` to find and identify Solana wallets.
|
|
141
|
-
- **Account Info (`getSolanaAddressAvatar.ts`, `getSolanaAddressName.ts`)**: Retrieves metadata (label, icon) associated with accounts within the connected wallet.
|
|
142
|
-
- **Explorer Links (`getSolanaExplorerLink.ts`)**: Utility for constructing explorer URLs.
|
|
143
|
-
|
|
144
|
-
### Build System
|
|
145
|
-
|
|
146
|
-
- Built using `tsup`.
|
|
147
|
-
- Outputs CommonJS (`cjs`) and ECMAScript Module (`esm`) formats.
|
|
148
|
-
- Generates TypeScript declaration files (`.d.ts`).
|
|
149
|
-
- Specifies external dependencies (`@tuwaio/orbit-core`, `gill`, `@wallet-standard/*`) to avoid bundling them.
|
|
150
|
-
|
|
151
|
-
-----
|
|
152
|
-
|
|
153
|
-
## ✨ How It Connects to the Ecosystem
|
|
154
|
-
|
|
155
|
-
- **Depends on `@tuwaio/orbit-core`:** Relies on core types (`OrbitAdapter`, `BaseAdapter`) and utilities (`lastConnectedConnectorHelpers`, `filterUniqueByKey`).
|
|
156
|
-
- **Provides Solana Functionality:** Implements the specific logic for Solana interactions needed by applications using Orbit Utils.
|
|
157
|
-
- **Leverages Gill & Wallet Standard:** Uses `gill` for simplified RPC communication and the Wallet Standard packages for wallet detection and interaction.
|
|
158
|
-
|
|
159
|
-
-----
|
|
57
|
+
---
|
|
160
58
|
|
|
161
|
-
##
|
|
59
|
+
## 🔧 API & Module Architecture
|
|
162
60
|
|
|
163
|
-
|
|
61
|
+
`@tuwaio/orbit-solana` exposes the following modules:
|
|
164
62
|
|
|
165
|
-
|
|
63
|
+
- **RPC Factory:** `createSolanaClientWithCache`, `createSolanaRPC`.
|
|
64
|
+
- **Connector Discovery:** `getAvailableSolanaConnectors`, `getConnectedSolanaConnector`.
|
|
65
|
+
- **Account Resolvers:** `getSolanaAddressName`, `getSolanaAddressAvatar`.
|
|
66
|
+
- **Network Helpers:** `getCluster`, `getRpcUrlForCluster`.
|
|
67
|
+
- **Explorer Helpers:** `getSolanaExplorerLink`.
|
|
166
68
|
|
|
167
|
-
|
|
69
|
+
---
|
|
168
70
|
|
|
169
71
|
## 📄 License
|
|
170
72
|
|
|
171
|
-
|
|
73
|
+
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-solana",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.10",
|
|
4
4
|
"private": false,
|
|
5
5
|
"author": "Oleksandr Tkach",
|
|
6
6
|
"license": "Apache-2.0",
|
|
7
|
-
"description": "
|
|
7
|
+
"description": "Tier 2 of the TUWA Ecosystem. Low-level Solana-specific communication primitives and RPC caching utilities powered strictly by gill.",
|
|
8
8
|
"main": "./dist/index.js",
|
|
9
9
|
"module": "./dist/index.mjs",
|
|
10
10
|
"types": "./dist/index.d.ts",
|
|
@@ -46,10 +46,10 @@
|
|
|
46
46
|
"tsup": "^8.5.1",
|
|
47
47
|
"typescript": "^6.0.3",
|
|
48
48
|
"gill": "^0.14.0",
|
|
49
|
-
"@wallet-standard/app": "^1.1.
|
|
50
|
-
"@wallet-standard/ui-core": "^1.0.
|
|
51
|
-
"@wallet-standard/ui-registry": "^1.1.
|
|
52
|
-
"@tuwaio/orbit-core": "^0.2.
|
|
49
|
+
"@wallet-standard/app": "^1.1.1",
|
|
50
|
+
"@wallet-standard/ui-core": "^1.0.1",
|
|
51
|
+
"@wallet-standard/ui-registry": "^1.1.1",
|
|
52
|
+
"@tuwaio/orbit-core": "^0.2.12"
|
|
53
53
|
},
|
|
54
54
|
"scripts": {
|
|
55
55
|
"start": "tsup src/index.ts --watch",
|