Introduction

Satellite Connect

Satellite Connect is the wallet connection project of TUWA Stage 2: a headless, framework-agnostic store for EVM and Solana wallet connections. It keeps the connected wallets and the active one outside your components, reconnects the last wallet after a page reload, follows account and network changes made in the wallet, and disconnects when a Sign-In With X session no longer matches the wallet, with no UI components and no hosted services.

🏛️ Where Satellite Connect Fits in TUWA

TUWA is built in stages. Each stage builds on the ones below it:

Stage	Projects	Role
1 — Core Auth & Primitives	SIWX , Orbit Utils	CAIP-122 authentication and multi-chain primitives
2 — State & Connection	Satellite Connect, Pulsar	Wallet connection state machine and transaction tracking
3 — Backend & Sync	Quasar Cloud or self-hosted Quasar Community	Transaction indexing and cross-device sync
4 — User Interface	Nova UI Kit	React design system and components

Satellite Connect builds on Orbit Utils (connector names, localStorage helpers, chain clients, ENS and SNS lookups). Nova Connect renders its state as connect modals, Pulsar reads the last connection it saves, and its watchers keep the wallet in line with a SIWX session; all of them are optional. The former @tuwaio/satellite-siwe-next-auth package is deprecated and replaced by SIWX .

🧭 Principles

Connections are state, not component logic: the wallets live in one store outside your components, so every component reads the same active connection, and the connection survives navigation and page reloads.
Headless and framework-agnostic: the store is a vanilla Zustand store with no UI. React bindings live in their own package, and connect modals in Nova Connect.
One store, many chains: chain logic lives in adapters that implement one contract. EVM and Solana wallets can be connected at the same time, with one of them active.
Modern Web3 libraries only: @wagmi/core and viem for EVM, the Wallet Standard and @solana/kit for Solana. No ethers.js, web3.js, @solana/web3.js or gill.
Self-custody, no hosted services: wallets connect directly through wagmi connectors and the Wallet Standard. There is no Wallet-as-a-Service and no backend of Satellite Connect’s own.
Transparent side effects: the package pages list what is saved to localStorage and which hosts are contacted.

🔄 How a Connection Works


connect({ connectorType, chainId })
  │ adapter.connect                               → the wallet asks the user to connect
  │ connections + activeConnection                → the store holds the new connection
  │ adapter.checkIsContractAddress                → isContractAddress (EVM smart accounts)
  │ callbackAfterConnected(connection)            → your code (optional)
  │ orbit-core:lastConnectedConnector             → saved to localStorage (read by auto-connect and Pulsar)
  ▼
chain watchers (EVM: wagmi events, Solana: Wallet Standard wallets)
  │ account or network changed in the wallet      → updateActiveConnection
  │ wallet disconnected, SIWX sign-in rejected,
  │ or wallet no longer matches the SIWX session  → disconnect
  ▼
disconnect(connectorType?)
  │ adapter.disconnect                            → the wallet disconnects
  │ other wallets still connected                 → the first one becomes active and is saved
  │ no wallet left                                → the saved connection is removed

After a reload, initializeAutoConnect reads the saved connection and connects the same wallet again, except wallets that need a user action (such as WalletConnect).

🧩 Packages

Package	Layer	Provides	Peer dependencies
`@tuwaio/satellite-core`	L3	Connection store, adapter contract, auto-connect, SIWX state type	`@tuwaio/orbit-core` ≥ 0.3, `zustand` 5.x, `immer` 11.x
`@tuwaio/satellite-evm`	L4	EVM adapter and watcher, contract account check, wagmi config helpers	`@tuwaio/satellite-core` ≥ 0.5, `@tuwaio/orbit-core` ≥ 0.3, `@tuwaio/orbit-evm` ≥ 0.3, `@wagmi/core` 3.x, `viem` 2.x
`@tuwaio/satellite-solana`	L4	Solana adapter and watcher, message signer	`@tuwaio/satellite-core` ≥ 0.5, `@tuwaio/orbit-core` ≥ 0.3, `@tuwaio/orbit-solana` ≥ 0.3, `@solana/kit` ≥ 8.2, `@wallet-standard/base`, `features`, `ui`, `ui-registry`
`@tuwaio/satellite-react`	L4	Provider, store hook, EVM and Solana watcher components	`@tuwaio/satellite-core` ≥ 0.5, `react` ≥ 19.2.3, `zustand` 5.x; for `/evm` and `/solana`: `@tuwaio/satellite-evm` or `@tuwaio/satellite-solana` and their libraries

Each package page shows the package README followed by a reference of every export, generated from the TypeScript source. The L4 chain packages also need the peers of @tuwaio/satellite-core and of the Orbit packages they use (for Solana, the @wallet-standard packages of @tuwaio/orbit-solana); the commands below install them.

💾 Installation

Install the core package and the L4 packages your app needs:


# L3 core
pnpm add @tuwaio/satellite-core @tuwaio/orbit-core zustand immer
 
# L4 EVM
pnpm add @tuwaio/satellite-evm @tuwaio/orbit-evm @wagmi/core viem
 
# L4 Solana
pnpm add @tuwaio/satellite-solana @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
 
# L4 React (add @wallet-standard/react and react-dom for @tuwaio/satellite-react/solana)
pnpm add @tuwaio/satellite-react react

📚 Next Steps

Browse the Packages section for usage examples and the full reference of each package. For a React app, start with @tuwaio/satellite-react.
Read the Multi-Chain Authentication guide for SIWX sign-in across EVM and Solana and how the connection watchers keep the wallet in line with the session.
Use ready-made connect and account modals from Nova Connect (Storybook).
Build a full-stack app with Nova Connect, SIWX, Pulsar and Quasar: see the TUWA SDK documentation .
Find more ecosystem guides at docs.tuwa.io/guides , and read the source on GitHub .