xl1-patterns

XL1 设计模式

此技能提供规范性的配方式模式，用于在 XL1 上构建常见的应用功能。较低层介绍 XL1 是什么，而这一层介绍 如何基于它构建内容。

规则归属。 以下条目概述了链接文件中完整陈述的规则。链接文件是权威来源：如果此处的摘要与文件内容有任何不一致，应以文件为准，并指出这一偏差，而不是默默调和两者。

技能标识。 此技能的版本在本文件的 frontmatter 中通过 metadata.version 指明。每当你提供计划、确认或完成摘要时，都应说明哪些技能为其提供了依据，格式为 <skill-name> v<version>——版本应从本文件的 frontmatter 中读取，切勿从示例中获取。当此插件中的多个技能处于启用状态时，可以逐一列出。

技能层级

这是 XYO 技能栈的 第 5 层：xy-development (1) → xy-toolchain (2) → xyo-knowledge (3) → xl1-knowledge (4) → xl1-patterns (5) → xl1-dapp-kit (6) → xl1-testing (7) → xl1-scaffold (8) → xl1-build (9)。

• 基于： xl1-knowledge (4) — 链数据模型、数据湖、网关（通用、浏览器和 Node）；xyo-knowledge (3) — 载荷、绑定见证、模块、身份；来自 ariestools-skills (1–2) 的 xy-toolchain 和 xy-development — 构建工具、ESLint、TypeScript 配置、Vitest；编码规范、Git、测试、工作流
• 交由以下技能处理： xl1-dapp-kit (6) — 使用 @xyo-network/dapp-kit* 时（无头运行时、应用端口、效果日志与恢复、托管）；xl1-testing (7) — 验证工作（无头测试网、本地区块链、浏览器模式），并在报告完成前核对 dApp 完成定义；xl1-scaffold (8) — 开始新的 XL1 项目时；xl1-build (9) — 构建请求仍不明确时

载荷架构与哈希前提

调整配方前，请阅读 载荷架构演进与身份：稳定的 ASCII 架构名称、明确支持版本和形状、经过冻结且有意封闭的定义，以及用于新应用引用和承诺的根哈希。现有的协议专用数据哈希算法仍是约定；文档中记录的例外并不意味着新应用默认应使用数据哈希。

目录

架构原则

设计或审查任何状态对多方都有影响的 XL1 dApp 时（游戏、市场、拍卖、注册表、排行榜），无论是否使用 dapp-kit，都应先阅读此文。 内容包括七项原则（dApp 是引擎，每个界面都是客户端；状态是锚定证据；书面协议；作为绑定协议角色的运营方；从索引加载，而非重放；索引的成本恒定；索引答案易于验证）、工作者权限与协调、横切规则、信任表和审查问题。分配工作者角色或选择任务发现、并发、恢复或协调机制时，还应查阅采用的修订版本中包含的横切技能 ariestools-architecture；该技能的可用性及其在 XL1 中的具体应用说明见工作者权限与协调。

浏览器 UX

所有带 UI 的 dApp 都必须阅读——而这几乎涵盖了所有 dApp。介绍钱包连接生命周期（ConnectAccountsStack 及其 slot 属性）、通过 onAccountsChanged（而非兼容性接口 onAccountConnected）将已授权账户提升到应用状态、useConnectAccount 单例陷阱、感知能力的组件（已授权账户加上具备写入能力的 runner）、dApp UI 结构和显示约定（哈希／地址截断、复制到剪贴板）。这是构建 浏览器网关 之上的 UX 层。只有在工作确实不涉及 UI 时才可跳过（例如纯索引器服务或 CLI）。

钱包

当 dApp 需要向 XL1 浏览器钱包请求 ConnectAccountsStack 默认处理范围之外的权限时阅读——或者当你想请求“datalake 权限”并需要了解为什么这不是正确做法时阅读。文档介绍了 5 个已注册的 RPC 权限：2 个公开支持的账户方法，它们共享一项授权（请求 xyoWallet_getAccounts；它同时涵盖 xyoSigner_address）；xyoSigner_sign 上的实验性自动签名权限；以及禁止使用 xyoDataLakes_* 的硬性规定（仅供内部使用，包括 SDK 的 DataLake* 组件）。还介绍了用于绕过 ConnectAccountsStack 的 SDK 钩子（useGrantedAccounts、RequestPermissionsButton、usePermissions）。

浏览器 ↔ 服务接线

