Skip to Content
指南概览

架构蓝图与深度工程指南

各个独立包的文档站点提供了函数级的细粒度 API 参考，而本指南中心则专注于高阶 Web3 系统架构、生产环境实战模式与端到端集成配方。

当分布式账本的真实复杂性遇上天真的前端假设时，Web3 工程往往会崩溃：内存池拥堵、动态 Gas 飙升、Nonce 丢失、加速与取消替换、后台标签页节流以及 React 组件卸载。这里的架构蓝图通过本地优先 (Local-First)、无头解耦 (Headless) 与非托管自持密钥 (Self-Custodial) 的设计模式彻底解决这些系统性难题。

面向开发者与 AI 智能体的权威技术规范
如需查阅贯穿整个 TUWA 生态的底层系统设计准则、严格的包隔离边界、跨层接口契约以及 AI 智能体行为约束，请参阅 workflows/TUWA_AGENTS.md。它是人类工程师与自主编程智能体共同遵循的唯一架构事实来源。

深度工程剖析

围绕现代 dApp 系统性痛点的深度架构拆解与工程方案：

🔐 基于 SIWX 的多链身份认证（以 CAIP-122 打破 EVM 孤岛）

深入解析为何 EIP-4361 无法满足现代多链应用、CAIP-122 如何将 EVM 与 Solana 认证统一到同一密码学边界内，以及如何实现带防重放保护的无状态加密验证会话。

  • 核心议题： CAIP-122 协议、跨链会话同步、EIP-191/1271 与 ed25519 签名验证。
  • 核心方案： 由 @tuwaio/siwx 驱动的通用多链身份认证。

⚡ 为什么 Web3 交易状态管理如此困难（以及为何 useState 是反模式）

深度剖析为何使用 React useState 建模链上写操作会导致组件卸载丢失状态、加速交易成为孤儿以及多标签页会话失步，并展示如何使用无头状态机与感知 Nonce 的生命周期追踪将执行逻辑与 UI 树彻底解耦。

  • 核心议题： 内存池机制、交易替换 (Speed-Up / Cancel)、跨标签页状态同步。
  • 核心方案： 由 @tuwaio/pulsar-core 驱动的解耦交易生命周期管理。

🛡️ 解密 ERC-4337：无需闭源 WaaS 的主权账户抽象

为什么账户抽象不需要依赖专有 WaaS 平台、替代内存池与 userOpHash → txHash 双阶段生命周期如何运作，以及如何结合 Solady、Orbit EVM、Pulsar 与 Quasar 构建 Gas 优化的自主权智能账户。

  • 核心议题： 标准 EntryPoint v0.7、Solady 反事实智能账户、Pimlico Bundler/Paymaster RPC、两阶段 UserOp 追踪。
  • 核心方案： 由 @tuwaio/orbit-evm、@tuwaio/pulsar-core 与 Quasar 驱动的 Gas 赞助主权智能账户。

分步实战教程

串联多个 TUWA 软件包的动手实践教程：

🧭 使用 Pulsar 在 React 中追踪交易

为 EVM 或 Solana 钱包在 React 应用中接入 Pulsar：持久化到 localStorage 的交易仓库、链适配器、页面刷新后自动恢复追踪，以及发起受追踪合约/程序调用的按钮（含可选的 ERC-4337 智能账户变体）。

  • 涉及包： @tuwaio/pulsar-core、@tuwaio/pulsar-evm 或 @tuwaio/pulsar-solana、@tuwaio/pulsar-react、Nova Connect。

🧱 使用 TUWA SDK 构建全栈 React 应用

基于 @tuwaio/sdk 构建支持 EVM 或 Solana 的 Next.js 应用：Nova Connect 钱包连接弹窗、带服务端会话的 SIWX 登录、配备 Nova Transactions 弹窗与通知提示的 Pulsar 交易仓库，以及可识别当前登录钱包的 Server Action。

  • 涉及包： @tuwaio/sdk、@tuwaio/evm-sdk 或 @tuwaio/solana-sdk。

☁️ 将交易同步至 Quasar

承接全栈应用教程：在校验 SIWX 会话后调用 Quasar 的 Server Actions、自动同步每笔新交易的 Pulsar 仓库，以及在 Nova 弹窗中展示跨设备历史记录。

  • 涉及包： @tuwaio/quasar-sdk、@tuwaio/sdk。

🔑 通过 JWT 与 JWKS 将 SIWX 登录凭证传递给外部认证服务

为已通过 SIWX 登录的钱包签发短期 JWT 并暴露用于验签的 JWKS 公钥端点，使 Coinbase CDP 自定义认证、其他嵌入式钱包服务商及您自己的后端微服务共享同一套登录信任链。

  • 涉及包： @tuwaio/sdk (/siwx/server, /siwx/server-next)、@coinbase/cdp-hooks。

🗄️ 将 SIWX 登录与 Supabase 行级安全策略 (RLS) 结合使用

配置 Supabase 将 SIWX 令牌作为第三方认证信任源，基于钱包地址编写 Row Level Security 策略使每个钱包仅能读写自己的数据行，并在浏览器与 Server Actions 中通过 supabase-js 发送令牌。

  • 涉及包： @tuwaio/sdk (/siwx, /siwx/server, /siwx/server-next)、@supabase/supabase-js。

🚀 启动模板 (Starter Templates)

来自 Cosmos Playground 的完整 Next.js 与 Vite 模板应用——钱包连接、交易追踪、SIWX 登录与 Quasar 同步均已预配置就绪——以及一键创建项目的 CLI 工具。

软件包 API 参考文档

正在寻找各个软件包的细粒度 API 参考、Hook 签名、类型定义或安装说明？

所有独立软件包文档空间（@tuwaio/siwx、@tuwaio/orbit、@tuwaio/satellite、@tuwaio/pulsar、@tuwaio/nova-uikit、@tuwaio/sdk 与 @tuwaio/quasar-sdk）均已索引在 主屏幕 (Main Screen) 上。访问主门户即可浏览完整的交互式分层路线图并直达指定包的文档。

关于 Quasar 的应用与密钥、配额、Webhook、社区版私有化部署以及 HTTP API 参考，请查阅本中心的 Quasar 专区。

核心架构原则

本仓库中的每一份架构蓝图均严格遵循三项不可妥协的工程准则：

  1. 自托管与主权架构 (Self-Custodial & Sovereign)： 前端始终保持非托管属性，绝不强制捆绑闭源专有的钱包即服务 (WaaS) 平台。客户端应用保有高可用的本地优先状态，并可按需接入 Quasar 实现跨设备索引、Webhook 投递与服务端编排——无论是使用托管云还是开源自部署的社区版 (Apache-2.0)，都绝不触碰用户私钥。
  2. 无头关注点分离 (Headless Separation of Concerns)： 核心业务逻辑沉淀在框架无关的状态仓库 (satellite、pulsar) 与底层协议适配器 (orbit) 中；表现层则位于可随时替换的 UI 视图 (nova) 中。修改 UI 样式绝不会影响底层 Web3 状态机的稳定性。
  3. 严格类型安全与零体积膨胀 (Strict Type Safety & Zero Bloat)： 对 any 类型、旧版 @solana/web3.js v1 捆绑包或庞大的 ethers.js 零容忍。全线仅采用现代化、支持 Tree-Shaking 的高性能原语（viem、@solana/kit）。
最后更新于
基于 SIWX 的多链身份认证