xl1-knowledge

XL1 区块链知识

此技能介绍 XL1 区块链（XYO Layer One）——一个面向数据、专为高吞吐量数据应用设计的 Layer 1。XL1 在 XYO 协议的基础上扩展了区块链原语：区块、交易、费用、质押和共识。

需要查询精确的类型定义时，请安装相关的 @xyo-network/xl1-* 软件包，并查看 dist/neutral/index.d.ts 中的 TypeScript 声明。XL1 Protocol Yellow Paper 提供了完整的协议规范。

技能标识。 此技能的版本在本文件 frontmatter 的 metadata.version 中公开。每当你提供计划、确认或完成摘要时，请注明所依据的技能，并按 <skill-name> v<version> 格式列出——请从本文件的 frontmatter 读取版本，切勿使用示例中的版本。此插件中有多个技能处于启用状态时，可逐一列出。

技能层级

这是 XYO 技能栈的 第 4 层：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）。

• 基于： xyo-knowledge（3）——协议原语（载荷、绑定见证、模块、账户、钱包）；来自 ariestools-skills（1–2）的 xy-toolchain 和 xy-development——构建工具（@ariestools/toolchain、ESLint、TypeScript 配置、Vitest）和编码规范（TypeScript、Git、测试、工作流）
• 后续交接给： xl1-patterns（5）——构建应用功能时，包括 Statement Graph（仅追加的签名关系声明，@xyo-network/xl1-statement-graph-*）以及其他非核心链的应用底层；xl1-dapp-kit（6）——采用可移植的无头应用契约（@xyo-network/dapp-kit*）时；xl1-testing（7）——针对本地区块链或 Sequence 验证链交互时；xl1-scaffold（8）——启动新的 XL1 项目时

载荷架构和身份规则

定义载荷或选择身份／承诺哈希之前，请阅读载荷架构演进与身份。新的架构名称必须使用严格的 ASCII 片段，且不得带结构化版本后缀；$version 是经过验证的元数据；根哈希是应用默认值。保留已发布的协议哈希契约，不要让未经身份验证的 BoundWitness 版本决定共识或签名规则。

重要：切勿发起原始 RPC 调用

XL1 网关只能通过 SDK 访问。以下两条规则适用于所有会访问链的代码——dApp、服务、索引器、测试、验证脚本：

1. 切勿按名称调用 XL1 JSON-RPC 方法（blockViewer_blocksByNumber、transactionViewer_byHash 以及任何其他 <viewer>_<method> 组合——无论是通过对 /rpc 发起原始 fetch，还是使用手写的 JSON-RPC 客户端）。读取请通过 gateway.connection.viewer.*，写入请使用网关方法。
2. 切勿对 XL1 使用 Ethereum RPC 方法（eth_getBalance、eth_blockNumber、eth_call、eth_sendTransaction、personal_sign 等）或 Ethereum SDK（ethers、viem、web3.js）。XL1 不是 EVM 链。XL1 与 Ethereum 唯一共享的是通过 BIP44 派生实现的地址兼容性。

有关原因、每个 Ethereum 方法在 XL1 中的对应方法，以及用于检查「完成」状态的结构化 grep 自检，请参阅网关 — 切勿发起原始 RPC 调用。对于 dApp，xl1-testing 中的完成门槛也会执行同样的检查：dApp 完成定义 — 网关与链访问。

目录

XL1 链

处理 XL1 区块链概念时阅读 — 区块、交易、费用、奖励、节点类型或共识。介绍链数据模型，以及 XL1 如何扩展 XYO 的 BoundWitness/Payload 原语。

XL1 开发

在 XL1 上构建应用或服务时阅读。介绍 Zod 优先的类型模式、Viewer/Runner 架构、提供方（包括 providerId 身份、MissingProviderIdError 和 UnknownProviderError 针脚）、验证以及 SDK 包结构。

身份与钱包

在 XL1 后端代码（Node 服务、索引器、CLI、测试）中创建钱包或签名者时阅读。介绍规范的 generateXyoBaseWalletFromPhrase + derivePath('<index>') 模式、与 MetaMask 和 XYO 浏览器扩展的跨环境兼容性保证，以及结果为 AccountInstance 这一规则；需要具备写入能力的 Runner 时，可直接将其传给 GatewayBuilder.account(...)。

数据湖

处理 XL1 链数据存储（归档、查询或配置存储后端）时阅读。介绍 DataLake 抽象及其如何基于 XYO Archivists 构建，并列出面向运营方的驱动程序和 S3 提供方包。

网关

连接 XL1 链时阅读 — 通用网关概念、Viewer API、网络（包括 REST 根路径）、交易提交（选项、确认，以及使用分阶段 buildXl1Transaction … observeXl1TransactionFinality 函数实现的崩溃安全持久提交）、传输方式以及如何运行网关节点。特定环境的构建方式位于两个同级文件中。

浏览器网关

将 XL1 集成到任何网站时阅读 — React dApp、普通页面、Worker、Service Worker 和浏览器扩展。@xyo-network/xl1-browser-system 是首选集成基础，REST 是首选传输方式；React dApp 通过 InPageGatewaysProvider 和 transport="rest" 接入，而非直接启动浏览器系统。还介绍 Chrome 钱包扩展、WalletGatewayProvider / GatewayProvider 和 useProvidedGateway。基于网关构建的 UX 模式见 浏览器 UX。

Node 网关

在任何非浏览器环境中构建网关时阅读 — 后端服务、索引器、CLI、定时任务、测试以及 dApp 的无头验证。介绍规范的 GatewayBuilder 入口（只读和可写）、自有网关会话（buildSession() / buildRunnerSession() 和用于干净关闭的 stop()）、助记词签名者模式、惰性 Promise 缓存模式，以及 basicRemoteViewerLocator 后备方案。

已定稿区块流

索引器或服务需要按顺序接收已定稿数据时阅读（FinalizedBlockStream / finalizedBlockStreamFromGateway）；优先使用它，而非已弃用的 headUpdated。此内容是网关的一节。