Introduction
Orbit Utils is the Stage 1 primitives layer of the TUWA ecosystem: headless, framework-agnostic helpers for talking to EVM and Solana networks. It provides cached RPC clients, wallet discovery, connection persistence, name resolution and ERC-4337 smart accounts as plain functions and types, with no UI, state management or framework bindings.
🏛️ Where Orbit Fits in TUWA
TUWA is built in stages. Each stage builds on the ones below it, and Orbit sits at the bottom:
| 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 |
Orbit depends on nothing else in TUWA. Higher layers import its types and helpers (for example, OrbitAdapter identifies the chain family in Satellite Connect and Pulsar), never the other way around. You can also use Orbit on its own in any app.
🧭 Principles
- Headless and framework-agnostic: no CSS, components, hooks or framework bindings. Everything is a plain function or type, usable from React, Vue, Svelte, Solid, Node.js or vanilla JavaScript.
- Modern Web3 libraries only:
viemand@wagmi/corefor EVM,@solana/kitand the Wallet Standard for Solana. Noethers.js,web3.js,@solana/web3.jsorgill. - Self-custody, no Wallet-as-a-Service: wallets stay with the user. Account abstraction uses open ERC-4337 infrastructure (Solady smart accounts, any Pimlico-compatible bundler) instead of proprietary wallet platforms.
- Peer dependencies, not bundled SDKs: chain libraries are peer dependencies, so your app controls their versions and keeps a single copy.
- Transparent side effects: helpers document when they write to
localStorage, cache in memory or call an external service. The Solana package lists every third-party host it contacts.
🧩 Packages
| Package | Layer | Provides | Peer dependencies |
|---|---|---|---|
@tuwaio/orbit-core | L1 | Multi-chain types, connector and address helpers, error normalization, SSR-safe connection storage | — |
@tuwaio/orbit-evm | L2 | Cached viem clients, chain switching, ENS resolution, ERC-4337 smart accounts (Solady + Pimlico) | viem 2.x, @wagmi/core 3.x |
@tuwaio/orbit-solana | L2 | Cached @solana/kit RPC clients, Wallet Standard discovery, cluster and explorer helpers, SNS lookups | @tuwaio/orbit-core, @solana/kit ≥ 8.2, @wallet-standard/* 1.x |
Each package page shows the package README followed by a reference of every export, generated from the TypeScript source.
💾 Installation
Install the core package and the chain packages your app targets:
# L1 core
pnpm add @tuwaio/orbit-core
# L2 EVM
pnpm add @tuwaio/orbit-evm @wagmi/core viem
# L2 Solana
pnpm add @tuwaio/orbit-solana @tuwaio/orbit-core @solana/kit @wallet-standard/app @wallet-standard/ui-core @wallet-standard/ui-registry📚 Next Steps
- Browse the Packages section for usage examples and the full reference of each package.
- Follow the ERC-4337 guide for an end-to-end smart account flow with Orbit EVM, Pulsar and Quasar.
- Find more ecosystem guides at docs.tuwa.io/guides .
- Read the source on GitHub .