@tuwaio/orbit-solana 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.
Files changed (2) hide show
  1. package/README.md +130 -23
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -4,54 +4,165 @@
4
4
  [![License](https://img.shields.io/npm/l/@tuwaio/orbit-solana.svg)](./LICENSE)
5
5
  [![Build Status](https://img.shields.io/github/actions/workflow/status/TuwaIO/orbit/release.yml?branch=main)](https://github.com/TuwaIO/orbit/actions)
6
6
 
7
- Solana blockchain implementation for the TUWA ecosystem, providing comprehensive utilities and helpers for interacting with Solana networks.
7
+ Solana-specific adapter implementation and utilities for the **Orbit Utils** ecosystem by **TUWA**. Provides helpers for interacting with Solana networks (mainnet, devnet, testnet) using **gill** and **Wallet Standard**.
8
8
 
9
9
  ---
10
10
 
11
11
  ## 🏛️ What is `@tuwaio/orbit-solana`?
12
12
 
13
- `@tuwaio/orbit-solana` is the Solana-focused extension of the TUWA ecosystem, built with TypeScript and designed for modern Web3 development. It provides specialized tools for interacting with Solana blockchain, including mainnet, devnet, and testnet networks.
13
+ `@tuwaio/orbit-solana` is the Solana-focused adapter within the **Orbit Utils** ecosystem, extending `@tuwaio/orbit-core` with functionalities specific to the Solana blockchain. It simplifies interactions with Solana wallets and RPC endpoints for UI development.
14
+
15
+ Built with **TypeScript**, this package utilizes **`gill`** (an improvement layer over `@solana/kit`) for RPC interactions and leverages the **Wallet Standard** (`@wallet-standard/app`, `@wallet-standard/ui-registry`) for wallet discovery and management. It provides essential tools for building user interfaces that connect to Solana.
14
16
 
15
17
  ---
16
18
 
17
19
  ## ✨ Key Features
18
20
 
19
- - **Modern Solana Support:** Built on latest gill (solana kit improver)
20
- - **Type-Safe Development:** Full TypeScript 5.9 support
21
- - **Tree-Shaking Optimized:** Efficient bundle size through careful exports.
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 (`getAvailableWallets`). Retrieves the currently connected wallet based on stored address (`getConnectedSolanaWallet`).
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.
22
28
 
23
29
  ---
24
30
 
25
31
  ## 💾 Installation
26
32
 
27
33
  ### Requirements
28
- - Node.js 20+
29
- - TypeScript 5.9+
34
+
35
+ - Node.js 20+
36
+ - TypeScript 5.9+
37
+ - `@tuwaio/orbit-core` (as a foundational peer dependency)
30
38
 
31
39
  ```bash
32
40
  # Using pnpm (recommended)
33
- pnpm add @tuwaio/orbit-solana gill @tuwaio/orbit-core @wallet-standard/app @wallet-standard/ui-core @wallet-standard/ui-registry
41
+ pnpm add @tuwaio/orbit-solana @tuwaio/orbit-core gill @wallet-standard/app @wallet-standard/ui-core @wallet-standard/ui-registry
34
42
 
35
43
  # Using npm
36
- npm install @tuwaio/orbit-solana gill @tuwaio/orbit-core @wallet-standard/app @wallet-standard/ui-core @wallet-standard/ui-registry
44
+ npm install @tuwaio/orbit-solana @tuwaio/orbit-core gill @wallet-standard/app @wallet-standard/ui-core @wallet-standard/ui-registry
37
45
 
38
46
  # Using yarn
39
- yarn add @tuwaio/orbit-solana gill @tuwaio/orbit-core @wallet-standard/app @wallet-standard/ui-core @wallet-standard/ui-registry
47
+ yarn add @tuwaio/orbit-solana @tuwaio/orbit-core gill @wallet-standard/app @wallet-standard/ui-core @wallet-standard/ui-registry
48
+ ````
49
+
50
+ *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`*.
51
+
52
+ -----
53
+
54
+ ## 🚀 Quick Start
55
+
56
+ ### Get Available Solana Wallets
57
+
58
+ Discover wallets installed by the user that support the Wallet Standard for Solana.
59
+
60
+ ```typescript
61
+ import { getAvailableWallets } from '@tuwaio/orbit-solana';
62
+
63
+ const wallets = getAvailableWallets();
64
+ console.log('Available Solana Wallets:', wallets.map(w => w.name));
65
+ // Example Output: ['Phantom', 'Backpack', ...]
66
+ ```
67
+
68
+ ### Create a Cached RPC Client
69
+
70
+ Get a `gill` SolanaClient instance for interacting with the mainnet. Caching ensures you reuse the same client instance.
71
+
72
+ ```typescript
73
+ import { createSolanaClientWithCache } from '@tuwaio/orbit-solana';
74
+
75
+ // Get client for mainnet using default RPC URL
76
+ const mainnetClient = createSolanaClientWithCache({ rpcUrlOrMoniker: 'mainnet' });
77
+ console.log('Mainnet Client:', mainnetClient);
78
+
79
+ // Get client using a custom RPC URL
80
+ const customClient = createSolanaClientWithCache({ rpcUrlOrMoniker: 'https://my-custom-rpc.com' });
81
+ console.log('Custom Client:', customClient);
82
+
83
+ // Get client for devnet, potentially using custom URLs if provided
84
+ const devnetClient = createSolanaClientWithCache({
85
+ rpcUrlOrMoniker: 'devnet',
86
+ rpcUrls: { devnet: 'https://api.devnet.solana.com' } // Optional: Provide specific URLs
87
+ });
88
+ console.log('Devnet Client:', devnetClient);
89
+
90
+ // You can now use the client, e.g., mainnetClient.rpc.getBalance(...)
40
91
  ```
41
- ---
92
+
93
+ ### Get Account Name/Label from Connected Wallet
94
+
95
+ 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.
96
+
97
+ ```typescript
98
+ import { getSolanaAddressName } from '@tuwaio/orbit-solana';
99
+ import { lastConnectedWalletHelpers } from '@tuwaio/orbit-core'; // Needed to know which address is connected
100
+
101
+ async function displayAccountName() {
102
+ const connectedWalletInfo = lastConnectedWalletHelpers.getLastConnectedWallet();
103
+ if (connectedWalletInfo?.address && connectedWalletInfo.walletType.startsWith('solana:')) {
104
+ try {
105
+ const name = await getSolanaAddressName(connectedWalletInfo.address);
106
+ console.log(`Label for address ${connectedWalletInfo.address}: ${name}`);
107
+ // If no label is set in the wallet, 'name' will be the address itself.
108
+ } catch (error) {
109
+ console.error("Could not get account name. Is a Solana wallet connected and registered?", error);
110
+ // This relies on getConnectedSolanaWallet finding the wallet via Wallet Standard registry
111
+ }
112
+ } else {
113
+ console.log("No Solana wallet seems to be connected.");
114
+ }
115
+ }
116
+
117
+ // Make sure Wallet Standard wallets are registered before calling this
118
+ // (This usually happens automatically when wallet extensions load)
119
+ setTimeout(displayAccountName, 1000); // Give wallets time to register
120
+ ```
121
+
122
+ ### Generate Explorer Link
123
+
124
+ Create a URL for a transaction on Solscan for the devnet cluster.
125
+
126
+ ```typescript
127
+ import { getSolanaExplorerLink } from '@tuwaio/orbit-solana';
128
+
129
+ const txHash = '2y...'; // Example transaction hash
130
+ const devnetExplorerUrl = getSolanaExplorerLink(`/tx/${txHash}`, 'devnet');
131
+ console.log(devnetExplorerUrl);
132
+ // Output: [https://solscan.io/tx/2y...?cluster=devnet](https://solscan.io/tx/2y...?cluster=devnet) (or similar, base URL from gill)
133
+ ```
134
+
135
+ -----
42
136
 
43
137
  ## 🔧 Architecture
44
138
 
45
- The package is structured around these core components:
139
+ `@tuwaio/orbit-solana` serves as the **adapter implementation** for `OrbitAdapter.SOLANA`, integrating Solana-specific functionalities into the Orbit Utils framework.
140
+
141
+ ### Core Modules & Exports (`index.ts`)
142
+
143
+ - **Types (`types.ts`)**: Defines Solana-specific types like `SolanaRPCUrls`.
144
+ - **Cluster Helpers (`clusterHelpers.ts`)**: Functions `getCluster` and `getRpcUrlForCluster` for managing Solana network identifiers and RPC endpoints.
145
+ - **Client Creation (`createSolanaClientWithCache.ts`, `createSolanaRPC.ts`)**: Provides cached instances of `gill`'s `SolanaClient` and `Rpc`. Includes default RPC URLs.
146
+ - **Wallet Interaction (`getAvailableSolanaWallets.ts`, `getConnectedSolanaWallet.ts`)**: Leverages `@wallet-standard` to find and identify Solana wallets.
147
+ - **Account Info (`getSolanaAddressAvatar.ts`, `getSolanaAddressName.ts`)**: Retrieves metadata (label, icon) associated with accounts within the connected wallet.
148
+ - **Explorer Links (`getSolanaExplorerLink.ts`)**: Utility for constructing explorer URLs.
46
149
 
47
150
  ### Build System
48
- - Built with `tsup` for optimal bundling
49
- - Outputs both CommonJS and ESM formats
50
- - Generates TypeScript declarations
51
151
 
52
- ### Core Modules
53
- - **RPC Configuration:** Solana network connection utilities
54
- ---
152
+ - Built using `tsup`.
153
+ - Outputs CommonJS (`cjs`) and ECMAScript Module (`esm`) formats.
154
+ - Generates TypeScript declaration files (`.d.ts`).
155
+ - Specifies external dependencies (`@tuwaio/orbit-core`, `gill`, `@wallet-standard/*`) to avoid bundling them.
156
+
157
+ -----
158
+
159
+ ## ✨ How It Connects to the Ecosystem
160
+
161
+ - **Depends on `@tuwaio/orbit-core`:** Relies on core types (`OrbitAdapter`, `BaseAdapter`) and utilities (`lastConnectedWalletHelpers`, `filterUniqueByKey`).
162
+ - **Provides Solana Functionality:** Implements the specific logic for Solana interactions needed by applications using Orbit Utils.
163
+ - **Leverages Gill & Wallet Standard:** Uses `gill` for simplified RPC communication and the Wallet Standard packages for wallet detection and interaction.
164
+
165
+ -----
55
166
 
56
167
  ## 🤝 Contributing & Support
57
168
 
@@ -63,8 +174,4 @@ If you find this library useful, please consider supporting its development. Eve
63
174
 
64
175
  ## 📄 License
65
176
 
66
- This project is licensed under the **Apache-2.0 License** - see the [LICENSE](./LICENSE) file for details.
67
-
68
- ## 👥 Contributors
69
-
70
- - **Oleksandr Tkach** - [GitHub](https://github.com/Argeare5)
177
+ This project is 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.1.0",
3
+ "version": "0.1.1",
4
4
  "private": false,
5
5
  "author": "Oleksandr Tkach",
6
6
  "license": "Apache-2.0",
@@ -49,7 +49,7 @@
49
49
  "@wallet-standard/app": "^1.1.0",
50
50
  "@wallet-standard/ui-core": "^1.0.0",
51
51
  "@wallet-standard/ui-registry": "^1.0.1",
52
- "@tuwaio/orbit-core": "^0.1.0"
52
+ "@tuwaio/orbit-core": "^0.1.1"
53
53
  },
54
54
  "scripts": {
55
55
  "start": "tsup src/index.ts --watch",