Quasar

Quasar — це серверний бекенд екосистеми TUWA (Етап 3, «Бекенд та синхронізація»). Pulsar відстежує транзакцію в браузері, поки відкрита вкладка; Quasar продовжує відстежувати ту саму транзакцію на сервері до фінального статусу, зберігає історію вашого застосунку для всіх пристроїв і сповіщає ваш бекенд підписаними вебхуками. Ваш сервер взаємодіє з ним через @tuwaio/quasar-sdk.

🔄 Місце Quasar в архітектурі

Quasar підтримує як транзакції, підписані гаманцем у браузері (депозити, свопи, виклики смарт-контрактів), так і транзакції, підписані вашим бекендом (виведення коштів, автоматичні виплати, серверні релеї) без потреби у браузерному localStorage.


1. Wallet-signed flow (Browser + Server + Quasar)Browser (Pulsar store)                Your server                     Quasar API──────────────────────                ───────────                     ──────────executeTxAction  │ beforeTxProcess ──────────────────────────────────────────────▶  GET /v1/engine/monitoring/health  │ wallet signs, Pulsar starts tracking  │ onRemoteCreate(tx) ─────────────▶ Server Action / route                                        │ checks the SIWX session                                        │ quasar.pulsar.syncCreate ──▶ POST /v1/engine/pulsar/sync                                                                          │ tracks the transaction                                                                          │ (EVM, Safe, ERC-4337, EIP-5792, Solana)Nova Transactions history ◀──────── quasar.pulsar.getHistory ◀─────  GET /v1/engine/pulsar/history                                    Your webhook endpoint ◀────────── POST, signed with HMAC-SHA256 2. Server-signed flow (Backend-only, no browser store required)Your backend / payout worker                                          Quasar API────────────────────────────                                          ──────────signs & broadcasts tx (writes op to DB)  │ quasar.pulsar.syncCreate ─────────────────────────────────────▶  POST /v1/engine/pulsar/sync  │ (idempotent by txKey; includes lastValidBlockHeight on Solana)        │ reconciles against chain finalityYour webhook endpoint ◀────────────────────────────────────────────── POST, signed with HMAC-SHA256

Ключ зберігається на вашому сервері. Браузер ніколи не звертається до Quasar із секретним ключем: для клієнтських транзакцій браузер викликає ваш сервер, який перевіряє володіння гаманцем (через сесію SIWX) і викликає Quasar; для серверних виплат ваш бекенд викликає Quasar напряму після відправлення транзакції в мережу. Посібник із синхронізації транзакцій Quasar описує обидва сценарії.
Двофазне відстеження. Швидка фаза відстежує транзакцію одразу після синхронізації, а відкладена черга та щогодинний свіпер повторно перевіряють незавершені транзакції на випадок реорганізації блоків або затримок RPC-вузлів. Quasar підтримує всі трекери Pulsar: транзакції EVM, батчі EIP-5792, мультипідписи Safe, операції ERC-4337 та підписи Solana. Quasar Cloud наразі не відстежує мультипідписи Safe; вузол Community Edition підтримує їх повністю.
Вебхуки сповіщають ваш бекенд, коли транзакція досягає термінального статусу (Success, Failed або Replaced). Див. розділ Вебхуки.

⛓️ Фіналізація, експірація та звірка станів

Quasar і Pulsar використовують однакові правила трекерів у кожній мережі, щоб ваша база даних та вебхуки фіксували лише детерміновані фінальні стани:

Мережа / Трекер	Проміжні оновлення	Термінальний Success	Термінальний Failed / Replaced
Solana (`TransactionTracker.Solana`)	Записує confirmationStatus: 'confirmed' та slot один раз після голосування супербільшості валідаторів (економить IOPS БД та оновлює UI)	Лише на рівні commitment finalized (confirmations: 'MAX')	Миттєвий Failed, якщо getSignatureStatuses повертає ончейн-помилку err на рівні confirmed; або Failed із помилкою простроченого blockhash, коли висота блоку кластера перевищує lastValidBlockHeight
EVM (`TransactionTracker.Ethereum`)	Лічильник підтверджень під час очікування потрібної глибини блоків	Чек зі status: 'success' після досягнення requiredConfirmations блоків	Failed при ончейн-реверті (status: 'reverted'); Replaced (із replacedTxHash), коли замість неї майниться транзакція пришвидшення або скасування з тим самим nonce
EIP-5792 (`TransactionTracker.EIP5792`)	Синхронізується за ID батчу (txKey); прив’язується до хешу виконання через quasar.pulsar.syncHash(txKey, hash)	Відстежується ончейн як стандартна EVM-транзакція після прикріплення хешу	Failed, якщо транзакція виконання ревертиться або якщо хеш не прикріплено протягом 1 години після синхронізації
ERC-4337 (`TransactionTracker.ERC4337`)	Опитує бандлер щодо включення userOpHash	Транзакція бандла досягає фінальності з результатом success: true	Failed, якщо бандлер відхиляє операцію або виконання UserOperation ревертиться ончейн

