Skip to Content
Introduction

Introduction

Satellite Connect

TUWA Satellite delivers low-level, headless wallet connection orchestration primitives engineered for complete architectural control and self-custodial cryptographic identity.

[!IMPORTANT] Decoupling Notice: Satellite manages connection logic and session state orchestration; it does not touch visual rendering (Nova UI) or cross-device cloud persistence/metering (Quasar).

🏛️ Architecture & Overview

Satellite represents the connection orchestration layer of the TUWA Ecosystem, sitting between user agents and blockchain RPC protocols. It maps physical wallet standard actions to unified cryptographic identities and tracks session status inside a type-safe state engine.

By establishing strict framework-agnostic core logic, Satellite removes the need for vendor lock-in or custodial SDK pipelines.

Core Decoupled Pipeline:

  1. State Orchestration: @tuwaio/satellite-core provides a framework-agnostic Zustand-based state store maintaining absolute synchronization between multi-chain provider events and application sessions.
  2. Connection Primitives: @tuwaio/satellite-react offers context providers and hooks mapping state updates to the React component lifecycle.
  3. Low-Level Adapters: Chain adapters (@tuwaio/satellite-evm, @tuwaio/satellite-solana) isolate wagmi and gill clients, operating directly on client transport parameters.
  4. Cryptographic Auth: @tuwaio/satellite-siwe-next-auth bridges active sessions to SIWE validation standards on the server side using encrypted cookie storage.

✨ Architectural Features

  • Unified React Hooks & Contexts: Context providers and hooks (useSatelliteConnectStore) tracking the lifecycle of multiple connection instances.
  • Multi-Connection Sync: Manages concurrent connections across distinct chains with atomic state updates.
  • Direct EVM & Solana Integrations: Raw integration of EVM connections and Solana wallet providers.
  • Direct Primitives Usage: Operates directly on Wagmi, Viem, and Gill without vendor wrappers.
  • Server-Side SIWE Session Mapping: High-integrity server session validation mapped to Next.js API routes and cookies.
  • Decoupled Core Storage: Pure state store logic using Zustand and Immer.
  • SSR Compatibility: Optimized for modern server-rendered architectures (Next.js App Router).

🧩 Monorepo Modules

Satellite is built modularly to ensure isolated imports:

Core Modules

  • @tuwaio/satellite-core: Foundational state layer. Exposes the Zustand store, core type definitions, and direct event dispatch interfaces.
  • @tuwaio/satellite-react: React bindings mapping core store state to React components.

Low-Level Adapters

  • @tuwaio/satellite-evm: EVM network adapter connecting Viem clients and Wagmi watchers.
  • @tuwaio/satellite-solana: Solana network adapter wrapping Gill and the Wallet Standard API.

Cryptographic Authentication

  • @tuwaio/satellite-siwe-next-auth: Server-side signature validation adapter matching the SIWE standard and Next.js App Router routes.

🚀 Getting Started

Here is a basic example of how to set up the SatelliteConnectProvider in a React application (e.g., in your main layout.tsx or App.tsx).

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { satelliteEVMAdapter, createDefaultTransports } from '@tuwaio/satellite-evm';
import { SatelliteConnectProvider } from '@tuwaio/satellite-react';
import { EVMConnectorsWatcher } from '@tuwaio/satellite-react/evm';
import { SolanaConnectorsWatcher } from '@tuwaio/satellite-react/solana';
import { satelliteSolanaAdapter } from '@tuwaio/satellite-solana';
import { WagmiProvider } from 'wagmi';
import { ReactNode } from 'react';
import { createConfig } from '@wagmi/core';
import { injected } from '@wagmi/connectors';
import { mainnet, sepolia } from 'viem/chains';
import type { Chain } from 'viem/chains';
 
export const appEVMChains = [mainnet, sepolia] as readonly [Chain, ...Chain[]];
 
export const wagmiConfig = createConfig({
  connectors: [injected()],
  transports: createDefaultTransports(appEVMChains), // Automatically creates http transports
  chains: appEVMChains,
  ssr: true, // Enable SSR support if needed (e.g., in Next.js)
});
 
export const solanaRPCUrls = {
  devnet: 'https://api.devnet.solana.com',
};
 
const queryClient = new QueryClient();
 
export function Providers({ children }: { children: ReactNode }) {
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <SatelliteConnectProvider
          adapter={[satelliteEVMAdapter(wagmiConfig, appEVMChains), satelliteSolanaAdapter({ rpcUrls: solanaRPCUrls })]}
          autoConnect={true}
        >
          <EVMConnectorsWatcher wagmiConfig={wagmiConfig} />
          <SolanaConnectorsWatcher />
          {children}
        </SatelliteConnectProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

📚 Next Steps

Built with ❤️ by the TUWA Team 

Last updated on
Overview