Introduction

Welcome to Pulsar — the headless-first, local-first transaction lifecycle tracking engine engineered for absolute application sovereignty.

Pulsar is The Tracker of the TUWA Ecosystem. It completely decouples transaction execution tracking from your interface, replacing fragile UI hooks with a robust, deterministic client-side state machine.

The Broken Web3 UX Standard

Most dApps look completely broken when the network is congested. Standard developer workflows rely on basic RPC broadcasts and blind polling, failing completely under production stress. If you are building tracking manually, you are likely trapped in a maze of edge cases:

• Dropped Context on Reload: If a user refreshes the page while a transaction is pending, your client-side tracking state is wiped out.

• Blind Replacement Invalidation: When a user speeds up or cancels a transaction via their wallet, your dApp loses track of the transaction signature, throwing false errors or freezing loaders.

• Tight UI Coupling: Forcing local React useState hooks to manage complex tx states (isLoading, isSuccess) creates messy, fragmented, and non-persistent transaction pipelines.

Building this infra yourself takes months and distracts from your primary logic.

The Solution: Pulsar Engine

Pulsar provides the complete transactional “brain” locally on the client. It indexes and reconciles transaction states from the mempool (pending) to ultimate finality (replaced, confirmed, failed) entirely in the background, checkpointing everything directly to localStorage.

Pulsar handles the core state engineering, sitting firmly below your visual components and perfectly integrating into cloud persistence layers like the Quasar SDK.

[!NOTE] Pulsar does not ship pre-bundled visual nodes natively; layout rendering is strictly delegated to the Nova UI Kit layer, while cloud state sync mapping is handled by the Quasar SDK.

                      (The Baseline Core Foundation)
┌───────────────────────────────────────────┐
│          @tuwaio/pulsar-core (Tier 3)     │
│  • Framework-Agnostic Headless Store      │
│  • Local Storage Append-Only Ledger       │
└───────────────────┬───────────────────────┘
                    │ (Isolated Network Adapters)
┌───────────────────▼───────────────────────┐
│     @tuwaio/pulsar-evm / pulsar-solana    │
│  • EVM (Viem/Wagmi) & Solana (Gill) Logic │
│  • Standard, Safe Multi-Sig, Gelato Pipes │
└───────────────────┬───────────────────────┘
                    │ (React Hook Bindings)
┌───────────────────▼───────────────────────┐
│       @tuwaio/pulsar-react (Tier 4)       │
│  • `usePulsarStore` & `executeTxAction`   │
└───────────────────┬───────────────────────┘
                    │ (Visual Logic Execution Layer)
┌───────────────────▼───────────────────────┐
│     @tuwaio/nova-transactions (UI Kit)    │
│  • Pure Visual Rendering: Modals & Toasts │
└───────────────────┬───────────────────────┘
                    │
┌───────────────────▼───────────────────────┐
│       Your Application (React, Next.js)   │
└───────────────────────────────────────────┘

✨ Core Engineering Features

• 🧠 Headless Purist Architecture: Controlled via an ultra-fast, framework-agnostic Zustand store. Zero rendering overhead, zero forced UI design lock-in.

• ⛓️ Pure Multi-Chain Adapters:

• EVM Adapter: Built strictly on viem and wagmi. Includes specialized tracking logic for contract wallets, Safe multi-sigs, and Gelato meta-transactions. Legacy ethers.js or web3.js is strictly prohibited.

• Solana Adapter: Built strictly on gill and @tuwaio/orbit-solana helpers to monitor fast-block lifecycles at the RPC level.

• 🔄 Local-First Resilience: Your transaction pool automatically checkpoints to localStorage. Pending trackers instantly resume execution lifecycle monitoring immediately upon client reboots or network reconnects.

• 🛠️ Strict Type Integrity: Built with zero-compromise strict TypeScript. Every payload, error state, and lifecycle swap is explicitly typed — absolutely no any parameters are allowed.

📦 Package Map

What’s Next?

1. Getting Started - Set up Pulsar in your project.
2. Quick Start - Implement your first tracked transaction in minutes.
3. API Reference - Dive deep into customization and advanced features.

Built with ❤️ by the TUWA Team