Solana lastValidBlockHeight та стійкість getTransaction: функція signAndSendSolanaTx із @tuwaio/pulsar-solana автоматично зберігає lastValidBlockHeight; під час синхронізації серверної транзакції Solana передавайте lastValidBlockHeight у quasar.pulsar.syncCreate. Щойно висота блоку кластера (getBlockHeight) перевищує lastValidBlockHeight, а підпис досі невідомий мережі, транзакція фізично не може бути включена в блок і миттєво отримує статус Failed (expired) без очікування умовного таймауту. Після підтвердження трекер запитує fee, recentBlockhash та instructions через getTransaction (підтримуються legacy, v0 та v1); помилка RPC у getTransaction ніколи не скасовує вже фіналізований підпис.
Некастодіальна межа та повторна трансляція (rebroadcasting): Ні Pulsar, ні Quasar ніколи не зберігають приватні ключі чи сирі підписані байти транзакцій. Якщо ваш бекенд підписує виведення коштів і повторно транслює ту саму підписану транзакцію в мережу до настання lastValidBlockHeight, зберігайте сирі підписані байти у своєму сервісі відправлення; повторний виклик quasar.pulsar.syncCreate із тим самим txKey є ідемпотентним (duplicate: true), поки Quasar веде підпис до finalized або закінчення терміну дії blockhash.
Серверне відновлення та повторні спроби: Щогодинний свіпер повторно ставить у чергу незавершені транзакції, які зупинилися через збій RPC, а будь-яку транзакцію у статусі Failed/Replaced або таку, що перебуває в очікуванні понад 60 секунд, можна перезапустити з панелі керування або через POST /v1/engine/pulsar/sync/retry/:txKey.

☁️ Quasar Cloud та Quasar Community

Quasar доступний у двох редакціях з однаковим ядром відстеження та однаковим API, тому @tuwaio/quasar-sdk працює з обома — змінюється лише baseUrl.

	Quasar Cloud	Quasar Community Edition
Хостинг	Керується TUWA: API на https://api.tuwa.io, панель на quasar.tuwa.io	Ваші сервери через Docker Compose (TuwaIO/quasar-community, Apache-2.0)
Мультитенантність	Організації з учасниками та кількома застосунками в кожній	Однотенантний режим: один адміністратор
Вхід у панель	Акаунти з входом через гаманець SIWX та ключі доступу (passkeys)	Email, пароль та двофакторна автентифікація TOTP в адмінці Payload (/admin)
Квоти	Облік на організацію; безкоштовно під час публічної бети (1 000 одиниць квоти на кожну організацію)	Встановлені так високо, що не обмежують роботу окремого вузла
Провайдери RPC	Ваші власні (обов’язково): RPC-ендпоінт, ключ Alchemy або QuickNode у налаштуваннях кожного застосунку	Ваші власні з опціональними резервними ключами та публічними ендпоінтами оператора
Email-сповіщення	Листи онбордингу та сповіщення про вичерпання квоти	Немає

Quasar Cloud перебуває у статусі безкоштовної публічної бети: платна квота наразі недоступна, а під час бети функції та ліміти можуть змінюватися. Community Edition не містить входу через SIWX, passkeys, транзакційних листів і білінгу. Щоб перенести організацію з Quasar Cloud на власний сервер разом із ключами та історією, див. Перехід із Quasar Cloud на Community; щоб розгорнути вузол з нуля — Self-Hosting.

Який шлях підходить вашому стеку

Serverless або edge-бекенди (Vercel, Cloudflare Workers): Використовуйте Quasar Cloud. Очікування ~13–15 секунд на фіналізацію блоку в Solana або підтвердження в EVM всередині serverless-функції спалює ліміти часу виконання й призводить до таймаутів, а підтримка повного Docker-стеку Quasar Community Edition (NestJS, BullMQ, Redis, Payload) є зайвим навантаженням для невеликої команди. Із Quasar Cloud ваш обробник робить один виклик quasar.pulsar.syncCreate, миттєво завершує роботу й отримує підписаний вебхук після фіналізації транзакції.
Власний фоновий воркер або cron із власною БД (без Quasar): Якщо вам потрібен лише цикл опитування мережі та перевірки фінальності/експірації всередині вашого існуючого воркера, імпортуйте автономні headless-трекери напряму з @tuwaio/pulsar-solana (solanaFetcher + initializePollingTracker) або @tuwaio/pulsar-evm — жоден із них не потребує React, браузера чи localStorage.
Власна серверна інфраструктура: Запускайте Quasar Community Edition через Docker Compose на власному VPS або виділеному сервері, коли вам потрібні повноцінний сервіс індексації, API міжпристроєвої історії, воркер вебхуків та адмін-панель на власній інфраструктурі.

📚 Наступні кроки

Створіть застосунок і отримайте ключі: Застосунки та ключі.
Синхронізуйте транзакції вашого React-застосунку: Посібник із синхронізації транзакцій Quasar, або повний приклад у посібнику Full-Stack React застосунок.
Приймайте вебхуки, зокрема на localhost: Вебхуки.
Перегляньте ендпоінти у Довіднику API, а клієнтську бібліотеку — у довіднику @tuwaio/quasar-sdk .