Skip to Content
Quasar概览

Quasar

Quasar 是 TUWA 生态的服务端引擎（第 3 阶段，“服务端与状态同步”）。Pulsar 在浏览器标签页打开期间追踪交易；Quasar 则在服务器上持续追踪同一笔交易直至到达最终状态，为每个设备维护应用历史记录，并通过签名 Webhook 通知您的后端。您的服务器通过 @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 多签交易，自部署社区版节点则完全支持。
  • Webhook 回调 会在交易到达终态（Success、Failed 或 Replaced）时通知您的后端。 详见 Webhooks 回调.

⛓️ 最终确定性、过期判定与状态对账

Quasar 与 Pulsar 在每条链上遵循完全一致的追踪规则，确保您的数据库与 Webhook 仅在确定性的终态下结算：

区块链 / 追踪器中间状态更新终态 Success 条件终态 Failed / Replaced 条件
Solana (TransactionTracker.Solana)当超级多数验证者对该签名投票确认时，记录一次 confirmationStatus: 'confirmed' 与 slot（在更新 UI 的同时节省数据库 IOPS）仅在达到 finalized 最终确认级别时 (confirmations: 'MAX')若 getSignatureStatuses 在 confirmed 阶段返回链上 err，则立即标记为 Failed；一旦集群区块高度超过 lastValidBlockHeight 且签名仍未上链，则立即以区块哈希过期标记为 Failed
EVM (TransactionTracker.Ethereum)等待区块深度期间更新确认块数 (confirmations)达到 requiredConfirmations 区块数且交易回执 status: 'success'链上回滚 (status: 'reverted') 时标记为 Failed；当相同 Nonce 的加速或取消交易先被打包时标记为 Replaced（附带 replacedTxHash）
EIP-5792 (TransactionTracker.EIP5792)按批次 ID (txKey) 同步；通过 quasar.pulsar.syncHash(txKey, hash) 关联实际执行哈希关联交易哈希后，按标准 EVM 交易规则在链上追踪至最终确认执行交易回滚时标记为 Failed；若同步后 1 小时内仍未关联哈希，同样标记为 Failed
ERC-4337 (TransactionTracker.ERC4337)轮询 Bundler 查询 userOpHash 是否打包上链打包交易达到区块最终确认且 UserOperation 执行结果为 success: trueBundler 拒绝该操作或链上 UserOperation 执行回滚时标记为 Failed
  • Solana lastValidBlockHeight 与 getTransaction 容错韧性： @tuwaio/pulsar-solana 的 signAndSendSolanaTx 会自动捕获 lastValidBlockHeight；当同步服务端签名的 Solana 交易时，请在 quasar.pulsar.syncCreate 中传入 lastValidBlockHeight。一旦集群区块高度 (getBlockHeight) 超过 lastValidBlockHeight 而签名仍未知，该交易在物理上已无法上链，系统会立即将其标记为 Failed（已过期），无需等待任意超时。确认后，追踪器通过 getTransaction 获取 fee、recentBlockhash 与 instructions（兼容 legacy、v0 与 v1 交易）；getTransaction 的 RPC 报错绝不会导致已 finalized 的签名失败或丢失。
  • 非托管边界与重复广播 (Rebroadcasting)： 无论是 Pulsar 还是 Quasar 都绝不存储私钥或原始签名交易字节。如果您的后端负责签署提现交易并在 lastValidBlockHeight 之前重复广播同一笔签名交易，请在您的广播服务中保留签名后的原始字节；使用相同 txKey 重复调用 quasar.pulsar.syncCreate 是完全幂等的 (duplicate: true)，Quasar 会持续追踪该签名直至 finalized 或区块哈希过期。
  • 服务端自愈与重试机制： 每小时巡检器会自动重新入队因 RPC 故障而停滞的挂起交易；任何处于 Failed/Replaced 终态或挂起超过 60 秒的交易，均可在控制台或通过 POST /v1/engine/pulsar/sync/retry/:txKey 手动触发重试。

☁️ Quasar Cloud 与 Quasar 社区版对比

Quasar 提供两个版本，共享完全相同的追踪引擎与 API，因此 @tuwaio/quasar-sdk 可无缝对接两者——只需更改 baseUrl。

Quasar Cloud（托管云）Quasar 社区版（自部署）
部署与托管由 TUWA 托管运维：API 位于 https://api.tuwa.io，控制台位于 quasar.tuwa.io部署在您自己的服务器上，通过 Docker Compose 启动 (TuwaIO/quasar-community, Apache-2.0)
多租户模型支持多成员组织，每个组织可创建多个应用单租户模式：单一管理员账户
后台登录方式支持 SIWX 钱包签名登录与通行密钥 (Passkey)在 Payload 管理后台 (/admin) 使用邮箱、密码与 TOTP 双因素认证登录
配额管理按组织计量；公开测试期间免费，每个组织享有 1,000 免费配额单位默认配额上限极高，不会限制单节点的正常使用
RPC 节点提供方必须配置您自己的节点：在每个应用的设置中填入自定义 RPC、Alchemy 密钥或 QuickNode 密钥使用您自己的节点，支持由运维人员配置全局备用密钥与公共节点
邮件通知提供引导邮件与配额不足预警邮件不发送邮件

Quasar Cloud 目前处于公开测试阶段且完全免费：暂不提供付费配额购买，公测期间其功能、限制及免费额度可能会有所调整。社区版不包含 SIWX 登录、Passkey、事务性邮件、计费系统与客户门户。如需将组织及其密钥、历史数据从 Quasar Cloud 迁移至您自己的节点，请参阅 从 Quasar Cloud 迁移至社区版；如需从零搭建节点，请参阅 私有化自部署指南.

哪种部署方案最适合您的技术栈

  • Serverless 或边缘计算后端（Vercel、Cloudflare Workers）： 推荐使用 Quasar Cloud。在无服务器函数内部等待 13–15 秒的 Solana finalized 确认或 EVM 区块确认会白白消耗计费时长并面临超时风险，而为小型 Serverless 团队单独维护整套 Quasar 社区版 Docker 栈（NestJS、BullMQ、Redis、Payload）又过于繁重。使用 Quasar Cloud 时，您的路由处理器只需发起一次 quasar.pulsar.syncCreate 调用即可立即返回，待交易达成 finalized 或过期时直接接收签名 Webhook。
  • 自有数据库 + 自定义后台 Worker 或定时任务（不使用 Quasar）： 如果您只需要在自己的定时任务或后台进程中运行链上拉取与最终性/过期轮询循环，可以直接从 @tuwaio/pulsar-solana（solanaFetcher + initializePollingTracker）或 @tuwaio/pulsar-evm 导入独立的无头追踪器——这两个包均不依赖 React、浏览器或 localStorage。
  • 自有服务器基础设施： 当您希望在自己的 VPS 或物理服务器上拥有完整的交易索引引擎、跨设备历史 API、Webhook 投递队列以及管理后台时，请通过 Docker Compose 运行 Quasar 社区版。

📚 下一步阅读

最后更新于
应用与密钥管理