@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 (the genesis-hash chain ID "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", "solana:devnet" and "devnet" all become "devnet") and the RPC URL you configured for it. Pass the moniker to Wallet Standard calls as solana:devnet; to identify the chain elsewhere (SIWX, transactions, APIs), use its CAIP-2 chain ID from getSolanaChainId of @tuwaio/orbit-core. The adapter reads SOL balances, builds Solana Explorer links and resolves SNS names and avatars. Its watchConnectors reports every Wallet Standard wallet that registers or unregisters (watchAvailableSolanaConnectors from @tuwaio/orbit-solana), so a wallet list that follows the store’s watchConnectors shows a wallet whose extension registers it after the list was opened.
• Restore without a prompt: after a page load the store restores the last wallet with the adapter’s reconnect, a standard:connect with silent: true: a wallet that still trusts the site returns its account without a prompt, and one that does not is left alone. The adapter remembers the wallets it connected, and disconnecting without a connection sends standard:disconnect only to those, never to a wallet that other code or another store of the page connected.
• 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 . Accounts that offer solana:signOffchainMessage but not solana:signMessage (hardware wallet accounts may) sign the version 1 off-chain message  of the text instead, which SIWX servers accept as is. createSolanaMessageSigner builds such a signer for any wallet and account; its messageFormat option ('auto', 'message' or 'offchainMessage') forces one format. It is the signer of @tuwaio/orbit-solana that SIWX uses too, with errors that start with [SATELLITE-SOLANA].
• Transactions: a connection carries the Wallet Standard handle of its account as connectedAccount. Pass it to createSolanaTransactionSendingSigner of @tuwaio/orbit-solana (0.5 and later) for an @solana/kit sending signer, without React, for example for signAndSendSolanaTx of @tuwaio/pulsar-solana.
• 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 (with silent when you pass it) 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.7), @tuwaio/orbit-core (>=0.5), @tuwaio/orbit-solana (>=0.7.2), @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 { SOLANA_CHAIN_IDS } from '@tuwaio/orbit-core';
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_CHAIN_IDS.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 Full-Stack React guide .

🌐 External Services

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 .

📄 License

Licensed under the Apache-2.0 License. See the LICENSE  file for details.

Interfaces

• SolanaConnection
• SolanaMessageSignerOptions
• SolanaWatcherCallbacks
• SolanaWatcherConfig

Type Aliases

• ConnectorSolana
• SolanaMessageFormat
• SolanaSignerTarget

Functions

• connect
• createSolanaConnectionsWatcher
• createSolanaMessageSigner
• disconnect
• satelliteSolanaAdapter
• unwrapUiWalletHandles