@tuwaio/orbit-solana 0.2.6 → 0.2.9
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 +38 -128
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -1,171 +1,81 @@
|
|
|
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
|
-
|
|
6
|
+
`@tuwaio/orbit-solana` provides concrete implementations and utilities tailored specifically for the Solana blockchain. Built entirely in **TypeScript** and powered by **`gill`** (the modern improvement layer over `@solana/kit`), it acts as the Solana adapter for the Orbit Utils ecosystem, simplifying wallet discovery via standard specifications and optimizing RPC client performance.
|
|
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 clients (`createSolanaClientWithCache`, `createSolanaRPC`) to eliminate instantiation overhead.
|
|
13
|
+
- **Wallet Standard Support:** Dynamic wallet discovery (`getAvailableSolanaConnectors`) and active wallet retrieval (`getConnectedSolanaConnector`) conforming to the official `@wallet-standard` specifications.
|
|
14
|
+
- **Account Metadata Lookups:** Retrieves user-defined account labels (names) and icons (avatars) directly from connected Wallet Standard accounts with cache persistence.
|
|
15
|
+
- **Cluster Moniker Helpers:** Utilities to resolve Solana cluster parameters (mainnet, devnet, testnet) and fetch matching RPC nodes.
|
|
16
|
+
- **Explorer Link Factory:** Generates explorer URLs (e.g. Solscan) automatically handling the active cluster parameters.
|
|
28
17
|
|
|
29
18
|
---
|
|
30
19
|
|
|
31
20
|
## 💾 Installation
|
|
32
21
|
|
|
33
|
-
### Requirements
|
|
34
|
-
|
|
35
|
-
- Node.js 20-24
|
|
36
|
-
- TypeScript 5.9+
|
|
37
|
-
- `@tuwaio/orbit-core` (as a foundational peer dependency)
|
|
38
|
-
|
|
39
22
|
```bash
|
|
40
|
-
# Using pnpm (recommended), but you can use npm, yarn or bun as well
|
|
41
23
|
pnpm add @tuwaio/orbit-solana @tuwaio/orbit-core gill @wallet-standard/app @wallet-standard/ui-core @wallet-standard/ui-registry
|
|
42
|
-
|
|
24
|
+
```
|
|
43
25
|
|
|
44
|
-
|
|
26
|
+
> [!IMPORTANT]
|
|
27
|
+
> `gill` and `@wallet-standard` packages are peer dependencies and must be installed alongside `@tuwaio/orbit-solana`.
|
|
45
28
|
|
|
46
|
-
|
|
29
|
+
---
|
|
47
30
|
|
|
48
31
|
## 🚀 Quick Start
|
|
49
32
|
|
|
50
|
-
###
|
|
33
|
+
### Wallet Discovery
|
|
51
34
|
|
|
52
|
-
|
|
35
|
+
Locate installed wallets supporting the modern Wallet Standard:
|
|
53
36
|
|
|
54
37
|
```typescript
|
|
55
|
-
import {
|
|
38
|
+
import { getAvailableSolanaConnectors } from '@tuwaio/orbit-solana';
|
|
56
39
|
|
|
57
|
-
const wallets =
|
|
58
|
-
console.log(
|
|
59
|
-
|
|
40
|
+
const wallets = getAvailableSolanaConnectors();
|
|
41
|
+
console.log(
|
|
42
|
+
'Detected Wallets:',
|
|
43
|
+
wallets.map((w) => w.name),
|
|
44
|
+
); // ['Phantom', 'Solflare', ...]
|
|
60
45
|
```
|
|
61
46
|
|
|
62
|
-
###
|
|
47
|
+
### Cached RPC Operations
|
|
63
48
|
|
|
64
|
-
|
|
49
|
+
Obtain a cached public Solana client for network requests:
|
|
65
50
|
|
|
66
51
|
```typescript
|
|
67
52
|
import { createSolanaClientWithCache } from '@tuwaio/orbit-solana';
|
|
68
53
|
|
|
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(...)
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
### Get Account Name/Label from Connected Wallet
|
|
88
|
-
|
|
89
|
-
Assuming a wallet is connected and its address is stored (e.g., using `lastConnectedWalletHelpers` from `orbit-core`), get the user-defined label for that address.
|
|
90
|
-
|
|
91
|
-
```typescript
|
|
92
|
-
import { getSolanaAddressName } from '@tuwaio/orbit-solana';
|
|
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.
|
|
54
|
+
// Obtain cached mainnet client
|
|
55
|
+
const client = createSolanaClientWithCache({ rpcUrlOrMoniker: 'mainnet' });
|
|
119
56
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
const txHash = '2y...'; // Example transaction hash
|
|
124
|
-
const devnetExplorerUrl = getSolanaExplorerLink(`/tx/${txHash}`, 'devnet');
|
|
125
|
-
console.log(devnetExplorerUrl);
|
|
126
|
-
// Output: [https://solscan.io/tx/2y...?cluster=devnet](https://solscan.io/tx/2y...?cluster=devnet) (or similar, base URL from gill)
|
|
57
|
+
// Perform RPC actions
|
|
58
|
+
// const balance = await client.rpc.getBalance(address).send();
|
|
127
59
|
```
|
|
128
60
|
|
|
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
|
|
61
|
+
---
|
|
154
62
|
|
|
155
|
-
|
|
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.
|
|
63
|
+
## 🔧 API & Module Architecture
|
|
158
64
|
|
|
159
|
-
|
|
65
|
+
`@tuwaio/orbit-solana` exports the following modules:
|
|
160
66
|
|
|
161
|
-
|
|
67
|
+
- **RPC Client Factory:** `createSolanaClientWithCache`, `createSolanaRPC`.
|
|
68
|
+
- **Wallet Discoverer:** `getAvailableSolanaConnectors`, `getConnectedSolanaConnector`.
|
|
69
|
+
- **Account Info Resolvers:** `getSolanaAddressName`, `getSolanaAddressAvatar`.
|
|
70
|
+
- **Network Helpers:** `getCluster`, `getRpcUrlForCluster`.
|
|
71
|
+
- **URL Builder:** `getSolanaExplorerLink`.
|
|
162
72
|
|
|
163
|
-
|
|
73
|
+
---
|
|
164
74
|
|
|
165
|
-
|
|
75
|
+
## 🤝 Contributing
|
|
166
76
|
|
|
167
|
-
|
|
77
|
+
Please read our main **[Contribution Guidelines](https://github.com/TuwaIO/workflows/blob/main/CONTRIBUTING.md)** before submitting pull requests.
|
|
168
78
|
|
|
169
79
|
## 📄 License
|
|
170
80
|
|
|
171
|
-
|
|
81
|
+
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-solana",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.9",
|
|
4
4
|
"private": false,
|
|
5
5
|
"author": "Oleksandr Tkach",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -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.11"
|
|
53
53
|
},
|
|
54
54
|
"scripts": {
|
|
55
55
|
"start": "tsup src/index.ts --watch",
|