Architecture Blueprints & Deep Dives

While individual package documentation provides granular, function-level API references, this hub is dedicated to high-level Web3 architecture, production battle-testing, and real-world execution recipes.

Web3 engineering fails when distributed ledger realities meet naive frontend assumptions: mempool congestion, dynamic gas spikes, dropped nonces, speed-up replacements, background tab throttling, and component unmounting. The blueprints documented here resolve these systemic issues using local-first, headless, and self-custodial architectural patterns.

Important

Authoritative Specification for Developers & AI Agents
For the ground-truth system design rules, strict package isolation boundaries, inter-layer contracts, and agent behavior constraints across the entire ecosystem, consult workflows/TUWA_AGENTS.md. It serves as the single source of architectural truth for human engineers and autonomous agents alike.

Deep-Dive Guides

Comprehensive engineering breakdowns focused on solving systemic vulnerabilities in modern dApps:

🔐 Multi-Chain Authentication with SIWX (CAIP-122 Beyond EVM Silos)

Why EIP-4361 limits modern multi-chain applications, how CAIP-122 unifies EVM and Solana authentication into a single cryptographic boundary, and how to implement stateless, cryptographically verified sessions with anti-replay protection.

Focus: CAIP-122 protocol, cross-chain session synchronization, EIP-191/1271 & ed25519 signature verification.
Key Solution: Universal multi-chain authentication powered by @tuwaio/siwx.

⚡ Why Web3 Transaction State Management is Broken (And Why useState is an Anti-Pattern)

An in-depth investigation into why modeling blockchain writes with React useState leads to component unmount bugs, orphaned speed-up transactions, and desynchronized user sessions. Demonstrates how to decouple execution from the UI tree using headless state machines and nonce-aware lifecycle tracking.

Focus: Mempool mechanics, transaction replacements, cross-tab synchronization.
Key Solution: Decoupled transaction lifecycles powered by @tuwaio/pulsar-core.

🛡️ Demystifying ERC-4337: Sovereign Account Abstraction Without Proprietary WaaS

Why Account Abstraction does not require a proprietary WaaS platform, how the alternative mempool and userOpHash vs txHash lifecycle works, and how to build gas-optimized, sovereign smart accounts with Solady, Orbit EVM, Pulsar, and Quasar.

Focus: Canonical EntryPoint v0.7, Solady counterfactual accounts, Pimlico bundler/paymaster RPCs, Two-Stage UserOp tracking.
Key Solution: Sovereign, gas-sponsored smart accounts powered by @tuwaio/orbit-evm, @tuwaio/pulsar-core, and Quasar — managed cloud or self-hosted Community Edition.

Step-by-Step Guides

Hands-on setups that combine several TUWA packages:

🧭 Track Transactions in React with Pulsar

Add Pulsar to a React app for an EVM or a Solana wallet: a transaction store saved to localStorage, the chain adapter, tracking that resumes after a reload, and a button that sends a tracked contract or program call, with an optional ERC-4337 smart account variant.

Packages: @tuwaio/pulsar-core, @tuwaio/pulsar-evm or @tuwaio/pulsar-solana, @tuwaio/pulsar-react, Nova Connect.

🧱 Build a Full-Stack React App with the TUWA SDK

A Next.js app on @tuwaio/sdk for EVM or Solana: wallet connection with the Nova Connect modals, SIWX sign-in with server sessions, a Pulsar transaction store with the Nova Transactions modals and toasts, and a Server Action that knows which wallet is signed in.

Packages: @tuwaio/sdk, @tuwaio/evm-sdk or @tuwaio/solana-sdk.

☁️ Sync Transactions to Quasar

Continues the full-stack app: Server Actions that call Quasar after checking the SIWX session, a Pulsar store that syncs every new transaction, and the history of every device in the Nova modals.

Packages: @tuwaio/quasar-sdk, @tuwaio/sdk. Quasar itself is described in the Quasar docs.

Continues the full-stack app: a short-lived JWT for the wallet signed in with SIWX and the public keys that verify it, so Coinbase CDP custom authentication, other embedded wallet providers and your own services trust the same sign-in.

Packages: @tuwaio/sdk (/siwx/server, /siwx/server-next), @coinbase/cdp-hooks for the CDP example.

Continues the external auth setup: Supabase trusts the SIWX token as third-party auth, Row Level Security policies on the wallet address give each wallet only its own rows, and supabase-js sends the token from the browser and from Server Actions.

Packages: @tuwaio/sdk (/siwx, /siwx/server, /siwx/server-next), @supabase/supabase-js.

🚀 Starter Templates

Complete Next.js and Vite apps from Cosmos Playground — wallet connection, transaction tracking, SIWX sign-in and Quasar sync already wired together — and the CLI that creates a project from them.

Package API References

Looking for granular API references, hook signatures, type definitions, or installation instructions for individual packages?

All dedicated package documentation spaces (@tuwaio/siwx, @tuwaio/orbit, @tuwaio/satellite, @tuwaio/pulsar, @tuwaio/nova-uikit, @tuwaio/sdk, and @tuwaio/quasar-sdk) are indexed on our Main Screen. Visit the main portal to explore the complete interactive layer roadmap and jump directly into specific package documentation.

Quasar — apps and keys, quotas, webhooks, self-hosting the Community Edition and the API reference — is documented in the Quasar section of this hub.

Architectural Principles

Every blueprint in this repository adheres to three non-negotiable engineering principles:

Self-Custodial & Sovereign Architecture: Frontends stay self-custodial and do not require a closed-source, proprietary Wallet-as-a-Service (WaaS) platform. Client applications keep resilient, local-first state and can add Quasar for multi-device indexing, webhook delivery, and backend orchestration — as a managed cloud or as the open-source, self-hosted Community Edition (Apache-2.0) — without ever taking custody of user keys.
Headless Separation of Concerns: Core business logic lives in framework-agnostic stores (satellite, pulsar) and low-level protocol adapters (orbit). Presentation lives in disposable UI views (nova). Changes to UI styling never jeopardize underlying Web3 state machines.
Strict Type Safety & Zero Bloat: Zero tolerance for any types, legacy @solana/web3.js v1 bundles, or monolithic ethers.js packages. Only modern, tree-shakeable, high-performance primitives (viem, @solana/kit).