当 dApp 同时包含 React 应用和配套 HTTP 服务时必须阅读（默认的 monorepo 流程）。文档说明了规定的端口配对（应用 :3000，服务 :3001）、/api/* 基础路径约定、保持所有内容同源的 Vite 开发代理，以及生产环境下单域名反向代理的方案。默认采用同源意味着服务上无需 CORS 中间件。文档也介绍了确实需要跨域布局时的备用方案，但这属于例外情况。只有在没有服务时才可跳过（例如纯只读 React 应用，或没有 UI 的纯服务项目）。

链上数据索引——按角色划分

这是该层中第一个遵循协议／客户端／服务拆分的模式。先阅读协议文件，再阅读与你正在构建的内容对应的角色文件。

链上数据索引——协议

介绍检索、筛选和监听特定于应用的链上数据的概念性规则——模式、锚定选择（Path A/B/C）、Destination as Protocol（哨兵地址）、4 种扫描策略，以及 finalized 与 latest 的语义。与环境无关；客户端和服务都会依赖它。

链上数据索引——客户端

浏览器端读取——但仅适用于临时、单用户、简单的场景。介绍用于轮询读取的 useChainData 钩子方案（由你自行编写的代码，并非 SDK 导出）、组件中的能力检测，以及明确划定哪些内容适合或不适合放在浏览器中。任何多用户、持久化或需要处理重组的场景都应改用服务文件。

链上数据索引——服务

长时间运行的索引器服务。介绍进程模型（同步／持久化／服务循环）、状态持久化和原子检查点、重启恢复语义、通过 HTTP API 暴露结果、签名者索引器和持久提交，以及部署形态（进程监管、单实例、/api/healthz、从环境变量读取网络配置）。

提交-揭示原语

构建多方同时决策且先看到他人选择会有失公平的功能时阅读。介绍两阶段提交-揭示工作流、提交和揭示的模式设计、链上记录、哈希验证及超时处理。

页面内数据湖

当你的 React dApp 需要只读访问链上数据，且无需连接钱包时阅读。介绍页面内网关架构（通过 gateways.inPageGateway 进行公共读取，因为只要钱包已安装，defaultGateway 就是钱包的网关）、如何从 React 组件查询数据湖，以及如何将只读访问与钱包授权写入结合起来。

Commit-Reveal 预测市场

当你要构建游戏、预测市场，或任何具有质押、提交、揭示、结算生命周期的应用时阅读。这是一种组合模式，将 commit-reveal、链上数据索引和页面内数据湖结合成一套完整方案。使用 nbf/exp 有效期窗口、配置的 outcomeAuthorities、精简的结算载荷，以及各阶段之间的 $sources 关联。

原子交换

当两个或多个参与方需要原子交换资产时阅读——除非每一方都已不可撤销地承诺，否则任何一方都无法得到想要的资产。这是 XYO/XNS 托管流程面向 dApp 的投影：多方配对密钥、多签名者 BoundWitness、可配置的估价与收据授权方列表、精简的结果载荷，以及一条严格规则：缺少揭示会阻止结算（而非导致没收）。将 commit-reveal 组合为资产释放的门控机制，而不是隐藏选择协议。

铭文基底

当你的应用需要在 XL1 上拥有持久、可转移、归属明确的对象——相当于 Bitcoin 的 Ordinals——时阅读。介绍制品与事件的区分、内容寻址的铭文 ID、单步签名转移、仅重放最终确定事件的索引器，以及所有权账本推导。更高层协议（同质化代币、集合、递归内容）都构建于此基底之上。

同质化代币（XRC-20）

当你要在 XL1 上构建类似 Bitcoin BRC-20 的同质化代币时阅读，包括开放式代币代码注册、限额铸造、地址间转移，以及根据链上事件生成的链下账本。直接构建于铭文基底之上。介绍部署／铸造／转移架构、双遍索引器、规范排序规则，以及与 BRC-20 两步转移机制的有意差异。

声明图

当你需要在 XL1 上构建可重放、带来源归属的关系／断言图（绑定、授权、批准、成员资格）时阅读。生命周期封闭（一个承载 { source, subject, hashes } 的 network.xyo.statement.claim）＋开放的产品词汇；Fold 4 没有撤销动词，并要求每个被声明的对象都位于该声明自身的交易中。它与铭文基底并列——不用于类似 NFT 的托管。

经过身份验证的唤醒投递

当可休眠的索引器／主机必须由钱包 JWT 发布者唤醒，且这些发布者已获 Statement Graph 授权并订阅了有效的 D-005 握手时阅读——而不是使用 HMAC Webhook。Event Kit 2.2.x（Node ≥ 26）：最终确定的 XL1／最终确定的 Ethereum／UTC 间隔来源、明确的 durable／best-effort 投递方式、有效来源准入、wakeId 与 jti 的区别，以及 WakeQueue 租约。唤醒用于安排工作；它们并非链上事实。

dApp 完成验收清单（位于 xl1-testing 中）

在报告任何 XL1 dApp 工作已完成之前，必须执行——上述每种模式的完成门槛均由 xl1-testing（第 7 层）负责；请逐项检查，并按相关章节报告通过／未通过。