@tuwaio/satellite-solana

@tuwaio/satellite-solana is the Solana Layer 4 (L4) package of Satellite Connect, the wallet connection project of TUWA Stage 2 (“State & Connection”, next to Pulsar). Built on the Wallet Standard, @solana/kit and @tuwaio/orbit-solana (wallet discovery, cluster helpers and cached RPC clients), it provides the Solana adapter for @tuwaio/satellite-core, a watcher that copies wallet account changes into the store, and a message signer. It does not use the legacy @solana/web3.js or gill.

🏛️ Core Capabilities

Adapter: satelliteSolanaAdapter({ rpcUrls }) connects the Wallet Standard wallets found by getAvailableSolanaConnectors from @tuwaio/orbit-solana (Phantom, Solflare, Backpack…) by connector type, such as "solana:phantom". A connection stores the cluster as a moniker ("solana:devnet" and "devnet" both become "devnet") and the RPC URL you configured for it. The adapter reads SOL balances, builds Solana Explorer links and resolves SNS names and avatars.
No network switch in the wallet: Solana wallets have no network setting, so switchNetwork only changes the connection’s cluster and RPC URL in the store.
Message signing: every connection has a signMessage that uses the wallet’s solana:signMessage feature (with fallbacks for wallet adapters) and returns a base58 signature, for example for SIWX . createSolanaMessageSigner builds such a signer for any wallet and account.
Watcher: the Wallet Standard has no connection events, so createSolanaConnectionsWatcher checks the wallets it is given each time it runs: it copies the active account of the connected wallet into the store, disconnects when the wallet has no accounts left and, with a SIWX session, when the sign-in is rejected or fails or the account no longer matches the session. React apps use SolanaConnectorsWatcher from @tuwaio/satellite-react/solana, which runs it on every change of the registered wallets.
Wallet Standard helpers: connect and disconnect run the standard:connect and standard:disconnect features of a wallet; unwrapUiWalletHandles returns the wallet and account behind UI handles.

💾 Installation


pnpm add @tuwaio/satellite-solana @tuwaio/satellite-core @tuwaio/orbit-core @tuwaio/orbit-solana @solana/kit @wallet-standard/base @wallet-standard/features @wallet-standard/ui @wallet-standard/ui-registry @wallet-standard/app @wallet-standard/ui-core zustand immer

[!IMPORTANT] @tuwaio/satellite-core (>=0.5), @tuwaio/orbit-core (>=0.3), @tuwaio/orbit-solana (>=0.3), @solana/kit (>=8.2), @wallet-standard/base (1.1.x), @wallet-standard/features (1.1.x), @wallet-standard/ui (1.x) and @wallet-standard/ui-registry (1.x) are peer dependencies and must be installed alongside @tuwaio/satellite-solana. @wallet-standard/app and @wallet-standard/ui-core are the peer dependencies of @tuwaio/orbit-solana, and zustand and immer those of @tuwaio/satellite-core.

🚀 Usage


import { createSatelliteConnectStore } from '@tuwaio/satellite-core';
import { type ConnectorSolana, satelliteSolanaAdapter, type SolanaConnection } from '@tuwaio/satellite-solana';
 
export const solanaRPCUrls = {
  mainnet: 'https://api.mainnet-beta.solana.com', // use your own RPC provider in production
  devnet: 'https://api.devnet.solana.com',
};
 
export const satelliteStore = createSatelliteConnectStore<ConnectorSolana, SolanaConnection>({
  adapter: satelliteSolanaAdapter({ rpcUrls: solanaRPCUrls }),
});
 
export async function connectPhantom() {
  await satelliteStore.getState().connect({ connectorType: 'solana:phantom', chainId: 'solana:devnet' });
  const connection = satelliteStore.getState().activeConnection;
  return connection?.signMessage?.('Hello from Satellite Connect'); // base58 signature
}

Configure an RPC URL for every cluster you connect to: a cluster missing from rpcUrls gets the rate-limited public endpoint of that cluster as its rpcURL (the mainnet-beta one for localnet, and for every cluster with @tuwaio/orbit-solana 0.3.1 and earlier). The React setup with the watcher is on the @tuwaio/satellite-react page, and a full-stack app with Nova Connect, SIWX and Pulsar is in the TUWA SDK documentation .

🌐 External Services

Helper	Host	Purpose
Adapter `connect`, `disconnect`, `switchConnection`, signer	The wallet, through the Wallet Standard	Connecting and signing; the package sends no network request
Adapter `getBalance`	The URL of the cluster in `rpcUrls`, else the public endpoint of the cluster (`api.<cluster>.solana.com`)	`getBalance`
Adapter `getName`	`sns-api.bonfida.com`	Favorite SNS domain of the address
Adapter `getAvatar`	`image-api.bonfida.com`; `api.dicebear.com` for the fallback identicon (loaded by the browser when rendered)	SNS profile image of a `.sol` domain

The address or domain being looked up is sent to the Bonfida hosts, and @tuwaio/orbit-solana caches the results in memory. Explorer links point to explorer.solana.com and are not requested by the package. The RPC URLs are kept in memory only: @tuwaio/satellite-core does not save them to localStorage.

📚 API Reference

Every export, with signatures and types generated from the source, is documented at satellite.docs.tuwa.io/packages/satellite-solana .

@tuwaio/satellite-solana

🏛️ Core Capabilities

💾 Installation

🚀 Usage

🌐 External Services

📚 API Reference

📄 License

Interfaces

Type Aliases

Functions